sam-docs/frontend/api-specs/barobill-api.md

# 바로빌 회계 데이터 API 명세

> **작성일**: 2026-03-11
> **상태**: 개발 완료 (API 배포 대기)
> **Base URL**: `api.codebridge-x.com` (운영) / `api.dev.codebridge-x.com` (개발)
> **엔드포인트 수**: 42개

---

## 1. 개요

MNG에서 바로빌 SOAP API로 동기화된 카드 거래, 은행 거래, 홈택스 세금계산서 데이터를 React 프론트엔드에서 조회/관리하기 위한 REST API 명세.

### 1.1 아키텍처

```
바로빌 SOAP API (baroservice.com)
        │
        │ MNG BarobillService (동기화)
        ▼
┌─────────────────────────────┐
│     MySQL (barobill_*)      │
│  ┌───────────────────────┐  │
│  │ barobill_card_*       │  │  ← 카드 거래 (5 테이블)
│  │ barobill_bank_*       │  │  ← 은행 거래 (4 테이블)
│  │ hometax_invoices      │  │  ← 홈택스 세금계산서 (2 테이블)
│  └───────────────────────┘  │
└──────────┬──────────────────┘
           │
           │ API REST Endpoints (이 문서)
           ▼
┌─────────────────────────────┐
│     React 프론트엔드        │
│  ┌───────────────────────┐  │
│  │ 카드 거래 조회/관리   │  │
│  │ 은행 거래 조회/관리   │  │
│  │ 홈택스 계산서 조회    │  │
│  └───────────────────────┘  │
└─────────────────────────────┘
```

> **중요**: 기존 `card-transactions`, `bank-transactions` 엔드포인트는 SAM 내부 `Withdrawal`/`Deposit` 모델을 사용한다. 바로빌 연동 데이터는 `barobill-*` 접두사 엔드포인트를 사용해야 한다.

### 1.2 인증

```
X-API-KEY: {api_key}
Authorization: Bearer {token}
```

### 1.3 공통 응답 형식

```json
{
  "success": true,
  "message": "조회되었습니다.",
  "data": { ... }
}
```

### 1.4 공통 쿼리 파라미터

| 파라미터 | 타입 | 설명 | 기본값 |
|---------|------|------|--------|
| `start_date` | date | 조회 시작일 | 이번 달 1일 |
| `end_date` | date | 조회 종료일 | 오늘 |
| `search` | string | 검색어 | - |
| `per_page` | int | 페이지당 건수 (1~100) | 50 |
| `page` | int | 페이지 번호 | 1 |

---

## 2. 바로빌 카드 거래 API (16개)

**Prefix**: `/api/v1/barobill-card-transactions`

### 2.1 엔드포인트 목록

| Method | Path | 설명 |
|--------|------|------|
| GET | `/` | 카드 거래 목록 |
| GET | `/card-numbers` | 카드 번호 목록 (필터용) |
| GET | `/hidden` | 숨겨진 거래 목록 |
| GET | `/splits` | 분할 조회 |
| POST | `/splits` | 분할 저장 |
| DELETE | `/splits` | 분할 삭제 |
| POST | `/manual` | 수동 거래 등록 |
| PUT | `/manual/{id}` | 수동 거래 수정 |
| DELETE | `/manual/{id}` | 수동 거래 삭제 |
| GET | `/{id}` | 거래 상세 |
| POST | `/{id}/hide` | 거래 숨김 |
| POST | `/{id}/restore` | 거래 복원 |
| PUT | `/{id}/amount` | 금액 수정 |
| GET | `/{id}/journal-entries` | 분개 조회 |
| POST | `/{id}/journal-entries` | 분개 저장 |
| DELETE | `/{id}/journal-entries` | 분개 삭제 |

### 2.2 목록 조회

```
GET /api/v1/barobill-card-transactions
```

**추가 파라미터**:

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `card_num` | string | 카드 번호 필터 |
| `include_hidden` | boolean | 숨겨진 거래 포함 여부 |

**응답**: 페이지네이션된 카드 거래 목록. 각 항목에 `splits`(분할 정보), `has_splits`(분할 존재 여부) 포함.

### 2.3 분할 (Splits)

하나의 카드 거래를 여러 계정과목으로 분할 배분한다.

```
GET /api/v1/barobill-card-transactions/splits?unique_key={key}
POST /api/v1/barobill-card-transactions/splits
DELETE /api/v1/barobill-card-transactions/splits
```

**POST 요청**:

```json
{
  "unique_key": "1234****5678|20260311120000|12345678|50000",
  "items": [
    {
      "split_amount": 30000,
      "split_supply_amount": 27273,
      "split_tax": 2727,
      "account_code": "81100",
      "account_name": "복리후생비",
      "card_num": "1234****5678",
      "use_date": "2026-03-11",
      "original_amount": 50000,
      "merchant_name": "식당"
    },
    {
      "split_amount": 20000,
      "split_supply_amount": 18182,
      "split_tax": 1818,
      "account_code": "81300",
      "account_name": "접대비"
    }
  ]
}
```

### 2.4 숨김/복원

거래를 목록에서 숨기거나 복원한다. 원본 데이터는 유지된다.

```
POST /api/v1/barobill-card-transactions/{id}/hide
POST /api/v1/barobill-card-transactions/{id}/restore
GET  /api/v1/barobill-card-transactions/hidden?start_date=&end_date=
```

### 2.5 금액 수정

공급가액/세액을 수정한다. 변경 이력이 `barobill_card_transaction_amount_logs`에 자동 기록된다.

```
PUT /api/v1/barobill-card-transactions/{id}/amount
```

```json
{
  "supply_amount": 45000,
  "tax": 4500,
  "modified_by_name": "홍길동"
}
```

### 2.6 수동 입력

MNG 동기화 외 수동으로 카드 거래를 입력한다. `is_manual=true`로 저장된다.

```
POST /api/v1/barobill-card-transactions/manual
```

```json
{
  "card_num": "1234****5678",
  "use_dt": "20260311120000",
  "use_date": "2026-03-11",
  "approval_amount": 50000,
  "merchant_name": "가맹점명",
  "account_code": "81100",
  "account_name": "복리후생비"
}
```

> **주의**: 수동 거래만 수정/삭제 가능. 바로빌 동기화 거래는 수정/삭제 불가.

### 2.7 분개 (Journal Entries)

`JournalSyncService`를 통해 `journal_entries` + `journal_entry_lines` 테이블에 분개를 저장한다. CEO 대시보드 복리후생비/접대비 자동 동기화.

```json
{
  "items": [
    {
      "side": "debit",
      "account_code": "81100",
      "debit_amount": 50000,
      "credit_amount": 0,
      "vendor_name": "가맹점",
      "memo": "식대"
    },
    {
      "side": "credit",
      "account_code": "25300",
      "account_name": "미지급금",
      "debit_amount": 0,
      "credit_amount": 50000
    }
  ]
}
```

**Source Type**: `barobill_card` (`JournalEntry::SOURCE_BAROBILL_CARD`)

---

## 3. 바로빌 은행 거래 API (13개)

**Prefix**: `/api/v1/barobill-bank-transactions`

### 3.1 엔드포인트 목록

| Method | Path | 설명 |
|--------|------|------|
| GET | `/` | 은행 거래 목록 |
| GET | `/accounts` | 계좌 목록 (필터용) |
| GET | `/balance-summary` | 잔액 요약 |
| GET | `/splits` | 분할 조회 |
| POST | `/splits` | 분할 저장 |
| DELETE | `/splits` | 분할 삭제 |
| POST | `/override` | 적요/분류 오버라이드 |
| POST | `/manual` | 수동 거래 등록 |
| PUT | `/manual/{id}` | 수동 거래 수정 |
| DELETE | `/manual/{id}` | 수동 거래 삭제 |
| GET | `/{id}/journal-entries` | 분개 조회 |
| POST | `/{id}/journal-entries` | 분개 저장 |
| DELETE | `/{id}/journal-entries` | 분개 삭제 |

### 3.2 목록 조회

```
GET /api/v1/barobill-bank-transactions
```

**추가 파라미터**:

| 파라미터 | 타입 | 설명 |
|---------|------|------|
| `bank_account_num` | string | 계좌번호 필터 |

**응답**: 각 항목에 `splits`, `has_splits`, `override`(오버라이드 정보) 포함.

### 3.3 오버라이드

원본 적요/분류를 변경하지 않고 별도 테이블에 수정값을 저장한다.

```
POST /api/v1/barobill-bank-transactions/override
```

```json
{
  "unique_key": "계좌번호|거래일시|입금|출금|잔액",
  "modified_summary": "수정된 적요",
  "modified_cast": "급여"
}
```

### 3.4 잔액 요약

특정 날짜 기준 계좌별 최종 잔액을 조회한다.

```
GET /api/v1/barobill-bank-transactions/balance-summary?date=2026-03-11
```

**응답**:

```json
{
  "items": [
    {
      "bank_account_num": "110-XXX-XXXXXX",
      "bank_name": "신한은행",
      "balance": 12500000,
      "last_trans_date": "2026-03-11"
    }
  ]
}
```

### 3.5 분개

**Source Type**: `barobill_bank` (`JournalEntry::SOURCE_BAROBILL_BANK`)

---

## 4. 홈택스 세금계산서 API (13개)

**Prefix**: `/api/v1/hometax-invoices`

### 4.1 엔드포인트 목록

| Method | Path | 설명 |
|--------|------|------|
| GET | `/sales` | 매출 계산서 목록 |
| GET | `/purchases` | 매입 계산서 목록 |
| GET | `/summary` | 매출/매입 요약 통계 |
| POST | `/` | 수동 계산서 등록 |
| GET | `/{id}` | 계산서 상세 |
| PUT | `/{id}` | 계산서 수정 |
| DELETE | `/{id}` | 계산서 삭제 (soft delete) |
| GET | `/{id}/journals` | 자체 분개 조회 |
| POST | `/{id}/journals` | 자체 분개 저장 |
| DELETE | `/{id}/journals` | 자체 분개 삭제 |
| GET | `/{id}/journal-entries` | 통합 분개 조회 |
| POST | `/{id}/journal-entries` | 통합 분개 저장 |
| DELETE | `/{id}/journal-entries` | 통합 분개 삭제 |

### 4.2 매출/매입 목록

```
GET /api/v1/hometax-invoices/sales
GET /api/v1/hometax-invoices/purchases
```

**응답**: 각 항목에 `has_journal`(분개 존재 여부) 포함.

### 4.3 요약 통계

```
GET /api/v1/hometax-invoices/summary?start_date=2026-03-01&end_date=2026-03-31
```

```json
{
  "sales": {
    "count": 15,
    "supply_amount": 50000000,
    "tax_amount": 5000000,
    "total_amount": 55000000
  },
  "purchase": {
    "count": 23,
    "supply_amount": 30000000,
    "tax_amount": 3000000,
    "total_amount": 33000000
  }
}
```

### 4.4 이중 분개 시스템

홈택스 세금계산서는 **두 가지 분개 경로**를 제공한다:

| 경로 | 테이블 | 용도 |
|------|--------|------|
| `/{id}/journals` | `hometax_invoice_journals` | 자체 분개 (MNG 호환) |
| `/{id}/journal-entries` | `journal_entries` + `journal_entry_lines` | 통합 분개 (CEO 대시보드) |

**자체 분개** (`/journals`): MNG의 홈택스 분개 패턴을 그대로 지원. 매입/매출별 차변/대변 구조.

```json
{
  "items": [
    {
      "dc_type": "debit",
      "account_code": "15400",
      "account_name": "부가세대급금",
      "debit_amount": 3000000,
      "credit_amount": 0,
      "description": "3월 매입 부가세"
    },
    {
      "dc_type": "credit",
      "account_code": "25300",
      "account_name": "미지급금",
      "debit_amount": 0,
      "credit_amount": 33000000
    }
  ]
}
```

**통합 분개** (`/journal-entries`): `JournalSyncService`를 통해 CEO 대시보드에 자동 연동.

**Source Type**: `hometax_invoice` (`JournalEntry::SOURCE_HOMETAX_INVOICE`)

### 4.5 상수값

| 구분 | 코드 | 설명 |
|------|------|------|
| 과세유형 | `01` | 과세 |
| | `02` | 영세 |
| | `03` | 면세 |
| 영수/청구 | `01` | 영수 |
| | `02` | 청구 |
| 발급유형 | `01` | 정발행 |
| | `02` | 역발행 |

---

## 5. 데이터 패턴

### 5.1 Unique Key

카드/은행 거래는 복합 키로 고유 식별한다.

| 데이터 | Unique Key 형식 |
|--------|----------------|
| 카드 거래 | `card_num\|use_dt\|approval_num\|approval_amount` |
| 은행 거래 | `bank_account_num\|trans_dt\|deposit\|withdraw\|balance` |

분할/숨김/오버라이드 API에서 `unique_key` 파라미터로 사용한다.

### 5.2 수동 거래 vs 동기화 거래

| 구분 | `is_manual` | 수정 | 삭제 | 비고 |
|------|:-----------:|:----:|:----:|------|
| 바로빌 동기화 | `false` | 금액수정만 | 숨김만 | MNG에서 동기화 |
| 수동 입력 | `true` | 가능 | 가능 | `/manual` 엔드포인트 |

---

## 6. 구현 파일 목록

### 6.1 Service (비즈니스 로직)

| 파일 | 설명 |
|------|------|
| `api/app/Services/BarobillCardTransactionService.php` | 카드 거래 서비스 |
| `api/app/Services/BarobillBankTransactionService.php` | 은행 거래 서비스 |
| `api/app/Services/HometaxInvoiceService.php` | 홈택스 세금계산서 서비스 |
| `api/app/Services/JournalSyncService.php` | 통합 분개 서비스 (공용) |

### 6.2 Controller

| 파일 | 엔드포인트 |
|------|----------|
| `api/app/Http/Controllers/Api/V1/BarobillCardTransactionController.php` | 16개 |
| `api/app/Http/Controllers/Api/V1/BarobillBankTransactionController.php` | 13개 |
| `api/app/Http/Controllers/Api/V1/HometaxInvoiceController.php` | 13개 |

### 6.3 Model

| 파일 | 테이블 |
|------|--------|
| `api/app/Models/Barobill/BarobillCardTransaction.php` | `barobill_card_transactions` |
| `api/app/Models/Barobill/BarobillCardTransactionSplit.php` | `barobill_card_transaction_splits` |
| `api/app/Models/Barobill/BarobillCardTransactionHide.php` | `barobill_card_transaction_hides` |
| `api/app/Models/Barobill/BarobillCardTransactionAmountLog.php` | `barobill_card_transaction_amount_logs` |
| `api/app/Models/Barobill/BarobillBankTransaction.php` | `barobill_bank_transactions` |
| `api/app/Models/Barobill/BarobillBankTransactionOverride.php` | `barobill_bank_transaction_overrides` |
| `api/app/Models/Barobill/BarobillBankTransactionSplit.php` | `barobill_bank_transaction_splits` |
| `api/app/Models/Barobill/BarobillBankSyncStatus.php` | `barobill_bank_sync_status` |
| `api/app/Models/Barobill/HometaxInvoice.php` | `hometax_invoices` |
| `api/app/Models/Barobill/HometaxInvoiceJournal.php` | `hometax_invoice_journals` |

### 6.4 라우트

`api/routes/api/v1/finance.php`에 등록.

---

## 7. 기존 API와의 관계

| API | 데이터 소스 | 모델 | 용도 |
|-----|-----------|------|------|
| `card-transactions` | SAM 내부 입력 | `Withdrawal` | SAM 자체 카드 거래 관리 |
| `bank-transactions` | SAM 내부 입력 | `Deposit` + `Withdrawal` | SAM 통합 입출금 조회 |
| **`barobill-card-transactions`** | **바로빌 SOAP 동기화** | **`BarobillCardTransaction`** | **바로빌 카드 데이터 조회** |
| **`barobill-bank-transactions`** | **바로빌 SOAP 동기화** | **`BarobillBankTransaction`** | **바로빌 은행 데이터 조회** |
| **`hometax-invoices`** | **바로빌 SOAP 동기화** | **`HometaxInvoice`** | **홈택스 세금계산서 조회** |

> **설계 결정**: 기존 `card-transactions`/`bank-transactions`는 SAM 자체 데이터를 관리하며, 바로빌 동기화 데이터는 별도 테이블/엔드포인트로 완전 분리한다. 두 데이터 소스가 충돌하지 않는다.

---

## 관련 문서

- [재무 관리](../../features/finance/README.md)
- [바로빌 카카오톡](../../features/barobill-kakaotalk/README.md)
- [API 개발 규칙](../../dev/standards/api-rules.md)
- [options 컬럼 정책](../../dev/standards/options-column-policy.md)

---

**최종 업데이트**: 2026-03-11