SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: [barobill] 온보딩 실행 가이드 작성

Browse Source 
- 7단계 실행 절차 (사전준비→회원등록→인증서→계좌카드→검증→운영전환→자동동기화)
- 각 단계별 API 호출 예시 포함
- 에러 코드 대응표, 트러블슈팅 섹션
- 고객 안내 자료 템플릿, FAQ
- INDEX.md에 등록
This commit is contained in:
김보곤
2026-03-17 13:14:17 +09:00
parent e619dd77f7
commit 4bc7f36b5e
2 changed files with 506 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
INDEX.md
View File

@@ -26,6 +26,7 @@
| 바로빌 회계 API | `frontend/api-specs/barobill-api.md` | 카드/은행/홈택스 REST API (42개 엔드포인트) |
| 바로빌 시스템 | `features/barobill/README.md` | SOAP 연동, 테스트/운영 모드, 과금, 멀티테넌트, 이관 계획 |
| 바로빌 출시 계획 | `dev/dev_plans/barobill-service-launch-plan.md` | 4단계 출시 로드맵 (SOAP 이관→UI→베타→출시) |
| 바로빌 온보딩 가이드 | `guides/barobill-onboarding-guide.md` | 신규 고객 바로빌 연동 실행 절차 (7단계, API 예시, 트러블슈팅) |
| 재공품 생산 정책 | `rules/wip-production-policy.md` | 재공품(WIP) 개념, 제조업 공통 패턴, SAM 처리 방식 |
| 재고생산관리 API | `frontend/api-specs/stock-production-api.md` | 재고생산 API 명세 (기존 수주 API + STOCK 타입) |
| 절곡품 LOT API | `frontend/api-specs/bending-lot-api.md` | 절곡품 코드맵/품목매핑/LOT 채번 API (프론트엔드 구현 가이드 포함) |
@@ -197,6 +198,7 @@ DB 도메인별:
| [pptx-generation-guide.md](guides/pptx-generation-guide.md) | PPTX 생성 가이드 |
| [project-launch-roadmap.md](guides/project-launch-roadmap.md) | 프로젝트 런칭 로드맵 |
| [table-design-guide.md](guides/table-design-guide.md) | 테이블 설계 가이드 |
| [barobill-onboarding-guide.md](guides/barobill-onboarding-guide.md) | 바로빌 온보딩 실행 가이드 (7단계 절차, API 예시, 트러블슈팅, 고객 안내 자료) |
---

504
guides/barobill-onboarding-guide.md Normal file
View File

@@ -0,0 +1,504 @@
# 바로빌 온보딩 실행 가이드
> **작성일**: 2026-03-17
> **상태**: 확정
> **대상**: SAM 관리자 + 고객사 담당자
> **관련**: [온보딩 프로세스 정의](../features/barobill/tenant-onboarding.md) | [바로빌 시스템](../features/barobill/README.md)
---
## 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 명세](../frontend/api-specs/barobill-api.md)
---
## 관련 문서
| 문서 | 설명 |
|------|------|
| [온보딩 프로세스 정의](../features/barobill/tenant-onboarding.md) | 6단계 프로세스 개념, 역할 분담 |
| [바로빌 연동 시스템](../features/barobill/README.md) | SOAP 구조, 테스트/운영 모드, 과금 |
| [바로빌 API 명세](../frontend/api-specs/barobill-api.md) | REST API 42개 엔드포인트 상세 |
| [바로빌 출시 계획](../dev/dev_plans/barobill-service-launch-plan.md) | 4단계 출시 로드맵 |
---
**최종 업데이트**: 2026-03-17