# WEHAGO T / SmartA 10 — 전 모듈 입출력 REST API v1 상세 명세서 (`API_REFERENCE.md`)
- **API 버전**: `v1.0.0` (OpenAPI 3.1.0 호환)
- **OpenAPI JSON 경로**: [`/api/v1/openapi.json`](/api/v1/openapi.json)
- **대화형 API 문서 경로**: [`/api/v1/docs`](/api/v1/docs)
- **오류 응답 규격**: `RFC 9457 Problem Details for HTTP APIs` (`application/problem+json`)
- **멱등성 보장**: 모든 변경 요청(`POST`, `PUT`, `PATCH`)에 `Idempotency-Key: <UUID>` 헤더 지원
---
## 1. 아키텍처 개요 및 모듈별 API 범위
웹앱의 **모든 모듈(회계관리·인사급여·법인조정·개인조정·물류관리·T-Edge/홈택스·전자신고)** 및 **전체 607개 법정서식(법인 301·개인 226·회계/부가세 60·원천/연말 30)** 의 입력·수정·자동계산(`CalcProc`)·새로불러오기(`NewLoadProc`)·작성확정(`SCBD0107`)·마감(`iscorclose`/`isrecclose`)·인쇄를 표준 REST API(`/api/v1/*`)로 수행할 수 있습니다.
| 모듈 구분 | 화면 수 | 법정서식 수 | REST API v1 Base Path | WEHAGO T 원본 대응 엔드포인트 |
|---|---:|---:|---|---|
| **수임처·기수 마스터** | 공통 | 공통 | `/api/v1/clients` | `GET /smarta/sabc0102/companyinfo/`, `POST /common/layout/company-change` |
| **회계관리 (`account`)** | 231 | 60 | `/api/v1/account/*` | `/smarta/sabk0102/slip/`, `/smarta/sabk0103/slip/`, `/smarta/sbcm0107/`, `/smarta/savf0101/` |
| **인사/급여 (`humanresource`)** | 181 | 30 | `/api/v1/hr/*` | `/smarta/swpa0101/`, `/smarta/swpm0102/`, `/smarta/swta0101/`, `/smarta/swym0101/` |
| **법인세무조정 (`corporation`)** | 301 | 301 | `/api/v1/corporation/*` | `GET/POST /smarta/cors/`, `/smarta/cors/dynamic_struct/`, `/smarta/cors/union/`, `/smarta/cors/SCBD0107_update/` |
| **개인세무조정 (`income`)** | 226 | 226 | `/api/v1/income/*` | `GET/POST /smarta/rec/`, `/smarta/rec/origin/`, `/smarta/rec/union/`, `/smarta/rec/update_complete/` |
| **법정서식 통합엔진 (`forms`)** | 607 | 607 | `/api/v1/forms/:formCode/*` | `/smarta/cors/*` & `/smarta/rec/*` & `/smarta/cors/print/*` & `/smarta/rec/print/*` |
| **물류/재고관리 (`logistics`)** | 169 | - | `/api/v1/logistics/*` | `/smarta/slsa0101/`, `/smarta/slpu0101/`, `/smarta/sliv0101/` |
| **T-Edge / 홈택스 (`tedge`)** | 175 | - | `/api/v1/tedge/*` | `/smarta/saac0103/` ~ `/smarta/saac0108/` (홈택스 전자증빙 수집·자동전표 전송) |
| **전자신고 변환 (`efiling`)** | 공통 | 공통 | `/api/v1/efiling/generate` | `/smarta/scer0101/`, `/smarta/srer0101/`, `/smarta/saer0101/`, `/smarta/swer0124/` |
| **전체 1,310개 화면 범용 I/O** | 1,310 | 607 | `/api/v1/screens/:screenCode` | WEHAGO T 전체 마이크로프론트엔드 화면 레코드 통합 입출력 |
---
## 2. 공통 규격 (인증 · 헤더 · RFC 9457 오류 응답)
### 2.1 요청 헤더
```http
Content-Type: application/json
Authorization: Bearer <SESSION_TOKEN> # 로컬/개발 환경에서는 생략 시 기본 총관리자 세션 자동 바인딩
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 # 선택: 중복 POST/PUT 실행 방지
```
### 2.2 RFC 9457 표준 오류 응답 (`application/problem+json`)
마감(`isMagam=true`) 또는 작성확정(`isComplete=true`) 상태인 서식에 저장(`PUT`)을 시도하거나 필수 파라미터가 누락된 경우 다음과 같이 반환됩니다.
```json
{
"type": "https://taxflow.wehago.local/problems/http-409",
"title": "Conflict / Form Locked",
"status": 409,
"detail": "작성확정 상태입니다. 확정해제(Ctrl+F4) 후 저장하시기 바랍니다.",
"instance": "/api/v1/forms/SCTP0102/data",
"timestamp": "2026-10-19T09:00:00.000Z"
}
```
---
## 3. 수임처 및 기수 API (`/api/v1/clients`)
### 3.1 전체 791개 수임처 조회
- **Endpoint**: `GET /api/v1/clients`
- **Query Params**:
- `entityType`: `CORP` (법인 92곳) | `INDIV` (개인 699곳)
- `q`: 상호·코드·사업자등록번호·대표자명 검색
- `limit`: 페이지 크기 (기본 `791`)
- `offset`: 시작 오프셋 (기본 `0`)
```bash
curl -s "http://localhost:3100/api/v1/clients?entityType=CORP&limit=5"
```
### 3.2 수임처 신규 등록 / 수정
- **Endpoint**: `POST /api/v1/clients`
```bash
curl -X POST "http://localhost:3100/api/v1/clients" \
-H "Content-Type: application/json" \
-d '{
"code": "9901",
"name": "(주)스마트택스랩",
"biz_no": "214-88-99012",
"ceo_name": "김대표",
"entity_type": "CORP",
"current_gisu": 12,
"fiscal_year": 2025
}'
```
### 3.3 수임처별 전 기수(제1기 2014 ~ 제13기 2026) 원장·대차 검증 조회
- **Endpoint**: `GET /api/v1/clients/:clientId/periods`
```bash
curl -s "http://localhost:3100/api/v1/clients/1/periods"
```
---
## 4. 회계관리 모듈 API (`/api/v1/account/*`)
### 4.1 계정과목표 조회 및 등록
- `GET /api/v1/account/accounts` — 56개 표준 계정과목 및 연결 법정서식(`SCSU0101`, `SCSU0102`, `SAVF0101` 등) 조회
- `POST /api/v1/account/accounts` — 계정과목 추가/수정
### 4.2 전표 조회 및 입력 (`SABK0102` 일반전표 / `SABK0103` 매입매출전표)
- `GET /api/v1/account/vouchers?clientId=1&gisu=12&voucherType=GENERAL`
- `POST /api/v1/account/vouchers` — 전표 입력 시 `autoBalance: true`(기본값)이면 상대계정(기본 `103 보통예금`)을 자동으로 복식부기 분개하여 차변·대변 일치(`balanced: true`)를 보장합니다.
```bash
curl -X POST "http://localhost:3100/api/v1/account/vouchers" \
-H "Content-Type: application/json" \
-d '{
"clientId": 1,
"gisu": 12,
"voucher_date": "2025-12-31",
"voucher_type": "GENERAL",
"acct_code": "811",
"acct_name": "복리후생비",
"dr_cr": "DR",
"amount": 250000,
"partner_name": "안암회관",
"summary": "결산 야근식대 지급",
"autoBalance": true
}'
```
### 4.3 합계잔액시산표(`SBCM0107`) 및 부가가치세신고서(`SAVF0101`)
- `GET /api/v1/account/ledgers/trial-balance?clientId=1&gisu=12`
- `GET /api/v1/account/vat/returns?clientId=1&gisu=12`
- `POST /api/v1/account/vat/returns`
---
## 5. 인사/급여 모듈 API (`/api/v1/hr/*`)
### 5.1 사원 및 급여대장 조회·등록 (`SWPA0101` / `SWPM0102`)
- `GET /api/v1/hr/employees?clientId=1&gisu=12`
- `POST /api/v1/hr/employees` — 기본급(`base_salary`), 비과세식대(`meal_allowance`), 상여(`bonus`) 입력 시 국민연금(4.5%), 건강보험(3.545%), 장기요양보험(12.95%), 고용보험(0.9%), 근로소득 간이세액 및 지방소득세를 자동 계산하여 저장합니다.
### 5.2 급여·4대보험 시뮬레이션 및 원천징수이행상황신고서(`SWTA0101`)
- `POST /api/v1/hr/payroll/calculate`
- `GET /api/v1/hr/withholding?clientId=1&gisu=12`
- `POST /api/v1/hr/withholding`
---
## 6. 법인세무조정 (`/api/v1/corporation/*`) & 개인세무조정 (`/api/v1/income/*`)
### 6.1 세무조정 항목 조회 및 등록 (`SCIR0101` / `SRTB0101`)
- `GET /api/v1/corporation/adjustments?clientId=1&gisu=12`
- `POST /api/v1/corporation/adjustments`
- `GET /api/v1/income/adjustments?clientId=3&gisu=12`
- `POST /api/v1/income/adjustments`
### 6.2 모듈별 전체 법정서식 목록 및 개별 서식 입출력
- `GET /api/v1/corporation/forms` (301개 법인조정 서식 전체)
- `GET /api/v1/corporation/forms/:formCode?clientId=1&gisu=12`
- `PUT /api/v1/corporation/forms/:formCode`
- `GET /api/v1/income/forms` (226개 개인조정 서식 전체)
- `GET /api/v1/income/forms/:formCode?clientId=3&gisu=12`
- `PUT /api/v1/income/forms/:formCode`
---
## 7. 법정서식 100% 동일 작성 엔진 API (`/api/v1/forms/:formCode/*`)
WEHAGO T의 법정서식 마이크로프론트엔드(`SAOCorpBusinessForm` + `PAGE_n.GRP_n.CODE_n` + `CalcProc` + `union`)와 100% 동일한 데이터 구조로 동작합니다.
| 기능 | Method & Endpoint | WEHAGO 원본 대응 액션 | 설명 |
|---|---|---|---|
| **서식 카탈로그** | `GET /api/v1/forms` | 메뉴 라우트 메타 | 607개 법정서식(법인 301·개인 226·회계 60·급여 30) 검색 |
| **서식 스키마** | `GET /api/v1/forms/:formCode/schema` | `dynamic_struct` + 정적번들 | 별지 서식번호, DRF, 탭(`1.정기신고`/`2.수정신고`), 툴바, 섹션·코드행 정의 |
| **서식 데이터 조회** | `GET /api/v1/forms/:formCode/data` | `callSelectAPI("select_main")` | `cells` (`CODE_101..`), `unionMap` (`FCTP0102` 등), `isComplete`, `isMagam` 반환 |
| **서식 데이터 저장** | `PUT /api/v1/forms/:formCode/data` | `insert_main` + `insert_union` | 입력 셀 저장 후 `CalcProc` 전 행 재계산 및 `union` 코드표 자동 갱신 |
| **실시간 산식계산** | `POST /api/v1/forms/:formCode/calculate` | `CalcProc` / `calculateDataState` | 저장 전 입력값 변경에 따른 계산행·세율·산출세액·차감납부세액 실시간 계산 |
| **새로불러오기** | `POST /api/v1/forms/:formCode/reload` | `onNewLoad` / `NewLoadProc` | 전표·손익계산서·세무조정합계표·급여대장·하위서식 `union`에서 값 재이관 |
| **일괄삭제** | `POST /api/v1/forms/:formCode/clear` | `onDeleteClickAll` (F6) | 해당 서식 셀 데이터 초기화 |
| **작성확정 / 마감** | `POST /api/v1/forms/:formCode/lock` | `SCBD0107_update` / `iscorclose` | `[작성확정 / 확정해제]`(`isComplete`) 및 `[마감 / 마감해제]`(`isMagam`) 토글 |
| **별지서식 인쇄** | `GET /api/v1/forms/:formCode/print` | `Common.Print.exe` (`*.drf`) | 국가법령정보센터 `별지 제N호서식` A4 공식 인쇄용 HTML 반환 |
### 예시: `SCTP0102` (법인세과세표준 및 세액조정계산서 — 별지 제3호서식) 셀 수정 및 자동계산
```bash
curl -X PUT "http://localhost:3100/api/v1/forms/SCTP0102/data" \
-H "Content-Type: application/json" \
-d '{
"clientId": 1,
"gisu": 12,
"singoGubun": "1",
"cells": {
"101": { "value": 719607724, "remark": "결산서상 당기순손익" },
"102": { "value": 1500000, "remark": "익금산입 조정" },
"103": { "value": 300000, "remark": "손금산입 조정" },
"109": { "value": 10000000, "remark": "이월결손금 공제" }
}
}'
```
위 요청 시 서버의 `CalcProc` 엔진이 즉시 다음 행들을 연쇄 계산하여 반환합니다:
- `(104) 차가감소득금액` = `101 + 102 - 103` = `720,807,724`
- `(107) 각사업연도소득금액` = `104 + 105 - 106`
- `(112) 과세표준` = `108 - 109 - 110 - 111`
- `(114) 세율` = `19%` (2억 이하 9% + 2억 초과분 19% 누진)
- `(115) 산출세액` = `200,000,000 × 9% + (과세표준 - 200,000,000) × 19%`
- `(134) 차가감납부할세액` 및 `(158) 차감납부세액`
- `unionMap` (`FCTP0102` `001`~`034`) 자동 생성
---
## 8. 물류관리 (`/api/v1/logistics/*`), T-Edge 홈택스 (`/api/v1/tedge/*`), 전자신고 (`/api/v1/efiling/*`)
- `GET /api/v1/logistics/records?clientId=1&gisu=12&screenCode=SLSA0101`
- `POST /api/v1/logistics/records`
- `GET /api/v1/tedge/hometax-items?clientId=1&gisu=12`
- `POST /api/v1/tedge/hometax-items/collect`
- `POST /api/v1/tedge/hometax-items/transmit`
- `POST /api/v1/efiling/generate` (`taxType`: `CORP` | `INCOME` | `VAT` | `WITHHOLDING`)
- `GET /api/v1/screens/:screenCode?clientId=1&gisu=12` & `POST /api/v1/screens/:screenCode/records`