@extends('layouts.app') @section('title', '바로빌 개발문서') @section('content')
바로빌(BaroBill)은 전자세금계산서, 카카오톡 알림톡, 계좌조회, 카드내역 등 다양한 비즈니스 서비스를 API로 제공하는 플랫폼입니다.
SAM에서 바로빌을 쓰는 이유
개발자 센터: https://dev.barobill.co.kr/ — API 문서, 테스트 도구, 에러코드 참조
파트너사와 회원사 구조
바로빌
API 플랫폼
(주)코드브릿지엑스
파트너사 (본사)
주일 · 경동 · …
회원사 (테넌트)
새 회원사가 바로빌 서비스를 사용하려면 아래 단계를 순서대로 완료해야 합니다.
{{-- STEP 1: MNG에서 회원사 등록 --}}경로: SAM MNG → 바로빌 → 회원사관리 → 신규등록
회사 기본 정보(사업자번호, 상호명, 대표자명, 주소 등)와 바로빌 로그인 정보(아이디/비밀번호)를 입력하면, 바로빌 API(RegistCorp)를 통해 회원사가 자동 등록됩니다.
바로빌 사이트에서 직접 수행 — SAM 설정 페이지에서 "공동인증서 등록" 버튼 클릭 시 바로빌 사이트로 이동
해야 할 일:
바로빌 사이트에서 직접 수행 — 입출금 내역을 자동 수집하려면 은행 계좌를 등록해야 합니다.
해야 할 일:
37개 은행 지원 (국민, 신한, 우리, 산업, 하나 등)
바로빌 사이트에서 직접 수행 — 법인카드 사용 내역을 자동 수집하려면 카드를 등록해야 합니다.
해야 할 일:
16개 카드사 지원 (비씨, 삼성, 신한, 현대 등)
경로: SAM MNG → 바로빌 → 설정 → 서비스 이용 설정
| 서비스 | 사전 조건 | 설정 항목 |
|---|---|---|
| 전자세금계산서 | 공동인증서 등록 필수 | use_tax_invoice 체크 |
| 계좌조회 | 은행 계좌 등록 완료 | use_bank_account 체크 |
| 카드사용내역 | 법인카드 등록 완료 | use_card_usage 체크 |
| 홈텍스 매입/매출 | 공동인증서 등록 필수 | use_hometax 체크 |
담당자 이름, 연락처, 이메일도 이 단계에서 설정합니다 (세금계산서 알림 수신용).
바로빌 API 호출은 선불 충전 방식입니다. 잔액이 부족하면 계좌조회/카드내역 수집이 중단됩니다.
확인 방법:
회원사 설정 체크리스트
☐ MNG에서 회원사 등록 (사업자번호, 바로빌 ID/PW)
☐ 공동인증서 등록 (바로빌 사이트 — 세금계산서/홈텍스 필수)
☐ 은행 계좌 등록 (바로빌 사이트 — 계좌조회 이용 시)
☐ 법인카드 등록 (바로빌 사이트 — 카드내역 이용 시)
☐ 서비스 활성화 (SAM 설정 페이지)
☐ 담당자 정보 설정 (이름, 연락처, 이메일)
☐ 충전 잔액 확인 (선불 충전제)
☐ 서버 모드 확인 (테스트 → 운영 전환)
세금계산서 발행 · 국세청 전송 · 상태 조회
TI.asmx알림톡 · 친구톡 · SMS 대체발송
KAKAOTALK.asmx입출금 내역 수집 · 잔액 조회 · 인증서 관리
BANKACCOUNT.asmx법인카드 등록 · 사용내역 수집 · 카드사 조회
CARD.asmx국세청 매입/매출 데이터 자동 수집
CORPSTATE.asmxSAM에서 거래처에 세금계산서를 발행하고, 바로빌 API를 통해 국세청에 자동 전송합니다.
처리 흐름
SOAP 서비스: TI.asmx | 주요 메서드: RegistAndIssueTaxInvoice, CancelTaxInvoice, GetTaxInvoiceState
상태 흐름: DRAFT → ISSUED → SENT (국세청 전송 완료)
전자계약 서명 요청, 리마인드 등 중요한 알림을 카카오톡으로 발송합니다.
| 구분 | 알림톡 | 친구톡 |
|---|---|---|
| 용도 | 정보성 메시지 (계약 알림 등) | 광고성 메시지 |
| 수신 대상 | 모든 카카오톡 사용자 | 채널 친구 추가자만 |
| 템플릿 | 필수 (카카오 사전 승인) | 불필요 (자유 작성) |
| 비용 | 건당 8~9원 | 건당 15~20원 |
| SMS 대체발송 | 지원 | 지원 |
카카오톡 채널 정보
채널명: (주)코드브릿지엑스 | 채널ID: @codebridge
법인 계좌를 등록하면, 바로빌이 자동으로 입출금 내역을 수집합니다. SAM에서는 이 데이터를 조회하여 재무관리에 활용합니다.
주요 기능
SOAP 서비스: BANKACCOUNT.asmx | 37개 은행 코드 지원
법인카드를 등록하면, 바로빌이 카드 사용 내역을 자동으로 수집합니다. 16개 카드사를 지원합니다.
주요 기능
SOAP 서비스: CARD.asmx | 16개 카드사 지원 (비씨, 삼성, 신한 등)
국세청 홈텍스의 매입/매출 세금계산서 데이터를 자동으로 수집하여 SAM에서 조회할 수 있습니다.
주요 기능
SOAP 서비스: CORPSTATE.asmx | 인증서 관리 포함
전자계약 서명 요청 시 알림톡이 발송되는 과정입니다.
{{-- 플로우차트 --}}
┌─────────────┐ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────┐
│ SAM 전자계약 │────▶│ EsignApiController │────▶│ BarobillService │────▶│ 바로빌 서버 │
│ 서명 요청 │ │ sendAlimtalk() │ │ sendATKakaotalkEx │ │ SOAP API │
└─────────────┘ └─────────────────┘ └──────────────────┘ └──────┬───────┘
│
┌─────────────────┐ ┌──────────────────┐ │
│ 수신자 카카오톡 │◀────│ 카카오 서버 │◀───────────┘
│ 알림톡 수신 │ │ 메시지 전달 │
└─────────────────┘ └──────────────────┘
⚠️ 2단계 검증 (필수)
알림톡 발송은 SendKey 반환 ≠ 전달 성공입니다. 반드시 2단계 검증이 필요합니다:
ResultCode=1: 성공 | ResultCode=4: 템플릿 불일치 | 기타: 실패
등록된 알림톡 템플릿
| 템플릿명 | 운영 | 개발 | 용도 |
|---|---|---|---|
| 전자계약_서명요청 | 전자계약_서명요청 |
전자계약_서명요청_DEV |
서명 요청 알림 |
| 전자계약_완료 | 전자계약_완료 |
전자계약_완료_DEV |
서명 완료 알림 |
| 전자계약_리마인드 | 전자계약_리마인드 |
전자계약_리마인드_DEV |
미서명 독촉 알림 |
템플릿 자동 분기: APP_ENV=production이면 원본 템플릿, 그 외에는 _DEV 접미사 자동 추가
바로빌 서비스는 월정액 + 건별 과금 구조로 운영됩니다.
| 서비스 | 과금 방식 | 무료 구간 | 초과 요금 |
|---|---|---|---|
| 전자세금계산서 | 건별 | 100건/월 무료 | 50건 단위 5,000원 |
| 계좌조회 | 월정액 | 1개 계좌 무료 | 추가 계좌당 월 10,000원 |
| 카드내역 | 월정액 | 5장 무료 | 추가 카드당 월 5,000원 |
| 홈텍스 | 월정액 | — | 본사 부담 (무료) |
| 카카오톡 알림톡 | 건별 (바로빌 직접 과금) | — | 건당 8~9원 |
참고: 과금 정책은 DB(barobill_pricing_policies 테이블)에서 관리되며, DB에 없으면 위의 기본값이 적용됩니다. 매월 1일 자동 과금 처리가 실행됩니다.
API 통신 방식
| 프로젝트 | 프로토콜 | 용도 |
|---|---|---|
| MNG (관리자) | SOAP/WSDL | 계좌, 카드, 카카오톡, SMS, 회원관리 |
| API (백엔드) | REST | 세금계산서 발행, 사업자번호 검증 |
SOAP WSDL 엔드포인트
| 서비스 | 테스트 서버 | 운영 서버 |
|---|---|---|
| 회원관리 | testws.baroservice.com/CORPSTATE.asmx |
ws.baroservice.com/CORPSTATE.asmx |
| 세금계산서 | testws.baroservice.com/TI.asmx |
ws.baroservice.com/TI.asmx |
| 계좌조회 | testws.baroservice.com/BANKACCOUNT.asmx |
ws.baroservice.com/BANKACCOUNT.asmx |
| 카드조회 | testws.baroservice.com/CARD.asmx |
ws.baroservice.com/CARD.asmx |
| 카카오톡 | testws.baroservice.com/KAKAOTALK.asmx |
ws.baroservice.com/KAKAOTALK.asmx |
| 문자(SMS) | testws.baroservice.com/SMS.asmx |
ws.baroservice.com/SMS.asmx |
테스트/운영 환경 분리
| 환경 | APP_ENV | 바로빌 서버 | 도메인 |
|---|---|---|---|
| 로컬 (Docker) | local |
test / production | mng.sam.kr |
| 개발 서버 | local |
test / production | admin.codebridge-x.com |
| 운영 서버 | production |
production | mng.codebridge-x.com |
server_mode는 barobill_members 테이블에서 회원사별로 관리됩니다. APP_ENV와 독립적으로 설정 가능합니다.
API 공통 응답 형식
{
"success": true|false,
"data": mixed, // success=true
"error": "에러 메시지", // success=false
"error_code": -11102 // 에러 코드
}
| 테이블 | 모델 | 역할 |
|---|---|---|
barobill_members |
BarobillMember | 바로빌 회원사 정보 (사업자번호, 인증키, server_mode) |
barobill_configs |
BarobillConfig | SOAP 연동 설정 (DB 기반) |
barobill_subscriptions |
BarobillSubscription | 월정액 구독 관리 (계좌/카드/홈텍스) |
barobill_billing_records |
BarobillBillingRecord | 건별/월정액 과금 기록 |
barobill_monthly_summaries |
BarobillMonthlySummary | 월별 과금 집계 |
barobill_pricing_policies |
BarobillPricingPolicy | 서비스별 과금 정책 (무료건수, 단가) |
hometax_invoices |
HometaxInvoice | 세금계산서 내역 (매입/매출, 사용량 집계용) |
MNG 페이지 라우트
| Method | Path | 설명 |
|---|---|---|
| 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 라우트
| Method | Path | 설명 |
|---|---|---|
| GET | /barobill/kakaotalk |
카카오톡 메인 |
| GET | /barobill/kakaotalk/guide |
카카오톡 사용법 가이드 |
| POST | /api/admin/barobill/kakaotalk/send-alimtalk |
알림톡 발송 |
| POST | /api/admin/barobill/kakaotalk/send-friendtalk |
친구톡 발송 |
API 프로젝트 (REST)
| 기능 | 메서드 | 설명 |
|---|---|---|
| 사업자 검증 | checkBusinessNumber() |
사업자번호 유효성/휴폐업 조회 |
| 세금계산서 발행 | issueTaxInvoice() |
세금계산서 발행 (DRAFT → ISSUED) |
| 세금계산서 취소 | cancelTaxInvoice() |
세금계산서 취소 (ISSUED → CANCELLED) |
| 국세청 전송 확인 | checkNtsSendStatus() |
국세청 전송 상태 (ISSUED → SENT) |
| 연동 테스트 | testConnection() |
바로빌 API 연결 테스트 |
증상: SendATKakaotalkEx가 SendKey를 반환했지만, 수신자가 메시지를 받지 못함
원인: SendKey는 "바로빌 서버가 접수했다"는 의미일 뿐, 카카오 전달 성공을 보장하지 않음
해결: 반드시 3초 대기 후 GetSendKakaotalk()을 호출하여 ResultCode=1인지 확인
증상: ResultCode=4 (템플릿 불일치) 오류 발생
원인: 버튼 URL이 등록된 템플릿과 정확히 일치해야 함 (경로, 쿼리 파라미터 추가 불가)
해결: 동적 URL이 필요하면, 템플릿에 #{변수}를 포함하여 카카오에 재등록
증상: 에러코드 -31325 발생
원인: SmsReply='S'(SMS 대체발송 사용)인데 SmsSenderNum이 비어있음
해결: SMS 메시지/발신번호가 비어있으면 SmsReply='N'으로 설정
증상: 1건일 때는 정상, 여러 건일 때 에러 (또는 반대)
원인: SOAP 응답이 1건이면 stdClass 객체, N건이면 배열로 반환
해결: 응답을 받으면 is_array()로 타입을 확인한 후 처리
주요 에러 코드
| 코드 | 의미 |
|---|---|
| -11101 | 사업자번호 미설정 또는 유효하지 않음 |
| -11102 | CERTKEY 유효하지 않음 |
| -11103 | 인증서 만료 또는 유효하지 않음 |
| -11104 | 등록되지 않은 사업자 |
| -26001 | 공동인증서 미등록 |
| -31325 | SMS 발신번호 누락 (SmsReply 오류) |
| -32010 | 이미 등록된 사업자번호 |
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 프로젝트 (백엔드)
서비스 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