sam-docs/guides/barobill-onboarding-guide.md

바로빌 온보딩 실행 가이드

작성일: 2026-03-17 상태: 확정 대상: SAM 관리자 + 고객사 담당자 관련: 온보딩 프로세스 정의 | 바로빌 시스템

---

1. 개요

1.1 이 문서의 목적

새로운 고객(테넌트)이 SAM의 바로빌 연동 기능을 사용하기까지의 실행 절차를 단계별로 안내한다. SAM 관리자가 이 문서를 따라 진행하면, 고객사가 계좌조회/카드내역/홈택스 세금계산서를 SAM에서 바로 사용할 수 있다.

1.2 전체 흐름 요약

Step 1. 사전 준비 (고객 정보 확보)
   ↓
Step 2. 바로빌 회원 등록 (테스트 모드)
   ↓
Step 3. 인증서 등록 (고객 직접)
   ↓
Step 4. 계좌/카드 연결 (고객 직접)
   ↓
Step 5. 연동 검증 (테스트 모드)
   ↓
Step 6. 운영 모드 전환
   ↓
Step 7. 자동 동기화 확인

1.3 소요 시간

단계	소요 시간	수행 주체
Step 1~2	10분	SAM 관리자
Step 3~4	30분~1시간	고객 직접
Step 5	10분	SAM 관리자
Step 6~7	5분	SAM 관리자

고객이 인증서와 계좌/카드를 미리 준비하면, 전체 1시간 이내 완료 가능.

---

2. Step 1: 사전 준비

2.1 고객에게 확보할 정보

항목	필수	예시	비고
사업자등록번호	🔴	138-81-66437	10자리, 하이픈 제거
상호(회사명)	🔴	(주)주일기업
대표자명	🔴	이경호
업태	🟡	제조업
종목	🟡	블라인드
사업장 주소	🟡	서울시 강남구...
담당자명	🟡	홍길동	바로빌 연동 담당
담당자 연락처	🟡	010-1234-5678
담당자 이메일	🟡	hong@example.com

2.2 바로빌 ID/PW 결정

고객사용 바로빌 아이디와 비밀번호를 정한다. 바로빌에 회원으로 등록되는 계정이다.

항목	규칙	예시
아이디	영문+숫자, 4~20자	juil5130
비밀번호	영문+숫자+특수문자, 8자 이상	Juil@2026!

권장 네이밍: {회사약칭}{사업자번호뒤4자리} — 예: juil6437

2.3 SAM 테넌트 확인

고객의 SAM 테넌트가 이미 생성되어 있어야 한다.

확인 경로: MNG → 테넌트 관리 → 해당 고객사
필요 정보: tenant_id, 사업자번호가 등록되어 있는지 확인

---

3. Step 2: 바로빌 회원 등록

3.1 테스트 모드로 회원 등록

중요: 처음에는 반드시 테스트 모드로 등록한다. 운영 모드는 검증 완료 후 전환한다.

방법 A: MNG 관리자 화면에서 등록

MNG → 바로빌 → 회원사 관리 → [새 회원사 등록]

입력 정보:
- 테넌트 선택: (해당 고객사)
- 사업자번호: 138-81-66437
- 상호: (주)주일기업
- 대표자: 이경호
- 바로빌 ID: juil6437
- 바로빌 PW: ********
- 서버 모드: 테스트 (기본값)

→ [등록] 버튼 클릭

방법 B: API 호출로 등록 (서비스 앱)

POST /api/v1/barobill/members
Header: X-Tenant-Id: {tenant_id}

Body:
{
  "biz_no": "1388166437",
  "corp_name": "(주)주일기업",
  "ceo_name": "이경호",
  "biz_type": "제조업",
  "biz_class": "블라인드",
  "addr": "서울시 강남구...",
  "barobill_id": "juil6437",
  "barobill_pwd": "Juil@2026!",
  "manager_name": "홍길동",
  "manager_hp": "01012345678",
  "manager_email": "hong@example.com"
}

3.2 등록 확인

등록 성공 시 바로빌 테스트 서버에 회원이 생성된다.

GET /api/v1/barobill/members/status
→ barobill_state 값 확인

또는 MNG → 바로빌 → 회원사 관리 → 해당 회원 상태 확인

상태	의미
1 또는 active	정상 등록됨
-32010	이미 등록된 사업자번호 (기존 회원)
-32011	이미 등록된 아이디 (ID 변경 필요)

3.3 이미 바로빌 회원인 경우

고객사가 이전에 바로빌을 사용한 적이 있다면, 기존 아이디를 확인하여 SAM에 등록한다.

1. 고객에게 기존 바로빌 아이디/비밀번호 확인
2. MNG 또는 API에서 해당 정보로 BarobillMember 레코드만 생성
3. SOAP RegistCorp 호출 생략 (skip_api=true)

---

4. Step 3: 인증서 등록

수행 주체: 고객 직접 (SAM 관리자는 URL만 제공)

4.1 인증서가 필요한 이유

바로빌이 은행/카드사/국세청에서 데이터를 수집하려면 고객사의 **공동인증서(구 공인인증서)**가 필요하다. 인증서는 바로빌 서버에 등록되며, SAM이 직접 보관하지 않는다.

4.2 인증서 등록 URL 제공

GET /api/v1/barobill/certificate-url
→ 응답에 포함된 URL을 고객에게 전달

또는 MNG → 바로빌 → 회원사 관리 → [인증서 등록] 버튼

고객은 해당 URL에 접속하여:

1. 공동인증서 선택
2. 인증서 비밀번호 입력
3. 등록 완료

4.3 인증서 등록 확인

GET /api/v1/barobill/certificate
→ is_valid: true
→ expire_date: "20271231" (만료일)

확인 항목	정상 값
is_valid	true
expire_date	현재 날짜 이후

인증서 갱신: 공동인증서는 보통 1년 만기. 만료 30일 전 알림이 필요하다.

---

5. Step 4: 계좌/카드 연결

수행 주체: 고객 직접 (SAM 관리자는 URL만 제공)

5.1 계좌 등록

GET /api/v1/barobill/account-link-url
→ 응답 URL을 고객에게 전달

또는 MNG → 바로빌 → 회원사 관리 → [계좌 등록] 버튼

고객은 해당 URL에서:

1. 은행 선택
2. 계좌번호 입력
3. 인터넷뱅킹 아이디/비밀번호 입력
4. 등록 완료

5.2 카드 등록

GET /api/v1/barobill/card-link-url
→ 응답 URL을 고객에게 전달

또는 MNG → 바로빌 → 회원사 관리 → [카드 등록] 버튼

고객은 해당 URL에서:

1. 카드사 선택
2. 카드번호 입력
3. 카드사 웹 아이디/비밀번호 입력
4. 등록 완료

5.3 등록 확인

GET /api/v1/barobill/accounts
→ accounts: [{bankAccountNum: "...", bankName: "신한은행", ...}]

GET /api/v1/barobill/cards
→ cards: [{cardNum: "...", cardCompanyName: "삼성카드", ...}]

확인 항목	기대 값
계좌 수	1개 이상
카드 수	1개 이상 (카드 이용 시)

---

6. Step 5: 연동 검증

수행 주체: SAM 관리자

6.1 은행 거래내역 조회 테스트

POST /api/v1/barobill/sync/bank
Header: X-Tenant-Id: {tenant_id}
Body: {
  "start_date": "20260301",
  "end_date": "20260317"
}

→ success: true
→ synced: 15 (동기화된 건수)
→ accounts: 2 (등록 계좌 수)

6.2 카드 거래내역 조회 테스트

POST /api/v1/barobill/sync/card
Header: X-Tenant-Id: {tenant_id}
Body: {
  "start_date": "20260301",
  "end_date": "20260317"
}

→ success: true
→ synced: 8 (동기화된 건수)
→ cards: 1 (등록 카드 수)

6.3 충전잔액 확인

GET /api/v1/barobill/balance
→ balance: 50000 (잔액, 원)

바로빌은 충전 방식. 잔액이 부족하면 API 호출이 실패한다. 잔액 충전은 바로빌 관리자 페이지에서 진행.

6.4 검증 체크리스트

모든 항목이 통과해야 운영 모드 전환이 가능하다.

• 바로빌 회원 상태: active
• 공동인증서: 등록됨 + 만료일 유효
• 계좌: 1개 이상 등록됨
• 은행 동기화: 정상 응답 (synced >= 0)
• 카드: 1개 이상 등록됨 (카드 이용 시)
• 카드 동기화: 정상 응답 (synced >= 0)
• 충전잔액: 양수 확인
• API 호출 시 에러 없음

테스트 서버 참고: 테스트 모드에서는 실제 거래 데이터가 아닌 바로빌 제공 테스트 더미 데이터가 조회된다. 이는 정상이다.

---

7. Step 6: 운영 모드 전환

수행 주체: SAM 관리자 전제: Step 5 검증 체크리스트 모두 통과

7.1 전환 전 확인사항

항목	확인
고객 동의	✅ 운영 전환 시 실제 과금 시작됨을 안내
운영 CERTKEY	✅ barobill_configs 테이블에 운영 설정 존재
충전잔액	✅ 바로빌 계좌에 충분한 잔액

7.2 모드 전환

MNG → 바로빌 → 회원사 관리 → 해당 회원 → [운영 전환]

또는 API:
PUT /api/v1/barobill/members
Body: { "server_mode": "production" }

7.3 전환 후 확인

운영 모드에서 첫 데이터 수집이 정상인지 확인한다.

1. POST /api/v1/barobill/sync/bank → 실제 거래 데이터 확인
2. POST /api/v1/barobill/sync/card → 실제 카드 데이터 확인
3. GET /api/v1/barobill/balance   → 충전잔액 차감 확인

---

8. Step 7: 자동 동기화 확인

8.1 스케줄러 동작

운영 모드(server_mode=production)인 회원만 자동 동기화 대상이다.

시간	동기화 대상	Job
매일 06:00	은행 거래내역 (전일)	SyncBarobillDataJob('bank')
매일 06:30	카드 거래내역 (전일)	SyncBarobillDataJob('card')

8.2 수동 동기화

고객이 실시간 데이터가 필요할 때는 React 화면에서 수동 동기화를 실행할 수 있다.

React 화면 → [동기화] 버튼
→ POST /api/v1/barobill/sync/bank (또는 /card)

8.3 동기화 모니터링

MNG → 바로빌 → 동기화 현황
- 테넌트별 마지막 동기화 시간
- 동기화 실패 이력
- 충전잔액 부족 알림

---

9. 고객 안내 자료

9.1 고객에게 전달할 내용

온보딩 시 고객에게 다음을 안내한다:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SAM 바로빌 연동 안내
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

고객님께서 직접 진행하셔야 하는 항목:

1. 공동인증서 등록
   → 저희가 보내드린 URL에 접속하여 공동인증서를 등록해주세요.
   → 은행/카드/홈택스 데이터 수집에 필요합니다.

2. 계좌 연결
   → 저희가 보내드린 URL에서 조회할 계좌를 등록해주세요.
   → 인터넷뱅킹 아이디/비밀번호가 필요합니다.

3. 카드 연결 (선택)
   → 법인카드 사용내역 조회가 필요하면 등록해주세요.
   → 카드사 웹 아이디/비밀번호가 필요합니다.

준비물:
- 공동인증서 (USB 또는 PC에 저장된 것)
- 인터넷뱅킹 아이디/비밀번호
- 카드사 웹 아이디/비밀번호 (카드 연결 시)

문의: 코드브릿지엑스 기술지원팀
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

9.2 자주 묻는 질문 (FAQ)

질문	답변
인증서가 만료되면?	갱신 후 바로빌 인증서 등록 URL에서 재등록
계좌를 추가하고 싶으면?	계좌 등록 URL에서 추가 등록
데이터가 안 나와요	인증서 유효성 확인 → 충전잔액 확인 → 관리자 문의
카드 등록이 안 돼요	카드사 웹 아이디/비밀번호 확인, 카드사 보안설정 확인
테스트에서 실제 데이터가 안 나와요	테스트 모드는 더미 데이터만 조회, 운영 전환 후 실제 데이터

---

10. 트러블슈팅

10.1 에러 코드 대응표

에러 코드	의미	대응
-11102	CERTKEY 무효	barobill_configs 테이블의 활성 설정 확인
-11104	미등록 사업자	RegistCorp 재실행 또는 사업자번호 확인
-26001	인증서 미등록	고객에게 인증서 등록 URL 재전달
-25001	조회 결과 없음	정상 (해당 기간 데이터 없음)
-25005	데이터 없음	정상 (해당 기간 데이터 없음)
-32010	중복 사업자번호	기존 회원으로 등록 (RegistCorp 생략)
-32011	중복 아이디	다른 바로빌 ID로 재시도
-32013	비밀번호 형식 오류	영문+숫자+특수문자 조합 8자 이상

10.2 인증서 관련 문제

증상: "공동인증서가 등록되어 있지 않습니다" (-26001)

확인 순서:
1. GET /api/v1/barobill/certificate → is_valid 확인
2. is_valid: false → 고객에게 인증서 등록 URL 재전달
3. 인증서 만료 → 갱신 후 재등록
4. 인증서 등록 후에도 오류 → 바로빌 고객센터 문의

10.3 충전잔액 부족

증상: API 호출 시 잔액 관련 에러

확인 순서:
1. GET /api/v1/barobill/balance → 잔액 확인
2. 잔액 < 1000원 → 충전 필요
3. 충전 URL 제공: GET /api/v1/barobill/cash-charge-url
4. 고객이 바로빌 관리자 페이지에서 충전

---

11. 참고: API 엔드포인트 요약

11.1 온보딩에 사용하는 API

Method	Path	용도	사용 단계
POST	/v1/barobill/members	바로빌 회원 등록	Step 2
GET	/v1/barobill/members/status	회원 상태 확인	Step 2
GET	/v1/barobill/certificate-url	인증서 등록 URL	Step 3
GET	/v1/barobill/certificate	인증서 상태 확인	Step 3
GET	/v1/barobill/account-link-url	계좌 등록 URL	Step 4
GET	/v1/barobill/card-link-url	카드 등록 URL	Step 4
GET	/v1/barobill/accounts	등록계좌 목록	Step 4~5
GET	/v1/barobill/cards	등록카드 목록	Step 4~5
POST	/v1/barobill/sync/bank	은행 동기화	Step 5
POST	/v1/barobill/sync/card	카드 동기화	Step 5
GET	/v1/barobill/balance	충전잔액 조회	Step 5~6
PUT	/v1/barobill/members	회원 정보 수정	Step 6

11.2 기존 데이터 조회 API (42개)

온보딩 완료 후 React에서 사용하는 데이터 조회 API:

• 은행 거래: GET /v1/barobill-bank-transactions (13개)
• 카드 거래: GET /v1/barobill-card-transactions (16개)
• 홈택스: GET /v1/hometax-invoices (13개)

상세 명세: 바로빌 API 명세

---

관련 문서

문서	설명
온보딩 프로세스 정의	6단계 프로세스 개념, 역할 분담
바로빌 연동 시스템	SOAP 구조, 테스트/운영 모드, 과금
바로빌 API 명세	REST API 42개 엔드포인트 상세
바로빌 출시 계획	4단계 출시 로드맵

---

최종 업데이트: 2026-03-17