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

docs: [barobill] 바로빌 회계 데이터 REST API 명세 추가

Browse Source 
- 카드 거래/은행 거래/홈택스 세금계산서 42개 엔드포인트 명세
- 아키텍처, 데이터 패턴, 분개 시스템, 구현 파일 목록 포함
- INDEX.md에 문서 등록
This commit is contained in:
김보곤
2026-03-11 19:53:11 +09:00
parent dbc34e826d
commit 1eaf6564e5
2 changed files with 502 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
INDEX.md
View File

@@ -20,6 +20,7 @@
| 단가관리 | `rules/pricing-policy.md` | 원가/판매가, 리비전 |
| 견적관리 | `features/quotes/README.md` | 견적 시스템, BOM 계산 |
| 급여관리 API | `frontend/api-specs/payroll-api.md` | 급여관리 API 전체 명세 (18개 엔드포인트) |
| 바로빌 회계 API | `frontend/api-specs/barobill-api.md` | 카드/은행/홈택스 REST API (42개 엔드포인트) |
| 결재관리 | `dev/dev_plans/approval-system-unification-plan.md` | MNG→API 결재 통합 계획 |
| 운영 배포 | `dev/dev_plans/production-deployment-plan.md` | 배포 계획 |
| 서버 운영 | `dev/deploys/ops-manual/README.md` | 서버 운영 매뉴얼 |
@@ -211,6 +212,7 @@ DB 도메인별:
| [approval-api.md](frontend/api-specs/approval-api.md) | 결재관리 API 전체 명세 (28개 엔드포인트) |
| [document-api-integration.md](frontend/api-specs/document-api-integration.md) | 문서 API 연동 명세 |
| [payroll-api.md](frontend/api-specs/payroll-api.md) | 급여관리 API 전체 명세 (18개 엔드포인트) |
| [barobill-api.md](frontend/api-specs/barobill-api.md) | 바로빌 회계 데이터 API 명세 (42개 엔드포인트) |
### frontend/integration/ — 프론트엔드 개발 가이드

500
frontend/api-specs/barobill-api.md Normal file
View File

@@ -0,0 +1,500 @@
# 바로빌 회계 데이터 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