Files

김보곤 3588bb3dd7 docs: [barobill] API SOAP 구축 완료 반영 + 기술 참조 문서 신규

- README.md: 현재 상태 업데이트 (API SOAP 100% 구축 완료, 아키텍처 다이어그램)
- api-soap-reference.md: 신규 — 전체 메서드 49+7개, 동기화, 스케줄러, 테스트 환경 데이터
- tenant-onboarding.md: 구현 현황/테스트 시나리오 추가
- INDEX.md: 신규 문서 등록

2026-03-17 14:53:30 +09:00

20 KiB

Raw Blame History

바로빌(Barobill) 연동 시스템

작성일: 2026-03-17 상태: MNG 운영 중 / API SOAP 서비스 구축 완료 (2026-03-17)

1. 개요

1.1 목적

바로빌은 전자세금계산서, 계좌조회, 카드내역, 홈택스 연동, 카카오톡/SMS 발송 등을 제공하는 SOAP 기반 B2B 서비스다. SAM에서 재무/회계 데이터를 자동 수집하고 세금계산서를 발행하기 위해 연동한다.

1.2 현재 상태

항목	MNG (백오피스)	API (서비스)	React (프론트)
SOAP 연동 서비스	✅ 완료 (1,761줄)	✅ 구축 완료 (49+7 메서드)	—
회원사 관리	✅ 운영 중	✅ SOAP 등록/수정/상태	설정 페이지
카드 거래 조회	✅ 운영 중	✅ REST 16개 + SOAP 동기화	—
은행 거래 조회	✅ 운영 중	✅ REST 13개 + SOAP 동기화	—
홈택스 세금계산서	✅ 운영 중	✅ REST 13개 + upsert 동기화	—
카카오톡/SMS	✅ 운영 중	✅ SOAP 메서드 구현 (19개)	—
과금 시스템	✅ 구현 완료	— (모델만 존재)	—
자동 동기화	MNG 수동	✅ Queue Job + 스케줄러	—

현재 상태 (2026-03-17): API SOAP 서비스가 MNG와 100% 동등하게 구축되었다. MNG(본사 tenant_id=1)와 API(서비스 tenant_id=2~N)가 각각 독립적으로 SOAP 호출하며, 같은 DB(samdb)를 공유한다.

MNG (본사 전용, 수정 없음)              API (서비스 고객용, 신규 구축 완료)
┌──────────────────────┐               ┌──────────────────────┐
│ BarobillService      │               │ BarobillSoapService  │
│ (1,761줄 그대로)     │               │ (49+7 메서드)        │
│ BankSyncService      │               │ BankSyncService      │
│ HometaxSyncService   │               │ CardSyncService      │
│                      │               │ HometaxSyncService   │
│ tenant_id=1 본사     │               │ tenant_id=2~N 고객   │
└──────────┬───────────┘               └──────────┬───────────┘
           │                                      │
           └────────── 같은 DB (samdb) ────────────┘

1.3 바로빌 공식 자료

개발자 센터: https://dev.barobill.co.kr/
운영 WSDL: https://ws.baroservice.com/
테스트 WSDL: https://testws.baroservice.com/

2. 테스트 모드 vs 운영 모드

경고: 개발 시 반드시 테스트 모드를 사용한다. 운영 모드는 실제 과금이 발생한다.

2.1 모드 비교

항목	테스트 모드	운영 모드
WSDL 엔드포인트	`https://testws.baroservice.com/`	`https://ws.baroservice.com/`
CERTKEY	테스트용 별도 발급	운영용 별도 발급
과금	❌ 무과금	✅ 실제 과금
데이터	테스트 데이터 (초기화 가능)	실제 세금계산서/거래 데이터
국세청 전송	❌ 미전송	✅ 실제 전송
회원사 등록	테스트 서버에 등록	운영 서버에 등록
인증서	테스트 인증서 사용 가능	실제 공동인증서 필수

2.2 모드 전환 구조

┌───────────────────────────────────────────────────────┐
│                    모드 결정 흐름                       │
├───────────────────────────────────────────────────────┤
│                                                       │
│  1. BarobillMember.server_mode                        │
│     └─ 'test' 또는 'production' (회원사별 설정)        │
│                                                       │
│  2. BarobillService.switchServerMode(isTestMode)      │
│     └─ SOAP 클라이언트 재초기화                        │
│     └─ initializeConfig() 호출                        │
│                                                       │
│  3. initializeConfig()                                │
│     ├─ DB 우선: BarobillConfig.getActive(isTestMode)  │
│     │   └─ environment = 'test' | 'production'       │
│     └─ .env 폴백:                                     │
│         ├─ test → BAROBILL_CERT_KEY_TEST              │
│         └─ prod → BAROBILL_CERT_KEY_PROD              │
│                                                       │
│  4. SOAP URL 구성                                     │
│     ├─ test → testws.baroservice.com/*                │
│     └─ prod → ws.baroservice.com/*                    │
│                                                       │
└───────────────────────────────────────────────────────┘

2.3 설정 우선순위

DB 설정 (barobill_configs 테이블) — 최우선
.env 환경변수 — DB 설정 없을 때 폴백

// BarobillService::initializeConfig()
$dbConfig = BarobillConfig::getActive($this->isTestMode);

if ($dbConfig) {
    // DB에서 cert_key, corp_num, base_url 사용
} else {
    // .env에서 BAROBILL_CERT_KEY_TEST/PROD, BAROBILL_CORP_NUM 사용
}

2.4 환경변수

# .env (MNG, API 동일)
BAROBILL_CERT_KEY_TEST=<테스트 인증키>
BAROBILL_CERT_KEY_PROD=<운영 인증키>
BAROBILL_CORP_NUM=<파트너 사업자번호>
BAROBILL_TEST_MODE=true   # 기본값: 테스트 모드

2.5 개발 시 주의사항

✅ 로컬/개발 서버: BAROBILL_TEST_MODE=true (기본값)
✅ 운영 서버: BAROBILL_TEST_MODE=false + 운영 CERTKEY
✅ 회원사별 server_mode로 개별 전환 가능
❌ 테스트 CERTKEY로 운영 서버 호출 불가 (에러 -11102)
❌ 운영 모드에서 테스트 데이터 생성 금지 (실제 과금)

3. 아키텍처

3.1 전체 데이터 흐름

                   바로빌 SOAP API (ws.baroservice.com / testws.baroservice.com)
                          │                                │
                   SOAP (6개 서비스)                  SOAP (6개 서비스)
                          ▼                                ▼
┌──────────────────────────────┐    ┌──────────────────────────────────┐
│  MNG (BarobillService)       │    │  API (BarobillSoapService)       │
│  본사 전용 (tenant_id=1)     │    │  서비스 고객 (tenant_id=2~N)     │
│  ├─ CORPSTATE 회원관리       │    │  ├─ CORPSTATE 회원관리           │
│  ├─ TI 세금계산서            │    │  ├─ TI 세금계산서               │
│  ├─ BANKACCOUNT 계좌         │    │  ├─ BANKACCOUNT 계좌             │
│  ├─ CARD 카드                │    │  ├─ CARD 카드                    │
│  ├─ KAKAOTALK 알림톡         │    │  ├─ KAKAOTALK 알림톡             │
│  └─ SMS 문자                 │    │  └─ SMS 문자                     │
└──────────┬───────────────────┘    │  + BankSyncService (동기화)      │
           │                        │  + CardSyncService (동기화)      │
           │                        │  + HometaxSyncService (동기화)   │
           │                        │  + SyncBarobillDataJob (스케줄러)│
           │                        └──────────┬───────────────────────┘
           │                                   │
           └─────────── MySQL (samdb) ─────────┘
                          │
                   REST API (53개 엔드포인트)
                          │
                          ▼
               ┌────────────────────┐
               │  React (사용자 UI) │
               └────────────────────┘

3.2 SOAP 서비스 목록

서비스	WSDL 경로	기능
CORPSTATE	`/CORPSTATE.asmx`	회원사 등록/조회/수정
TI	`/TI.asmx`	전자세금계산서 발행/조회
BANKACCOUNT	`/BANKACCOUNT.asmx`	계좌 등록/입출금 내역 조회
CARD	`/CARD.asmx`	카드 등록/사용내역 조회
KAKAOTALK	`/KAKAOTALK.asmx`	카카오톡 알림톡 발송
SMS	`/SMS.asmx`	문자 메시지 발송

3.3 인증 구조

모든 API 호출
  └─ CERTKEY (파트너 인증키) — 필수 파라미터
      ├─ 바로빌 파트너 계약 시 발급
      ├─ 테스트/운영 별도 키
      └─ BarobillService.call()에서 자동 주입

4. 과금 정책

4.1 바로빌 과금 구조 (SAM 내부 정책)

서비스	월정액	비고
계좌조회 (`bank_account`)	10,000원/월	테넌트별
카드내역 (`card`)	10,000원/월	테넌트별
홈택스 매입/매출 (`hometax`)	0원	본사 부담 (무료 제공)

4.2 추가 과금 (건별)

BarobillPricingPolicy 모델 기반:

서비스	무료 기본량	추가 과금 단위	추가 금액
법인카드 등록 (`card`)	정책 설정값	정책 설정값	정책 설정값
계산서 발행 (`tax_invoice`)	정책 설정값	건당	정책 설정값
계좌조회 수집 (`bank_account`)	정책 설정값	정책 설정값	정책 설정값

과금 계산: BarobillPricingPolicy::calculateBilling(usageCount) — 무료 제공량 초과분만 과금

4.3 과금 처리 흐름

매월 1일 (배치)
  └─ BarobillBillingService::processMonthlyBilling()
      ├─ 활성 구독 조회 (BarobillSubscription::active())
      ├─ 이미 과금된 기록 중복 방지
      ├─ BarobillBillingRecord 생성 (subscription 타입)
      └─ BarobillMonthlySummary 갱신

건별 발생 시
  └─ BarobillBillingService::recordUsage()
      ├─ BarobillBillingRecord 생성 (usage 타입)
      └─ BarobillMonthlySummary 갱신

4.4 테스트 모드에서의 과금

✅ 테스트 모드: 바로빌 API 호출에 대한 바로빌 측 과금 없음
✅ SAM 내부 과금 시스템은 모드와 무관하게 기록 가능 (테스트용)
❌ 운영 모드: 바로빌 측 실제 과금 발생 (충전잔액 차감)

5. 멀티테넌트 처리

5.1 데이터 격리

모든 바로빌 테이블은 tenant_id 컬럼으로 데이터를 격리한다.

tenant_id=1 (코드브릿지엑스) → 본사 실무 데이터
tenant_id=N (고객사)        → 해당 고객사 데이터만 접근

5.2 회원사별 설정

각 테넌트는 barobill_members 테이블에 독립된 바로빌 회원사 정보를 가진다:

컬럼	설명
`tenant_id`	테넌트 FK
`biz_no`	사업자번호 (UNIQUE with tenant_id)
`barobill_id`	바로빌 로그인 ID
`barobill_pwd`	바로빌 비밀번호 (Laravel Encryption)
`server_mode`	`test` 또는 `production` (회원사별 전환)
`status`	`active` / `inactive` / `pending`

5.3 서비스 이관 시 고려사항

🔴 필수: 테넌트별 CERTKEY 관리 방안 (현재는 전역 1개)
🔴 필수: 테넌트 온보딩 시 바로빌 회원 자동 등록 플로우
🟡 중요: 테스트→운영 모드 전환 프로세스 정의
🟡 중요: 과금 정책을 테넌트별로 다르게 적용 가능하도록 확장
🟢 권장: 바로빌 API 호출 로그/모니터링

6. 프로젝트별 코드 위치

6.1 MNG (`/home/aweso/sam/mng`)

유형	경로
서비스	`app/Services/Barobill/BarobillService.php` (1,761줄, 핵심)
서비스	`app/Services/Barobill/HometaxSyncService.php`
서비스	`app/Services/Barobill/BarobillBillingService.php`
서비스	`app/Services/Barobill/BarobillUsageService.php`
서비스	`app/Services/Barobill/BarobillBankSyncService.php`
모델	`app/Models/Barobill/` (18개 모델)
컨트롤러	`app/Http/Controllers/Barobill/` (7개)
Admin API	`app/Http/Controllers/Api/Admin/Barobill/` (7개)
뷰	`resources/views/barobill/` (10개 페이지)

6.2 API (`/home/aweso/sam/api`)

유형	경로	설명
SOAP 서비스	`app/Services/Barobill/BarobillSoapService.php`	6개 SOAP 서비스, 49+7 메서드
동기화	`app/Services/Barobill/BarobillBankSyncService.php`	은행 거래 SOAP→DB 동기화
동기화	`app/Services/Barobill/BarobillCardSyncService.php`	카드 거래 SOAP→DB 동기화
동기화	`app/Services/Barobill/HometaxSyncService.php`	홈택스 세금계산서 upsert
기존 서비스	`app/Services/BarobillService.php`	REST 설정/세금계산서 발행 (기존)
Queue Job	`app/Jobs/Barobill/SyncBarobillDataJob.php`	자동 동기화 스케줄러 Job
컨트롤러	`app/Http/Controllers/Api/V1/BarobillSyncController.php`	SOAP 동기화/회원/인증서 API
컨트롤러	`app/Http/Controllers/Api/V1/BarobillController.php`	기존 설정/URL API (보강됨)
모델	`app/Models/Barobill/` (15개)	기존 모델
라우트	`routes/api/v1/finance.php`	기존 42개 + 신규 11개
스케줄러	`routes/console.php`	06:00 은행, 06:30 카드 동기화

6.3 React (`/home/aweso/sam/react`)

유형	경로
컴포넌트	`src/components/settings/BarobillIntegration/`
페이지	`/settings/barobill-integration`

7. DB 테이블 구조

7.1 테이블 목록

테이블	용도	마이그레이션 위치
`barobill_members`	회원사 정보	API
`barobill_configs`	API 설정 (test/prod 분리)	API
`barobill_settings`	테넌트별 서비스 설정	API
`barobill_subscriptions`	월정액 구독	API
`barobill_billing_records`	과금 기록	API
`barobill_monthly_summaries`	월별 과금 요약	API
`barobill_pricing_policies`	요금 정책	API
`hometax_invoices`	홈택스 세금계산서	API
`hometax_invoice_journals`	세금계산서 분개	API
`barobill_bank_transactions`	은행 거래 내역	API
`barobill_bank_transaction_overrides`	은행 적요 수정	API
`barobill_bank_transaction_splits`	은행 거래 분할	API
`barobill_bank_sync_status`	은행 동기화 상태	API
`barobill_card_transactions`	카드 거래 내역	API
`barobill_card_transaction_splits`	카드 거래 분할	API
`barobill_card_transaction_amount_logs`	카드 금액 수정 로그	API
`barobill_card_transaction_hides`	카드 거래 숨김	API
`account_codes`	계정과목 마스터	API

7.2 핵심 테이블 스키마

barobill_members:

tenant_id + biz_no UNIQUE
server_mode: test | production
barobill_pwd: Laravel Encryption (복호화 가능, API 호출 시 필요)

hometax_invoices:

tenant_id + nts_confirm_num + invoice_type UNIQUE
invoice_type: sales | purchase
tax_type: 1=과세, 2=영세, 3=면세
issue_type: 1=정발행, 2=역발행

8. 에러 코드 매핑

코드	의미	대응
-11101	사업자번호 미설정/유효하지 않음	회원사 정보 확인
-11102	CERTKEY 유효하지 않음	테스트/운영 키 확인
-11103	인증서 만료/유효하지 않음	공동인증서 갱신
-11104	미등록 사업자	회원사 등록 먼저
-11105	이미 등록된 사업자	중복 등록 방지
-26001	공동인증서 미등록	인증서 등록 안내
-32001	사업자번호 형식 오류	10자리 숫자 확인
-32010	이미 등록된 사업자번호	기존 회원 확인
-32011	이미 등록된 아이디	다른 아이디 사용

9. 서비스 이관 계획

9.1 이관 현황 (2026-03-17 기준)

기능	MNG	API 이관	React	상태
SOAP 연동 서비스 (6개)	✅	✅ 완료	—	49 메서드 100%
회원사 등록/관리	✅	✅ 완료	설정 페이지	API 3개 엔드포인트
테스트/운영 모드 전환	✅	✅ 완료	—	initForMember()
은행 거래 동기화	✅	✅ 완료	—	BankSyncService
카드 거래 동기화	✅	✅ 완료	—	CardSyncService
홈택스 동기화	✅	✅ 완료	—	HometaxSyncService
자동 동기화 스케줄러	—	✅ 완료	—	06:00/06:30 Job
카카오톡 (15개)	✅	✅ 완료	—	SOAP 메서드
SMS (4개)	✅	✅ 완료	—	SOAP 메서드
세금계산서 발행	✅	✅ 기존 REST	—	BarobillService
과금 시스템	✅	모델만	—	미이관
카카오톡/SMS API 엔드포인트	✅	—	—	미구현 (SOAP만)
온보딩 대시보드 (MNG)	—	—	—	기획 중

9.2 남은 과제

우선순위	과제	설명
🔴 P1	온보딩 실제 테스트	테스트 테넌트로 풀 시나리오 검증
🔴 P1	카카오톡/SMS REST API 엔드포인트	SOAP 메서드는 구현됨, Controller+Route 추가 필요
🟡 P2	React 바로빌 관리 화면	동기화 트리거, 인증서/계좌/카드 관리
🟡 P2	MNG 온보딩 대시보드	테넌트별 연동 진행 상태 시각화
🟢 P3	과금 시스템 API 이관	BillingService, UsageService
🟢 P3	인증서 만료/잔액 부족 알림	스케줄러 기반 자동 알림

문서	설명
테넌트 온보딩	온보딩 개념 정의, 테스트→운영 전환 프로세스
API SOAP 기술 참조	API BarobillSoapService 전체 메서드, 동기화, 스케줄러
온보딩 실행 가이드	7단계 실행 절차, API 예시, 트러블슈팅, 고객 안내
바로빌 API 명세	카드/은행/홈택스 REST API 42개 엔드포인트
바로빌 회원 마이그레이션	회원 데이터 이관 가이드
바로빌 카카오톡	카카오톡 알림톡 연동
바로빌 출시 계획	4단계 출시 로드맵
재무관리	재무/자금관리 전체 개요

20 KiB Raw Blame History