Files

김보곤 79ca132d1a docs: [barobill] 테넌트 온보딩 개념 정의 문서 추가

- 온보딩 vs 베타테스트 개념 구분
- 6단계 온보딩 프로세스 정의
- 테스트→운영 모드 전환 체크리스트
- 개발→베타→출시→온보딩 단계별 관계 정리

2026-03-17 09:00:00 +09:00

README.md

docs: [barobill] 테넌트 온보딩 개념 정의 문서 추가

2026-03-17 09:00:00 +09:00

tenant-onboarding.md

docs: [barobill] 테넌트 온보딩 개념 정의 문서 추가

2026-03-17 09:00:00 +09:00

README.md

바로빌(Barobill) 연동 시스템

작성일: 2026-03-17 상태: MNG 운영 중 / 서비스 이관 준비

1. 개요

1.1 목적

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

1.2 현재 상태

항목	MNG (백오피스)	API (서비스)	React (프론트)
SOAP 연동 서비스	✅ 완료 (1,761줄)	기본 설정만	—
회원사 관리	✅ 운영 중	모델만 존재	설정 페이지
카드 거래 조회	✅ 운영 중	✅ REST API 16개	—
은행 거래 조회	✅ 운영 중	✅ REST API 13개	—
홈택스 세금계산서	✅ 운영 중	✅ REST API 13개	—
카카오톡/SMS	✅ 운영 중	—	—
과금 시스템	✅ 구현 완료	—	—

핵심: tenant_id=1 (코드브릿지엑스 본사)에서 실무 운영 중. 서비스 이관 시 멀티테넌트 SOAP 연동이 핵심 과제.

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)
        │
        │ SOAP (6개 서비스)
        ▼
┌─────────────────────────────────┐
│  MNG (BarobillService)          │
│  ├─ CORPSTATE — 회원사 관리      │
│  ├─ TI — 전자세금계산서          │
│  ├─ BANKACCOUNT — 계좌조회       │
│  ├─ CARD — 카드조회              │
│  ├─ KAKAOTALK — 알림톡          │
│  └─ SMS — 문자 발송             │
└──────────┬──────────────────────┘
           │ MySQL 저장
           ▼
┌─────────────────────────────────┐
│  MySQL (samdb)                  │
│  ├─ barobill_members            │
│  ├─ barobill_card_transactions  │
│  ├─ barobill_bank_transactions  │
│  ├─ hometax_invoices            │
│  └─ (18개 테이블)               │
└──────────┬──────────────────────┘
           │ REST API
           ▼
┌─────────────────────────────────┐
│  API (42개 엔드포인트)           │
│  ├─ /api/v1/barobill-card-*     │
│  ├─ /api/v1/barobill-bank-*     │
│  └─ /api/v1/hometax-invoices/*  │
└──────────┬──────────────────────┘
           │
           ▼
┌─────────────────────────────────┐
│  React (사용자 UI)              │
│  └─ BarobillIntegration 컴포넌트│
└─────────────────────────────────┘

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`)

유형	경로
서비스	`app/Services/BarobillService.php` (기본 설정만)
모델	`app/Models/Barobill/` (15개)
모델	`app/Models/Tenants/BarobillSetting.php`
컨트롤러	`app/Http/Controllers/Api/V1/Barobill*Controller.php`
마이그레이션	`database/migrations/` (19개 바로빌 관련)

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 이관 범위

기능	MNG (현재)	API 이관	React 이관	우선순위
SOAP 연동 서비스	✅	🔴 필수	—	P1
회원사 등록/관리	✅	🔴 필수	🔴 필수	P1
테스트/운영 모드 전환	✅	🔴 필수	🟡 관리자	P1
카드 거래 동기화	✅	🟡 중요	✅ 완료	P2
은행 거래 동기화	✅	🟡 중요	—	P2
홈택스 동기화	✅	🟡 중요	—	P2
세금계산서 발행	✅	🟡 중요	🟡 중요	P2
과금 시스템	✅	🟢 권장	🟢 권장	P3
카카오톡/SMS	✅	🟢 권장	—	P3

9.2 이관 시 핵심 과제

SOAP 서비스 이관: MNG의 BarobillService (1,761줄)를 API로 이동
멀티테넌트 CERTKEY: 테넌트별로 바로빌 파트너 계약이 필요한지, 공용 CERTKEY로 처리 가능한지 확인
테스트 모드 관리: 신규 테넌트는 테스트 모드로 시작 → 관리자가 운영 모드로 전환
동기화 스케줄러: MNG에서 실행 중인 은행/카드/홈택스 동기화를 API Queue로 이관
인증서 관리: 공동인증서 등록 URL을 테넌트 사용자에게 제공하는 플로우

문서	설명
테넌트 온보딩	온보딩 개념 정의, 테스트→운영 전환 프로세스
바로빌 API 명세	카드/은행/홈택스 REST API 42개 엔드포인트
바로빌 회원 마이그레이션	회원 데이터 이관 가이드
바로빌 카카오톡	카카오톡 알림톡 연동
재무관리	재무/자금관리 전체 개요

README.md

바로빌(Barobill) 연동 시스템

1. 개요

1.1 목적

1.2 현재 상태

1.3 바로빌 공식 자료

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

2.1 모드 비교

2.2 모드 전환 구조

2.3 설정 우선순위

2.4 환경변수

2.5 개발 시 주의사항

3. 아키텍처

3.1 전체 데이터 흐름

3.2 SOAP 서비스 목록

3.3 인증 구조

4. 과금 정책

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

4.2 추가 과금 (건별)

4.3 과금 처리 흐름

4.4 테스트 모드에서의 과금

5. 멀티테넌트 처리

5.1 데이터 격리

5.2 회원사별 설정

5.3 서비스 이관 시 고려사항

6. 프로젝트별 코드 위치

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

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

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

7. DB 테이블 구조

7.1 테이블 목록

7.2 핵심 테이블 스키마

8. 에러 코드 매핑

9. 서비스 이관 계획

9.1 이관 범위

9.2 이관 시 핵심 과제

관련 문서

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

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

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