@extends('layouts.app') @section('title', '바로빌 개발문서') @section('content')
{{-- 페이지 헤더 --}}
바로빌 개발문서

바로빌 연동 개발문서

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

{{-- 목차 --}}

📋 목차

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

바로빌이란?

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

SAM에서 바로빌을 쓰는 이유

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

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

{{-- 섹션 2: 회원사 필수 설정 가이드 --}}
2

회원사 필수 설정 가이드

{{-- 파트너사 / 회원사 구조 설명 --}}

파트너사와 회원사 구조

바로빌

API 플랫폼

(주)코드브릿지엑스

파트너사 (본사)

주일 · 경동 · …

회원사 (테넌트)

  • 파트너사 (코드브릿지엑스) — 바로빌과 직접 계약하고, 인증키(CERTKEY)를 보유. 회원사를 등록/관리
  • 회원사 (각 테넌트) — 파트너사 아래에 등록된 실제 사업체. 각자의 사업자번호로 서비스를 이용
{{-- 회원사 설정 단계 --}}

새 회원사가 바로빌 서비스를 사용하려면 아래 단계를 순서대로 완료해야 합니다.

{{-- STEP 1: MNG에서 회원사 등록 --}}
1 MNG에서 회원사 등록 SAM 관리자 작업

경로: SAM MNG → 바로빌 → 회원사관리 → 신규등록

회사 기본 정보(사업자번호, 상호명, 대표자명, 주소 등)와 바로빌 로그인 정보(아이디/비밀번호)를 입력하면, 바로빌 API(RegistCorp)를 통해 회원사가 자동 등록됩니다.

주의: 바로빌 아이디/비밀번호는 이후 모든 바로빌 사이트 접속에 사용됩니다. 회원사에 반드시 안내해 주세요.
{{-- STEP 2: 공동인증서 등록 --}}
2 공동인증서 등록 회원사 필수 작업 가장 중요

바로빌 사이트에서 직접 수행 — SAM 설정 페이지에서 "공동인증서 등록" 버튼 클릭 시 바로빌 사이트로 이동

해야 할 일:

  1. SAM MNG → 바로빌 → 설정 → "공동인증서 등록" 버튼 클릭
  2. 바로빌 사이트가 열리면, 회원사의 범용 공동인증서(.pfx 파일)를 업로드
  3. 인증서 비밀번호 입력 후 등록 완료
⚠️ 미등록 시: 전자세금계산서 발행 불가, 홈텍스 매입/매출 수집 불가. 인증서 없이는 국세청 연동 기능을 사용할 수 없습니다.
인증서 갱신: 인증서는 1년 단위로 만료됩니다. 갱신 후 바로빌에 다시 등록해야 합니다. SAM 회원사관리에서 인증서 만료일을 확인할 수 있습니다.
{{-- STEP 3: 계좌 등록 --}}
3 은행 계좌 등록 (계좌조회 서비스 이용 시) 회원사 필수 작업

바로빌 사이트에서 직접 수행 — 입출금 내역을 자동 수집하려면 은행 계좌를 등록해야 합니다.

해야 할 일:

  1. SAM MNG → 바로빌 → 설정 → "은행 빠른조회 서비스 등록" 버튼 클릭
  2. 바로빌 사이트에서 법인 계좌 정보 입력 (은행, 계좌번호)
  3. 은행별 본인 인증 절차 완료
  4. 등록 후 "계좌 관리" 버튼에서 등록된 계좌 확인

37개 은행 지원 (국민, 신한, 우리, 산업, 하나 등)

{{-- STEP 4: 카드 등록 --}}
4 법인카드 등록 (카드내역 서비스 이용 시) 회원사 필수 작업

바로빌 사이트에서 직접 수행 — 법인카드 사용 내역을 자동 수집하려면 카드를 등록해야 합니다.

해야 할 일:

  1. SAM MNG → 바로빌 → 설정 → "카드 연동 등록" 버튼 클릭
  2. 바로빌 사이트에서 법인카드 정보 입력 (카드사, 카드번호)
  3. 카드사별 인증 절차 완료
  4. 등록 후 "카드 관리" 버튼에서 등록된 카드 확인

16개 카드사 지원 (비씨, 삼성, 신한, 현대 등)

{{-- STEP 5: 서비스 활성화 --}}
5 서비스 활성화 및 담당자 정보 설정 SAM 관리자 작업

경로: SAM MNG → 바로빌 → 설정 → 서비스 이용 설정

서비스 사전 조건 설정 항목
전자세금계산서 공동인증서 등록 필수 use_tax_invoice 체크
계좌조회 은행 계좌 등록 완료 use_bank_account 체크
카드사용내역 법인카드 등록 완료 use_card_usage 체크
홈텍스 매입/매출 공동인증서 등록 필수 use_hometax 체크

담당자 이름, 연락처, 이메일도 이 단계에서 설정합니다 (세금계산서 알림 수신용).

{{-- STEP 6: 충전 잔액 확인 --}}
6 충전 잔액 확인 (선불제) 회원사 수시 확인

바로빌 API 호출은 선불 충전 방식입니다. 잔액이 부족하면 계좌조회/카드내역 수집이 중단됩니다.

확인 방법:

  • SAM MNG → 바로빌 → 회원사관리 → 상태조회 버튼 → "충전 잔액" 확인
  • 잔액 부족 시: 바로빌 사이트에서 직접 충전 (SAM 설정 → "현금충전" 버튼)
{{-- 체크리스트 요약 --}}

회원사 설정 체크리스트

☐ MNG에서 회원사 등록 (사업자번호, 바로빌 ID/PW)

공동인증서 등록 (바로빌 사이트 — 세금계산서/홈텍스 필수)

☐ 은행 계좌 등록 (바로빌 사이트 — 계좌조회 이용 시)

☐ 법인카드 등록 (바로빌 사이트 — 카드내역 이용 시)

☐ 서비스 활성화 (SAM 설정 페이지)

☐ 담당자 정보 설정 (이름, 연락처, 이메일)

☐ 충전 잔액 확인 (선불 충전제)

☐ 서버 모드 확인 (테스트 → 운영 전환)

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

우리가 쓰는 서비스

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

전자세금계산서

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

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

카카오톡

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

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

계좌조회

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

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

카드내역

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

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

홈텍스 매입/매출

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

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

서비스별 상세

{{-- 전자세금계산서 --}}
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 | 인증서 관리 포함

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

카카오톡 알림톡 흐름

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

{{-- 플로우차트 --}}
┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  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 접미사 자동 추가

{{-- 섹션 6: 과금 구조 --}}
6

과금 구조

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

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

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

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

시스템 구조 (개발자용)

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

API 통신 방식

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

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_modebarobill_members 테이블에서 회원사별로 관리됩니다. APP_ENV와 독립적으로 설정 가능합니다.

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

API 공통 응답 형식

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

주요 테이블

테이블 모델 역할
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 세금계산서 내역 (매입/매출, 사용량 집계용)
{{-- 섹션 9: API 엔드포인트 --}}
9

API 엔드포인트

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

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 --}}

카카오톡 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 프로젝트 엔드포인트 --}}

API 프로젝트 (REST)

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

트러블슈팅

{{-- 이슈 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이미 등록된 사업자번호
{{-- 섹션 11: 관련 파일 경로 --}}
11

관련 파일 경로

{{-- 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