SamProject/sam-docs
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
220ab78041d2b1ca712d9381ffa89871cd2d79e9
sam-docs/frontend/api-specs/account-ledger-income-statement-api.md
김보곤 5effbb8a0b docs: [finance] 계정코드 마이그레이션 이력 + 손익계산서 API 명세 업데이트 
- 더존 3자리→KIS 5자리 코드 마이그레이션 기록 (832건)
- 손익계산서 월별 API 명세 추가
- 당기/전기 토글, 월별 보기 화면 요구사항 추가
2026-03-19 12:51:02 +09:00

8.7 KiB
Raw Blame History

계정별원장·손익계산서 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 응답 구조

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 응답 구조

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 월별 조회 응답 구조

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} 전표 상세 (계정별원장 드릴다운)

관련 문서

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