# 바로빌 온보딩 실행 가이드

> **작성일**: 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
