# 계정별원장·손익계산서 API 명세 > **작성일**: 2026-03-19 > **상태**: API 완료, React 미구현 > **대상**: React 프론트엔드 개발자 --- ## 1. 개요 회계/세무 메뉴에 **계정별원장**과 **손익계산서** 2개 화면을 추가한다. 일반전표 + 홈택스 세금계산서 분개 데이터를 통합 조회하여 계정별 거래 내역과 기간별 손익 현황을 표시한다. ### 메뉴 위치 (MNG 기준) ``` 회계/세무관리 ├── 일반전표입력 ← 기존 ├── 계정별원장 ← NEW ├── 손익계산서 ← NEW ├── 전자세금계산서 ← 기존 ├── ... ``` --- ## 2. 계정별원장 API ### 2.1 엔드포인트 | Method | Path | 설명 | |--------|------|------| | `GET` | `/api/v1/account-ledger` | 계정별원장 조회 | ### 2.2 요청 파라미터 | 파라미터 | 타입 | 필수 | 설명 | |---------|------|:----:|------| | `start_date` | `string(date)` | Y | 조회 시작일 (`2026-01-01`) | | `end_date` | `string(date)` | Y | 조회 종료일 (`2026-03-19`) | | `account_code` | `string` | Y | 계정과목 코드 (`81100`) | ### 2.3 응답 구조 ```typescript interface AccountLedgerResponse { success: boolean; message: string; data: { account: { code: string; // "81100" name: string; // "복리후생비" category: string; // "expense" } | null; period: { start_date: string; // "2026-01-01" end_date: string; // "2026-03-19" }; carry_forward: { debit: number; // 이월 차변 합계 credit: number; // 이월 대변 합계 balance: number; // 이월 잔액 }; monthly_data: MonthlyData[]; grand_total: { debit: number; credit: number; balance: number; }; }; } interface MonthlyData { month: string; // "2026-03" items: LedgerItem[]; subtotal: { debit: number; credit: number }; cumulative: { debit: number; credit: number }; } interface LedgerItem { date: string; // "2026-03-01" description: string | null; // 적요 trading_partner_name: string | null; // 거래처명 biz_no: string | null; // 사업자번호 debit_amount: number; // 차변 금액 credit_amount: number; // 대변 금액 balance: number; // 누적 잔액 source_type: 'journal' | 'hometax'; // 출처 source_id: number; // 전표ID 또는 홈택스 인보이스ID } ``` ### 2.4 잔액 계산 규칙 | 계정 카테고리 | 정상 잔액 | 계산 | |-------------|----------|------| | `asset` (자산) | 차변 | 차변 - 대변 | | `expense` (비용) | 차변 | 차변 - 대변 | | `liability` (부채) | 대변 | 대변 - 차변 | | `capital` (자본) | 대변 | 대변 - 차변 | | `revenue` (수익) | 대변 | 대변 - 차변 | ### 2.5 화면 요구사항 - **조회 필터**: 기간(date range) + 계정과목 검색 (코드/이름) - **계정과목 목록**: 기존 `GET /api/v1/account-subjects` 활용 - **테이블 구조**: 날짜, 적요, 거래처, 사업자번호, 차변, 대변, 잔액 - **월별 소계/누계**: 월이 바뀔 때마다 소계 행 + 누계 행 표시 - **이월잔액**: 조회 시작일 이전 잔액 (첫 행에 표시) - **드릴다운**: 행 클릭 시 원본 전표 상세 조회 (`source_type` + `source_id`) - `journal` → `GET /api/v1/general-journal-entries/{source_id}` - `hometax` → 홈택스 세금계산서 상세 - **홈택스 태그**: `source_type === 'hometax'`인 행에 `[홈택스]` 표시 --- ## 3. 손익계산서 API ### 3.1 엔드포인트 | Method | Path | 설명 | |--------|------|------| | `GET` | `/api/v1/income-statement` | 기간 손익계산서 조회 | | `GET` | `/api/v1/income-statement/monthly` | 월별 손익계산서 조회 | ### 3.2 기간 조회 파라미터 | 파라미터 | 타입 | 필수 | 설명 | |---------|------|:----:|------| | `start_date` | `string(date)` | Y | 당기 시작일 (`2026-01-01`) | | `end_date` | `string(date)` | Y | 당기 종료일 (`2026-12-31`) | | `unit` | `string` | N | `won` (기본) / `thousand` / `million` | > **전기**: API가 자동으로 전년 동기를 계산 (예: 2026 → 2025) > **기수**: 코드브릿지엑스 설립 2025-09-13 기준, 제1기 = 2025년, 제2기 = 2026년 ### 3.2.1 월별 조회 파라미터 | 파라미터 | 타입 | 필수 | 설명 | |---------|------|:----:|------| | `year` | `integer` | Y | 조회 연도 (`2026`) | | `unit` | `string` | N | `won` (기본) / `thousand` / `million` | ### 3.3 응답 구조 ```typescript interface IncomeStatementResponse { success: boolean; message: string; data: { period: { current: { start: string; end: string; label: string }; // "제 22 (당)기" previous: { start: string; end: string; label: string }; // "제 21 (전)기" }; unit: 'won' | 'thousand' | 'million'; sections: PLSection[]; }; } interface PLSection { code: string; // "I", "II", ... "X" name: string; // "매출액", "매출원가", ... current_amount: number; // 당기 금액 previous_amount: number; // 전기 금액 items: PLItem[]; // 세부 계정과목 (계산 항목은 빈 배열) is_calculated: boolean; // true = 계산 항목 (III, V, VIII, X) } interface PLItem { code: string; // 계정코드 "40100" name: string; // 계정명 "상품매출" current: number; // 당기 금액 previous: number; // 전기 금액 } ``` ### 3.3.1 월별 조회 응답 구조 ```typescript interface MonthlyIncomeStatementResponse { success: boolean; message: string; data: { year: number; // 2026 fiscal_year: number; // 2 (제2기) fiscal_label: string; // "제 2 기" unit: 'won' | 'thousand' | 'million'; months: MonthPL[]; }; } interface MonthPL { month: string; // "01", "02", ... label: string; // "1월", "2월", ... sections: PLSection[]; // 해당 월의 손익 항목 (current_amount만 유효, previous_amount는 0) } ``` ### 3.4 손익계산서 구조 ``` I. 매출액 ← sales_revenue 계정 합계 II. 매출원가 ← cogs + construction_cost 계정 합계 III. 매출총이익 = I - II ← 계산 (is_calculated: true) IV. 판매비와관리비 ← selling_admin 계정 합계 V. 영업이익 = III - IV ← 계산 VI. 영업외수익 ← other_revenue 계정 합계 VII. 영업외비용 ← other_expense 계정 (법인세 제외) VIII.법인세비용차감전순이익 ← 계산 (V + VI - VII) IX. 법인세비용 ← 계정코드 99800(법인세) + 99900(소득세등) X. 당기순이익 = VIII - IX ← 계산 ``` ### 3.5 화면 요구사항 - **보기 모드 토글**: `[기간 보기]` / `[월별 보기]` - **당기/전기 토글**: `[당기만]` / `[당기+전기]` (기간 보기에서만) - **조회 필터**: 기간(date range) 또는 연도 + 금액 단위 선택 - **기간 보기 테이블**: 과목 | 당기 금액(2열) | 전기 금액(2열, 토글로 숨김 가능) - **월별 보기**: 연도 선택 → 월별 버튼(1~12월) → 개별 월 또는 전체 비교 - **당기 컬럼 2열**: 세부 금액(왼쪽) + 소계(오른쪽) - 세부 항목이 있는 섹션: 마지막 행의 오른쪽 열에 소계 표시 - 계산 항목(`is_calculated`): 오른쪽 열에만 금액 표시 - **계산 항목 강조**: III(매출총이익), V(영업이익), X(당기순이익) 등 배경색 구분 - **들여쓰기**: 세부 항목(`items`)은 과목 이름 앞에 들여쓰기 - **단위 표시**: 하단에 `(단위: 원)` 등 표시 - **인쇄**: 인쇄 버튼 (CSS `@media print` 활용) --- ## 4. 참고: MNG 구현 화면 MNG(백오피스)에는 이미 동일 기능이 구현되어 있다. 화면 레이아웃과 UX를 참고한다. - **계정별원장**: 더존 프로그램 스타일의 원장 뷰 + 행 클릭 시 전표 상세 모달 - **손익계산서**: 더존 프로그램 스타일의 P&L 테이블 + 당기/전기 비교 > MNG 개발서버: `https://admin.codebridge-x.com` → 회계/세무관리 메뉴 --- ## 5. 관련 API | API | 용도 | |-----|------| | `GET /api/v1/account-subjects` | 계정과목 목록 (계정별원장 필터용) | | `GET /api/v1/general-journal-entries/{id}` | 전표 상세 (계정별원장 드릴다운) | --- ## 관련 문서 - [dev/dev_plans/account-ledger-income-statement-plan.md](../../dev/dev_plans/account-ledger-income-statement-plan.md) — 전체 기획서 - [features/finance/README.md](../../features/finance/README.md) — 재무관리 기능 개요 - [frontend/api-specs/barobill-api.md](barobill-api.md) — 바로빌 회계 API 명세 --- **최종 업데이트**: 2026-03-19