diff --git a/app/Http/Controllers/Barobill/BarobillController.php b/app/Http/Controllers/Barobill/BarobillController.php index aeb61658..20f1305f 100644 --- a/app/Http/Controllers/Barobill/BarobillController.php +++ b/app/Http/Controllers/Barobill/BarobillController.php @@ -16,6 +16,18 @@ */ class BarobillController extends Controller { + /** + * 바로빌 개발문서 페이지 + */ + public function devGuide(Request $request): View|Response + { + if ($request->header('HX-Request')) { + return response('', 200)->header('HX-Redirect', route('barobill.dev-guide.index')); + } + + return view('barobill.dev-guide'); + } + /** * 바로빌 설정 페이지 * HTMX 요청 시 전체 페이지 리로드 (스크립트 로딩을 위해) diff --git a/resources/views/barobill/dev-guide.blade.php b/resources/views/barobill/dev-guide.blade.php new file mode 100644 index 00000000..5293347e --- /dev/null +++ b/resources/views/barobill/dev-guide.blade.php @@ -0,0 +1,975 @@ +@extends('layouts.app') + +@section('title', '바로빌 개발문서') + +@section('content') +
+ + {{-- 페이지 헤더 --}} +
+
+ 바로빌 + + + + 개발문서 +
+

바로빌 연동 개발문서

+

SAM에서 바로빌 API를 통해 연동하는 서비스 현황과 기술 가이드

+
+ + {{-- 목차 --}} +
+

📋 목차

+ +
+ + {{-- 본문 섹션들 --}} +
+ + {{-- 섹션 1: 바로빌이란? --}} +
+
+
+
1
+

바로빌이란?

+
+ +
+

바로빌(BaroBill)은 전자세금계산서, 카카오톡 알림톡, 계좌조회, 카드내역 등 다양한 비즈니스 서비스를 API로 제공하는 플랫폼입니다.

+ +
+

SAM에서 바로빌을 쓰는 이유

+
    +
  • + • + 전자세금계산서 — 세금계산서를 SAM 안에서 바로 발행하고 국세청에 전송 +
    • +
  • + • + 카카오톡 알림톡 — 전자계약 서명 요청 등 중요 알림을 카카오톡으로 자동 발송 +
    • +
  • + • + 계좌 입출금 조회 — 법인 계좌의 입출금 내역을 자동으로 수집/조회 +
    • +
  • + • + 법인카드 사용내역 — 법인카드 사용 내역을 자동으로 수집/조회 +
    • +
  • + • + 홈텍스 매입/매출 — 국세청 홈텍스 데이터를 자동으로 수집 +
    • +
+
+ +
+

+ 개발자 센터: + https://dev.barobill.co.kr/ + — API 문서, 테스트 도구, 에러코드 참조 +

+
+
+
+
+ + {{-- 섹션 2: 우리가 쓰는 서비스 --}} +
+
+
+
2
+

우리가 쓰는 서비스

+
+ +
+ {{-- 전자세금계산서 --}} +
+
+
+ +
+

전자세금계산서

+
+

세금계산서 발행 · 국세청 전송 · 상태 조회

+ TI.asmx +
+ + {{-- 카카오톡 --}} +
+
+
+ +
+

카카오톡

+
+

알림톡 · 친구톡 · SMS 대체발송

+ KAKAOTALK.asmx +
+ + {{-- 계좌조회 --}} +
+
+
+ +
+

계좌조회

+
+

입출금 내역 수집 · 잔액 조회 · 인증서 관리

+ BANKACCOUNT.asmx +
+ + {{-- 카드내역 --}} +
+
+
+ +
+

카드내역

+
+

법인카드 등록 · 사용내역 수집 · 카드사 조회

+ CARD.asmx +
+ + {{-- 홈텍스 --}} +
+
+
+ +
+

홈텍스 매입/매출

+
+

국세청 매입/매출 데이터 자동 수집

+ CORPSTATE.asmx +
+
+
+
+ + {{-- 섹션 3: 서비스별 상세 --}} +
+
+
+
3
+

서비스별 상세

+
+ +
+ {{-- 전자세금계산서 --}} +
+ +
+ 1 + 전자세금계산서 + 운영중 +
+ + +
+

SAM에서 거래처에 세금계산서를 발행하고, 바로빌 API를 통해 국세청에 자동 전송합니다.

+
+

처리 흐름

+
+ SAM에서 발행 + → + 바로빌 API 전송 + → + 국세청 전송 + → + 전송 완료 +
+
+
+

SOAP 서비스: TI.asmx | 주요 메서드: RegistAndIssueTaxInvoice, CancelTaxInvoice, GetTaxInvoiceState

+

상태 흐름: DRAFT → ISSUED → SENT (국세청 전송 완료)

+
+
+
+ + {{-- 카카오톡 알림톡/친구톡 --}} +
+ +
+ 2 + 카카오톡 알림톡 / 친구톡 + 운영중 +
+ + +
+

전자계약 서명 요청, 리마인드 등 중요한 알림을 카카오톡으로 발송합니다.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
구분알림톡친구톡
용도정보성 메시지 (계약 알림 등)광고성 메시지
수신 대상모든 카카오톡 사용자채널 친구 추가자만
템플릿필수 (카카오 사전 승인)불필요 (자유 작성)
비용건당 8~9원건당 15~20원
SMS 대체발송지원지원
+
+ +
+

카카오톡 채널 정보

+

채널명: (주)코드브릿지엑스 | 채널ID: @codebridge

+
+
+
+ + {{-- 계좌조회 --}} +
+ +
+ 3 + 계좌조회 (입출금 내역) + 운영중 +
+ + +
+

법인 계좌를 등록하면, 바로빌이 자동으로 입출금 내역을 수집합니다. SAM에서는 이 데이터를 조회하여 재무관리에 활용합니다.

+
+

주요 기능

+
    +
  • • 계좌 등록/관리 (바로빌 페이지로 이동)
    • +
  • • 일별/월별/기간별 입출금 내역 조회
    • +
  • • 공동인증서 등록 및 유효성 관리
    • +
  • • 충전 잔액 확인
    • +
+
+

SOAP 서비스: BANKACCOUNT.asmx | 37개 은행 코드 지원

+
+
+ + {{-- 카드내역 --}} +
+ +
+ 4 + 법인카드 사용내역 + 운영중 +
+ + +
+

법인카드를 등록하면, 바로빌이 카드 사용 내역을 자동으로 수집합니다. 16개 카드사를 지원합니다.

+
+

주요 기능

+
    +
  • • 카드 등록/수정/해지 관리
    • +
  • • 일별/월별/기간별 사용내역 조회
    • +
  • • 카드 스크랩 신청 (바로빌 페이지)
    • +
+
+

SOAP 서비스: CARD.asmx | 16개 카드사 지원 (비씨, 삼성, 신한 등)

+
+
+ + {{-- 홈텍스 --}} +
+ +
+ 5 + 홈텍스 매입/매출 + 운영중 +
+ + +
+

국세청 홈텍스의 매입/매출 세금계산서 데이터를 자동으로 수집하여 SAM에서 조회할 수 있습니다.

+
+

주요 기능

+
    +
  • • 매입/매출 세금계산서 자동 수집
    • +
  • • 홈텍스 관리 페이지 연동 (바로빌 URL)
    • +
  • • 공동인증서 기반 인증
    • +
+
+

SOAP 서비스: CORPSTATE.asmx | 인증서 관리 포함

+
+
+
+
+
+ + {{-- 섹션 4: 카카오톡 알림톡 흐름 --}} +
+
+
+
4
+

카카오톡 알림톡 흐름

+
+ +

전자계약 서명 요청 시 알림톡이 발송되는 과정입니다.

+ + {{-- 플로우차트 --}} +
+ 
+┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐     ┌──────────────┐
+│  SAM 전자계약  │────▶│  EsignApiController │────▶│  BarobillService   │────▶│  바로빌 서버  │
+│  서명 요청     │     │  sendAlimtalk()    │     │  sendATKakaotalkEx │     │  SOAP API    │
+└─────────────┘     └─────────────────┘     └──────────────────┘     └──────┬───────┘
+                                                                              │
+                     ┌─────────────────┐     ┌──────────────────┐            │
+                     │  수신자 카카오톡   │◀────│  카카오 서버       │◀───────────┘
+                     │  알림톡 수신      │     │  메시지 전달       │
+                     └─────────────────┘     └──────────────────┘
+
+ + {{-- 2단계 검증 --}} +
+

⚠️ 2단계 검증 (필수)

+
+

알림톡 발송은 SendKey 반환 ≠ 전달 성공입니다. 반드시 2단계 검증이 필요합니다:

+
+ 1. SendATKakaotalkEx 호출 + → + SendKey 수신 + → + 2. 3초 대기 + → + 3. GetSendKakaotalk 호출 + → + ResultCode 확인 +
+

ResultCode=1: 성공 | ResultCode=4: 템플릿 불일치 | 기타: 실패

+
+
+ + {{-- 등록된 템플릿 --}} +
+

등록된 알림톡 템플릿

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
템플릿명운영개발용도
전자계약_서명요청전자계약_서명요청전자계약_서명요청_DEV서명 요청 알림
전자계약_완료전자계약_완료전자계약_완료_DEV서명 완료 알림
전자계약_리마인드전자계약_리마인드전자계약_리마인드_DEV미서명 독촉 알림
+
+ +
+

템플릿 자동 분기: APP_ENV=production이면 원본 템플릿, 그 외에는 _DEV 접미사 자동 추가

+
+
+
+ + {{-- 섹션 5: 과금 구조 --}} +
+
+
+
5
+

과금 구조

+
+ +

바로빌 서비스는 월정액 + 건별 과금 구조로 운영됩니다.

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
서비스과금 방식무료 구간초과 요금
전자세금계산서건별100건/월 무료50건 단위 5,000원
계좌조회월정액1개 계좌 무료추가 계좌당 월 10,000원
카드내역월정액5장 무료추가 카드당 월 5,000원
홈텍스월정액—본사 부담 (무료)
카카오톡 알림톡건별 (바로빌 직접 과금)—건당 8~9원
+
+ +
+

참고: 과금 정책은 DB(barobill_pricing_policies 테이블)에서 관리되며, DB에 없으면 위의 기본값이 적용됩니다. 매월 1일 자동 과금 처리가 실행됩니다.

+
+
+
+ + {{-- 섹션 6: 시스템 구조 (개발자용) --}} +
+
+
+
6
+

시스템 구조 (개발자용)

+
+ +
+ {{-- API 통신 방식 --}} +
+

API 통신 방식

+
+ + + + + + + + + + + + + + + + + + + + +
프로젝트프로토콜용도
MNG (관리자)SOAP/WSDL계좌, 카드, 카카오톡, SMS, 회원관리
API (백엔드)REST세금계산서 발행, 사업자번호 검증
+
+
+ + {{-- SOAP WSDL 엔드포인트 --}} +
+

SOAP WSDL 엔드포인트

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
서비스테스트 서버운영 서버
회원관리testws.baroservice.com/CORPSTATE.asmxws.baroservice.com/CORPSTATE.asmx
세금계산서testws.baroservice.com/TI.asmxws.baroservice.com/TI.asmx
계좌조회testws.baroservice.com/BANKACCOUNT.asmxws.baroservice.com/BANKACCOUNT.asmx
카드조회testws.baroservice.com/CARD.asmxws.baroservice.com/CARD.asmx
카카오톡testws.baroservice.com/KAKAOTALK.asmxws.baroservice.com/KAKAOTALK.asmx
문자(SMS)testws.baroservice.com/SMS.asmxws.baroservice.com/SMS.asmx
+
+
+ + {{-- 테스트/운영 환경 분리 --}} +
+

테스트/운영 환경 분리

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
환경APP_ENV바로빌 서버도메인
로컬 (Docker)localtest / productionmng.sam.kr
개발 서버localtest / productionadmin.codebridge-x.com
운영 서버productionproductionmng.codebridge-x.com
+
+

+ server_mode는 barobill_members 테이블에서 회원사별로 관리됩니다. APP_ENV와 독립적으로 설정 가능합니다. +

+
+ + {{-- 응답 형식 --}} +
+

API 공통 응답 형식

+ 
{
+    "success": true|false,
+    "data": mixed,           // success=true
+    "error": "에러 메시지",    // success=false
+    "error_code": -11102     // 에러 코드
+}
+
+
+
+
+ + {{-- 섹션 7: 주요 테이블 --}} +
+
+
+
7
+

주요 테이블

+
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
테이블모델역할
barobill_membersBarobillMember바로빌 회원사 정보 (사업자번호, 인증키, server_mode)
barobill_configsBarobillConfigSOAP 연동 설정 (DB 기반)
barobill_subscriptionsBarobillSubscription월정액 구독 관리 (계좌/카드/홈텍스)
barobill_billing_recordsBarobillBillingRecord건별/월정액 과금 기록
barobill_monthly_summariesBarobillMonthlySummary월별 과금 집계
barobill_pricing_policiesBarobillPricingPolicy서비스별 과금 정책 (무료건수, 단가)
hometax_invoicesHometaxInvoice세금계산서 내역 (매입/매출, 사용량 집계용)
+
+
+
+ + {{-- 섹션 8: API 엔드포인트 --}} +
+
+
+
8
+

API 엔드포인트

+
+ +
+ {{-- MNG 내부 라우트 --}} +
+

MNG 페이지 라우트

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodPath설명
GET/barobill/settings바로빌 설정
GET/barobill/members회원사 관리
GET/barobill/tax-invoice전자세금계산서
GET/barobill/bank-account계좌조회
GET/barobill/card-usage카드사용내역
GET/barobill/usage사용량 조회
GET/barobill/billing과금 관리 (본사 전용)
+
+
+ + {{-- 카카오톡 API --}} +
+

카카오톡 API 라우트

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodPath설명
GET/barobill/kakaotalk카카오톡 메인
GET/barobill/kakaotalk/guide카카오톡 사용법 가이드
POST/api/admin/barobill/kakaotalk/send-alimtalk알림톡 발송
POST/api/admin/barobill/kakaotalk/send-friendtalk친구톡 발송
+
+
+ + {{-- API 프로젝트 엔드포인트 --}} +
+

API 프로젝트 (REST)

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
기능메서드설명
사업자 검증checkBusinessNumber()사업자번호 유효성/휴폐업 조회
세금계산서 발행issueTaxInvoice()세금계산서 발행 (DRAFT → ISSUED)
세금계산서 취소cancelTaxInvoice()세금계산서 취소 (ISSUED → CANCELLED)
국세청 전송 확인checkNtsSendStatus()국세청 전송 상태 (ISSUED → SENT)
연동 테스트testConnection()바로빌 API 연결 테스트
+
+
+
+
+
+ + {{-- 섹션 9: 트러블슈팅 --}} +
+
+
+
9
+

트러블슈팅

+
+ +
+ {{-- 이슈 1: 2단계 검증 --}} +
+
+ 이슈 1 + SendKey 반환 ≠ 전달 성공 +
+
+

증상: SendATKakaotalkEx가 SendKey를 반환했지만, 수신자가 메시지를 받지 못함

+

원인: SendKey는 "바로빌 서버가 접수했다"는 의미일 뿐, 카카오 전달 성공을 보장하지 않음

+

해결: 반드시 3초 대기 후 GetSendKakaotalk()을 호출하여 ResultCode=1인지 확인

+
+
+ + {{-- 이슈 2: 템플릿 URL --}} +
+
+ 이슈 2 + 알림톡 템플릿 URL 정확 일치 +
+
+

증상: ResultCode=4 (템플릿 불일치) 오류 발생

+

원인: 버튼 URL이 등록된 템플릿과 정확히 일치해야 함 (경로, 쿼리 파라미터 추가 불가)

+

해결: 동적 URL이 필요하면, 템플릿에 #{변수}를 포함하여 카카오에 재등록

+
+
+ + {{-- 이슈 3: SmsReply 오류 --}} +
+
+ 이슈 3 + SmsReply='S' + 발신번호 누락 → -31325 오류 +
+
+

증상: 에러코드 -31325 발생

+

원인: SmsReply='S'(SMS 대체발송 사용)인데 SmsSenderNum이 비어있음

+

해결: SMS 메시지/발신번호가 비어있으면 SmsReply='N'으로 설정

+
+
+ + {{-- 이슈 4: 응답 타입 --}} +
+
+ 이슈 4 + SOAP 응답 타입 불일치 +
+
+

증상: 1건일 때는 정상, 여러 건일 때 에러 (또는 반대)

+

원인: SOAP 응답이 1건이면 stdClass 객체, N건이면 배열로 반환

+

해결: 응답을 받으면 is_array()로 타입을 확인한 후 처리

+
+
+ + {{-- 주요 에러 코드 --}} +
+

주요 에러 코드

+
+ + + + + + + + + + + + + + + + +
코드의미
-11101사업자번호 미설정 또는 유효하지 않음
-11102CERTKEY 유효하지 않음
-11103인증서 만료 또는 유효하지 않음
-11104등록되지 않은 사업자
-26001공동인증서 미등록
-31325SMS 발신번호 누락 (SmsReply 오류)
-32010이미 등록된 사업자번호
+
+
+
+
+
+ + {{-- 섹션 10: 관련 파일 경로 --}} +
+
+
+
10
+

관련 파일 경로

+
+ +
+ {{-- MNG 프로젝트 --}} +
+

MNG 프로젝트 (관리자)

+
+

서비스 app/Services/Barobill/BarobillService.php ← SOAP 클라이언트

+

서비스 app/Services/Barobill/BarobillBillingService.php ← 과금 처리

+

서비스 app/Services/Barobill/BarobillUsageService.php ← 사용량 집계

+

모델 app/Models/Barobill/*.php ← 6개 모델

+

컨트롤러 app/Http/Controllers/Barobill/*.php

+

뷰 resources/views/barobill/**/*.blade.php

+
+
+ + {{-- API 프로젝트 --}} +
+

API 프로젝트 (백엔드)

+
+

서비스 app/Services/BarobillService.php ← REST 클라이언트

+

모델 app/Models/BarobillSetting.php

+

모델 app/Models/TaxInvoice.php

+
+
+ + {{-- 문서 --}} +
+

문서

+
+

가이드 docs/features/barobill-kakaotalk/README.md

+

가이드 docs/features/barobill-kakaotalk/esign-notification-guide.md

+

정책 docs/rules/billing-policy.md

+
+
+
+
+
+ +
+ + {{-- 하단 빠른 바로가기 --}} +
+

바로 이동하기

+
+ 바로빌 설정 + 전자세금계산서 + 계좌조회 + 카드내역 + 사용량 조회 + 과금 관리 +
+
+ +
+@endsection diff --git a/routes/web.php b/routes/web.php index 5f537020..f496748e 100644 --- a/routes/web.php +++ b/routes/web.php @@ -48,6 +48,7 @@ use App\Http\Controllers\PostController; use App\Http\Controllers\ProfileController; use App\Http\Controllers\ProjectManagementController; +use App\Http\Controllers\RdController; use App\Http\Controllers\RoadmapController; use App\Http\Controllers\QuoteFormulaController; use App\Http\Controllers\RoleController; @@ -369,6 +370,14 @@ Route::get('/plans/{id}/edit', [RoadmapController::class, 'editPlan'])->name('plans.edit'); }); + // 연구개발 (Blade 화면만) + Route::prefix('rd')->name('rd.')->group(function () { + Route::get('/', [RdController::class, 'index'])->name('index'); + Route::get('/ai-quotation', [RdController::class, 'quotations'])->name('ai-quotation.index'); + Route::get('/ai-quotation/create', [RdController::class, 'createQuotation'])->name('ai-quotation.create'); + Route::get('/ai-quotation/{id}', [RdController::class, 'showQuotation'])->name('ai-quotation.show'); + }); + // 일일 스크럼 (Blade 화면만) Route::prefix('daily-logs')->name('daily-logs.')->group(function () { Route::get('/', [DailyLogController::class, 'index'])->name('index'); @@ -537,6 +546,7 @@ |-------------------------------------------------------------------------- */ Route::prefix('barobill')->name('barobill.')->group(function () { + Route::get('/dev-guide', [\App\Http\Controllers\Barobill\BarobillController::class, 'devGuide'])->name('dev-guide.index'); Route::get('/settings', [\App\Http\Controllers\Barobill\BarobillController::class, 'settings'])->name('settings.index'); Route::get('/members', [\App\Http\Controllers\Barobill\BarobillController::class, 'members'])->name('members.index'); Route::get('/tax-invoice', [\App\Http\Controllers\Barobill\BarobillController::class, 'taxInvoice'])->name('tax-invoice.index');