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 공통 응답 형식

{
  "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 요청:

{
  "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

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

2.6 수동 입력

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

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

{
  "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 대시보드 복리후생비/접대비 자동 동기화.

{
  "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

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

3.4 잔액 요약

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

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

응답:

{
  "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

{
  "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의 홈택스 분개 패턴을 그대로 지원. 매입/매출별 차변/대변 구조.

{
  "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 자체 데이터를 관리하며, 바로빌 동기화 데이터는 별도 테이블/엔드포인트로 완전 분리한다. 두 데이터 소스가 충돌하지 않는다.

---

관련 문서

• 재무 관리
• 바로빌 카카오톡
• API 개발 규칙
• options 컬럼 정책

---

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