# 바로빌(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 설정 우선순위 1. **DB 설정** (`barobill_configs` 테이블) — 최우선 2. **.env 환경변수** — DB 설정 없을 때 폴백 ```php // 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 환경변수 ```bash # .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 | 인증서 만료/잔액 부족 알림 | 스케줄러 기반 자동 알림 | --- ## 관련 문서 | 문서 | 설명 | |------|------| | [테넌트 온보딩](./tenant-onboarding.md) | 온보딩 개념 정의, 테스트→운영 전환 프로세스 | | [API SOAP 기술 참조](./api-soap-reference.md) | API BarobillSoapService 전체 메서드, 동기화, 스케줄러 | | [온보딩 실행 가이드](../../guides/barobill-onboarding-guide.md) | 7단계 실행 절차, API 예시, 트러블슈팅, 고객 안내 | | [바로빌 API 명세](../../frontend/api-specs/barobill-api.md) | 카드/은행/홈택스 REST API 42개 엔드포인트 | | [바로빌 회원 마이그레이션](../../dev/guides/barobill-members-migration.md) | 회원 데이터 이관 가이드 | | [바로빌 카카오톡](../barobill-kakaotalk/README.md) | 카카오톡 알림톡 연동 | | [바로빌 출시 계획](../../dev/dev_plans/barobill-service-launch-plan.md) | 4단계 출시 로드맵 | | [재무관리](../finance/README.md) | 재무/자금관리 전체 개요 | --- **최종 업데이트**: 2026-03-17