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

10 KiB

Raw Blame History

바로빌 테넌트 온보딩 프로세스

작성일: 2026-03-17 상태: 설계 중 (서비스 이관 준비)

1. 온보딩(Onboarding)이란

1.1 정의

온보딩: 새로운 고객(테넌트)이 서비스에 가입하여 실제 사용을 시작하기까지의 초기 설정 과정.

SAM 바로빌 맥락에서는 정식 계약 고객이 바로빌 연동 기능(계좌조회, 카드내역, 세금계산서 등)을 실무에서 사용할 수 있도록 초기 세팅하는 일련의 절차를 의미한다.

1.2 온보딩 vs 베타테스트

구분	온보딩	베타테스트
대상	정식 계약 고객	서비스 출시 전 검증 참여자
목적	고객이 기능을 쓸 수 있게 초기 세팅	서비스 안정성/기능 검증
시점	고객 가입할 때마다 반복 발생	서비스 출시 전 1회성
테스트 모드	초기 세팅 확인용으로 잠깐 사용 가능	전체 기간 테스트 모드로 운영
데이터	실제 업무 데이터	검증용 테스트 데이터
과금	정식 과금 (운영 모드 전환 후)	무과금

1.3 단계별 관계

서비스 이관 완료 후 다음 순서로 진행한다:

서비스 이관 (개발)
  └─ 베타테스트 (출시 전 검증)
      └─ 정식 출시
          └─ 테넌트 온보딩 (고객 가입 시마다 반복)

2. 바로빌 온보딩 전체 흐름

2.1 단계별 프로세스

Phase 1: 테넌트 계약
┌──────────────────────────────────────────┐
│  고객사 SAM 서비스 계약 체결              │
│  └─ SAM 테넌트 생성 (tenant_id 발급)     │
│  └─ 바로빌 서비스 이용 여부 확인          │
└──────────────────────┬───────────────────┘
                       ▼
Phase 2: 바로빌 회원 등록 (테스트 모드)
┌──────────────────────────────────────────┐
│  바로빌 회원사 등록 (BarobillService)     │
│  ├─ 사업자번호, 상호, 대표자 등록         │
│  ├─ 바로빌 ID/PW 생성                    │
│  ├─ server_mode = 'test' (기본값)         │
│  └─ 테스트 서버에서 연동 확인             │
└──────────────────────┬───────────────────┘
                       ▼
Phase 3: 인증서 및 계좌/카드 연결
┌──────────────────────────────────────────┐
│  공동인증서 등록                          │
│  ├─ getCertificateRegistUrl() → 고객 직접│
│  ├─ 인증서 유효성 확인                    │
│  └─ 인증서 만료일 모니터링 설정           │
│                                          │
│  계좌 연결                                │
│  ├─ getBankAccountScrapRequestUrl()       │
│  └─ 고객이 직접 계좌 등록                 │
│                                          │
│  카드 연결                                │
│  ├─ registCard()                          │
│  └─ 카드사별 등록                         │
└──────────────────────┬───────────────────┘
                       ▼
Phase 4: 연동 검증
┌──────────────────────────────────────────┐
│  테스트 모드에서 기능 확인                 │
│  ├─ 계좌 입출금 내역 조회 확인            │
│  ├─ 카드 사용내역 조회 확인               │
│  ├─ 홈택스 세금계산서 수집 확인           │
│  └─ 문제 없으면 다음 단계                 │
└──────────────────────┬───────────────────┘
                       ▼
Phase 5: 운영 모드 전환
┌──────────────────────────────────────────┐
│  관리자가 server_mode → 'production' 전환 │
│  ├─ 운영 CERTKEY로 SOAP 재연결            │
│  ├─ 실제 데이터 수집 시작                 │
│  └─ 과금 시작 (구독 등록)                 │
└──────────────────────┬───────────────────┘
                       ▼
Phase 6: 실무 사용 시작
┌──────────────────────────────────────────┐
│  정기 동기화 스케줄러 활성화              │
│  ├─ 은행 거래 자동 수집                   │
│  ├─ 카드 내역 자동 수집                   │
│  ├─ 홈택스 세금계산서 자동 수집           │
│  └─ 월정액 과금 자동 처리                 │
└──────────────────────────────────────────┘

2.2 역할 분담

단계	수행 주체	설명
테넌트 생성	SAM 관리자	MNG에서 테넌트 생성
회원사 등록	SAM 관리자 또는 고객	사업자 정보 입력
인증서 등록	고객 직접	바로빌 제공 URL에서 직접 등록
계좌/카드 등록	고객 직접	바로빌 제공 URL에서 직접 등록
연동 검증	SAM 관리자	테스트 모드에서 데이터 수집 확인
운영 전환	SAM 관리자	`server_mode` 변경

3. 테스트 모드 활용

3.1 온보딩에서의 테스트 모드 역할

테스트 모드는 온보딩 Phase 2~4에서 연동을 검증하기 위해 사용한다.

✅ 바로빌 회원 등록이 정상적으로 되는지 확인
✅ 인증서/계좌/카드 연결이 작동하는지 확인
✅ API 호출이 정상 응답하는지 확인
❌ 실제 세금계산서 발행 (국세청 미전송)
❌ 실제 거래 데이터 수집 (테스트 데이터만)

3.2 테스트 모드 체크리스트

Phase 4 (연동 검증) 완료 기준:

바로빌 회원 상태: active
공동인증서: 등록됨 + 유효기간 확인
계좌: 1개 이상 등록, 입출금 조회 응답 정상
카드: 1개 이상 등록, 사용내역 조회 응답 정상
홈택스: 매출/매입 세금계산서 수집 응답 정상
에러 없이 모든 API 호출 성공

3.3 운영 전환 체크리스트

Phase 5 (운영 모드 전환) 전 확인:

테스트 모드 검증 완료
고객 동의 (실제 과금 시작 안내)
운영 CERTKEY 설정 확인
구독 등록 (월정액 과금 설정)
server_mode → production 전환
운영 모드에서 첫 데이터 수집 성공 확인

4. 개발 시 주의사항

4.1 개발 단계에서의 테스트 모드

온보딩 프로세스와 별개로, 서비스 이관 개발 중에는 항상 테스트 모드를 사용한다.

단계	모드	이유
서비스 이관 개발	테스트	코드 검증, 무과금
베타테스트	테스트	실사용 시나리오 검증, 무과금
고객 온보딩 Phase 2~4	테스트	연동 설정 확인, 무과금
고객 온보딩 Phase 5~	운영	실무 사용, 과금 시작

4.2 서비스 이관 완료 후 출시 순서

1. 서비스 이관 개발 완료 (테스트 모드)
2. 내부 베타테스트 (tenant_id=1, 코드브릿지엑스, 테스트 모드)
3. 외부 베타테스트 (선별 고객 2~3곳, 테스트 모드)
4. 정식 출시
5. 신규 고객 온보딩 프로세스 가동 (반복)

5. 구현 현황 (2026-03-17)

5.1 API SOAP 서비스 구축 완료

API에 MNG와 100% 동등한 SOAP 서비스가 독립 구축되었다.

항목	파일	상태
SOAP 래퍼 (6개 서비스, 49 메서드)	`BarobillSoapService.php`	✅
은행 동기화	`BarobillBankSyncService.php`	✅
카드 동기화	`BarobillCardSyncService.php`	✅
홈택스 동기화	`HometaxSyncService.php`	✅
동기화/회원 API (11개)	`BarobillSyncController.php`	✅
자동 동기화 Job	`SyncBarobillDataJob.php`	✅

상세: API SOAP 기술 참조

5.2 테스트 환경 데이터

tenant_id	회사	바로빌 ID	모드	테스트 적합성
290	(주)주일기업	`juil5130`	test	즉시 가능 (Step 3~7)
289	(주)경동기업	`kd5130`	test	즉시 가능
291	(미생성)	—	—	풀 온보딩 테스트용

5.3 온보딩 테스트 시나리오

시나리오 A: 빠른 SOAP 검증 (tenant_id=290)

이미 바로빌 회원이 등록된 상태.
→ Step 3(인증서 URL 확인)부터 Step 7(동기화)까지 테스트.
→ 소요: 10분

시나리오 B: 풀 온보딩 (tenant_id=291 신규 생성)

테넌트 생성 → 바로빌 회원 등록 → 인증서/계좌/카드 → 검증 → 운영 전환
→ Step 1부터 Step 7까지 전 과정 테스트.
→ 소요: 1시간 (인증서/계좌 등록 포함)

문서	설명
바로빌 연동 시스템	전체 구조, 테스트/운영 모드, 과금 정책
API SOAP 기술 참조	API SOAP 서비스 전체 메서드, 동기화, 스케줄러
온보딩 실행 가이드	7단계 실행 절차, API 예시, 트러블슈팅
온보딩 실행 가이드 PPT	12슬라이드 프레젠테이션
바로빌 API 명세	REST API 42개 + SOAP 11개 엔드포인트
데모 테넌트 정책	영업파트너 데모 테넌트 3-Tier 전략

10 KiB Raw Blame History