From 1eaf6564e5345a2fd6d068034b25e7060e46b908 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 11 Mar 2026 19:53:11 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[barobill]=20=EB=B0=94=EB=A1=9C?= =?UTF-8?q?=EB=B9=8C=20=ED=9A=8C=EA=B3=84=20=EB=8D=B0=EC=9D=B4=ED=84=B0=20?= =?UTF-8?q?REST=20API=20=EB=AA=85=EC=84=B8=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 카드 거래/은행 거래/홈택스 세금계산서 42개 엔드포인트 명세 - 아키텍처, 데이터 패턴, 분개 시스템, 구현 파일 목록 포함 - INDEX.md에 문서 등록 --- INDEX.md | 2 + frontend/api-specs/barobill-api.md | 500 +++++++++++++++++++++++++++++ 2 files changed, 502 insertions(+) create mode 100644 frontend/api-specs/barobill-api.md diff --git a/INDEX.md b/INDEX.md index 87b1258..fde1b4a 100644 --- a/INDEX.md +++ b/INDEX.md @@ -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/ — 프론트엔드 개발 가이드 diff --git a/frontend/api-specs/barobill-api.md b/frontend/api-specs/barobill-api.md new file mode 100644 index 0000000..a11f598 --- /dev/null +++ b/frontend/api-specs/barobill-api.md @@ -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