{"openapi":"3.1.0","info":{"title":"TaxFlow AI — WEHAGO T / SmartA 10 Unified REST API","version":"1.0.0","summary":"WEHAGO T / SmartA 10 전 모듈(회계·급여·법인조정·개인조정·물류·T-Edge/홈택스) 및 607개 국세청 법정서식(별지 서식) 100% 입출력 REST API 명세","description":"동성회계법인 WEHAGO T 등록 791개 수임처 × 13개 기수(2014~2026) × 1,310개 전체 화면 및 607개 법정서식(법인 301·개인 226·회계/부가세 60·원천/연말 30)의 모든 입력·계산(CalcProc)·새로불러오기(NewLoadProc)·작성확정(SCBD0107)·마감(iscorclose/isrecclose)·별지서식 인쇄·국세청 전자신고(.201/.101)를 API로 수행할 수 있는 표준 REST API v1 명세서입니다.","contact":{"name":"TaxFlow AI Architecture Team"}},"servers":[{"url":"https://taxflow.srv1827974.hstgr.cloud","description":"Hostinger Production VPS"},{"url":"http://localhost:3100","description":"Local Development Server"}],"tags":[{"name":"Discovery","description":"API 인덱스, OpenAPI 3.1 명세 및 대화형 문서"},{"name":"Clients","description":"791개 수임처(법인 92 / 개인 699) 및 13개 회계기수(제1기~제13기) 입출력"},{"name":"Account","description":"회계관리 모듈 (231개 화면: 일반전표 SABK0102, 매입매출전표 SABK0103, 시산표 SBCM0107, 재무제표 SBCM0101/0102, 부가가치세신고서 SAVF0101)"},{"name":"HR","description":"인사/급여 모듈 (181개 화면: 사원등록 SWPA0101, 급여자료입력 SWPM0102, 4대보험·간이세액 계산, 원천징수이행상황신고서 SWTA0101, 연말정산 SWYM0101)"},{"name":"Corporation","description":"법인세무조정 모듈 (301개 화면: 법인세과세표준및세액조정계산서 SCTP0102, 소득금액조정합계표 SCIR0101, 표준재무제표 SCSU0101~0103, 농특세 SCCF0102 등)"},{"name":"Income","description":"개인세무조정 모듈 (226개 화면: 종합소득세신고서 SRTP0102, 과세표준및세액계산서 SRTB0101, 전자계산서세액공제 SRDO0123, 경정청구서 SRDV0116 등)"},{"name":"StatutoryForms","description":"국세청 법정서식(별지 제N호서식) 100% 동일 작성·자동계산(CalcProc)·원장연계 새로불러오기(NewLoadProc)·작성확정·마감·A4 인쇄 엔진"},{"name":"Logistics","description":"물류/재고관리 모듈 (169개 화면: 견적·수주·출고·매입·재고수불부)"},{"name":"TEdge","description":"T-Edge / 홈택스 전자세금계산서·신용카드·현금영수증 스크래핑 수집 및 전표 자동전송 (175개 화면)"},{"name":"EFiling","description":"국세청 홈택스 전자신고 변환파일(.201 / .101) 생성"},{"name":"UniversalScreens","description":"전체 1,310개 WEHAGO 화면 범용 데이터 조회 및 저장"}],"paths":{"/api/v1":{"get":{"tags":["Discovery"],"summary":"REST API v1 전체 모듈 요약 및 엔드포인트 인덱스 조회","responses":{"200":{"description":"API v1 모듈 카탈로그 반환"}}}},"/api/v1/openapi.json":{"get":{"tags":["Discovery"],"summary":"OpenAPI 3.1.0 JSON 스키마 조회","responses":{"200":{"description":"OpenAPI 3.1.0 문서 반환"}}}},"/api/v1/docs":{"get":{"tags":["Discovery"],"summary":"REST API v1 상세 레퍼런스 문서 조회 (HTML / Markdown)","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["html","md"]}}],"responses":{"200":{"description":"API 상세 문서 반환"}}}},"/api/v1/clients":{"get":{"tags":["Clients"],"summary":"791개 수임처 목록 및 기수별 전표·세무조정 요약 조회","parameters":[{"name":"entityType","in":"query","schema":{"type":"string","enum":["CORP","INDIV"]},"description":"법인(CORP) 또는 개인(INDIV) 필터"},{"name":"q","in":"query","schema":{"type":"string"},"description":"수임처명·코드·사업자번호·대표자명 검색어"},{"name":"limit","in":"query","schema":{"type":"integer","default":791}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"수임처 배열 및 메타데이터 반환"}}},"post":{"tags":["Clients"],"summary":"신규 수임처 등록 또는 기존 수임처 정보 수정 (Upsert)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientInput"}}}},"responses":{"201":{"description":"등록/수정된 수임처 정보 반환"},"400":{"$ref":"#/components/responses/Problem400"}}}},"/api/v1/clients/{clientId}/periods":{"get":{"tags":["Clients"],"summary":"특정 수임처의 전체 13개 기수(제1기 2014 ~ 제13기 2026) 원장·대차균형·세무조정 요약 조회","parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"수임처 상세 및 13개 기수 배열 반환"},"404":{"$ref":"#/components/responses/Problem404"}}}},"/api/v1/account/accounts":{"get":{"tags":["Account"],"summary":"표준 계정과목표(Chart of Accounts) 및 세무조정 서식 매핑 조회","responses":{"200":{"description":"계정과목 목록 반환"}}},"post":{"tags":["Account"],"summary":"계정과목 추가 또는 수정","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string","example":"831"},"name":{"type":"string","example":"지급수수료"},"category":{"type":"string","example":"판관비"},"normal_side":{"type":"string","enum":["DR","CR"],"default":"DR"},"tax_adj_form":{"type":"string","example":"SCSU0102"}}}}}},"responses":{"201":{"description":"저장된 계정과목 반환"}}}},"/api/v1/account/vouchers":{"get":{"tags":["Account"],"summary":"전표 목록 조회 (일반전표 SABK0102 / 매입매출전표 SABK0103 대응)","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}},{"name":"voucherType","in":"query","schema":{"type":"string","enum":["GENERAL","SALES_TAX","PURCHASE_TAX","CARD_PURCHASE"]}},{"name":"acctCode","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"전표 목록 및 차변/대변 합계·대차일치 여부 반환"}}},"post":{"tags":["Account"],"summary":"신규 전표 입력 (복식부기 자동 상대계정 분개 지원)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoucherInput"}}}},"responses":{"201":{"description":"생성된 전표 행 반환"},"400":{"$ref":"#/components/responses/Problem400"}}}},"/api/v1/account/ledgers/trial-balance":{"get":{"tags":["Account"],"summary":"합계잔액시산표(SBCM0107) 및 계정별 차변·대변·잔액 집계 조회","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"합계잔액시산표 반환"}}}},"/api/v1/account/vat/returns":{"get":{"tags":["Account"],"summary":"부가가치세신고서(SAVF0101, 별지 제21호서식) 조회","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"부가가치세 법정서식 데이터 반환"}}},"post":{"tags":["Account"],"summary":"부가가치세신고서(SAVF0101) 셀 수정 및 자동계산 저장","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatutoryFormSaveInput"}}}},"responses":{"200":{"description":"저장된 부가가치세신고서 반환"}}}},"/api/v1/hr/employees":{"get":{"tags":["HR"],"summary":"사원 목록 및 급여·4대보험·원천징수세액 내역 조회 (SWPA0101 / SWPM0102)","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"사원 및 급여대장 반환"}}},"post":{"tags":["HR"],"summary":"사원 등록 및 월 급여·4대보험·간이세액 자동계산 저장","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeInput"}}}},"responses":{"201":{"description":"등록된 사원 및 4대보험/원천세 계산 결과 반환"}}}},"/api/v1/hr/payroll/calculate":{"post":{"tags":["HR"],"summary":"급여·비과세식대·상여금 기준 4대보험(국민·건강·장기요양·고용) 및 근로소득 간이세액 계산","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"base_salary":{"type":"number","example":5000000},"meal_allowance":{"type":"number","example":200000},"bonus":{"type":"number","example":1000000}}}}}},"responses":{"200":{"description":"계산된 공제액 및 차인지급액 반환"}}}},"/api/v1/hr/withholding":{"get":{"tags":["HR"],"summary":"원천징수이행상황신고서(SWTA0101, 별지 제21호서식) 조회","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"원천징수이행상황신고서 법정서식 데이터 반환"}}}},"/api/v1/corporation/adjustments":{"get":{"tags":["Corporation"],"summary":"법인 세무조정 내역(SCIR0101) 및 법인세과세표준및세액조정계산서(SCTP0102) 요약 조회","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"법인 세무조정 및 FCTP0102 union 요약 반환"}}},"post":{"tags":["Corporation"],"summary":"법인 세무조정(익금산입·손금불산입 / 손금산입·익금불산입) 항목 추가","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxAdjustmentInput"}}}},"responses":{"201":{"description":"생성된 세무조정 항목 반환"}}}},"/api/v1/income/adjustments":{"get":{"tags":["Income"],"summary":"개인 세무조정 내역(SRTB0101) 및 종합소득세신고서(SRTP0102) 요약 조회","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":3}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"개인 세무조정 및 FRTP0102 union 요약 반환"}}},"post":{"tags":["Income"],"summary":"개인 세무조정(총수입금액산입·필요경비불산입 등) 항목 추가","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxAdjustmentInput"}}}},"responses":{"201":{"description":"생성된 개인 세무조정 항목 반환"}}}},"/api/v1/forms":{"get":{"tags":["StatutoryForms"],"summary":"전체 607개 법정서식(법인 301·개인 226·회계 60·급여 30) 카탈로그 조회","parameters":[{"name":"module","in":"query","schema":{"type":"string","enum":["corporation","income","account","humanresource"]}},{"name":"q","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"법정서식 카탈로그 반환"}}}},"/api/v1/forms/{formCode}/schema":{"get":{"tags":["StatutoryForms"],"summary":"특정 법정서식의 별지 서식번호·탭·툴바·구획(Section)·코드행(Row)·산식(CalcProc)·WEHAGO API 계약 조회","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}}],"responses":{"200":{"description":"법정서식 스키마 반환"}}}},"/api/v1/forms/{formCode}/data":{"get":{"tags":["StatutoryForms"],"summary":"법정서식 작성 데이터(PAGE_n.GRP_n.CODE_n 셀 값·CalcProc 계산결과·union 연계값·확정/마감 상태) 조회","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}},{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}},{"name":"singoGubun","in":"query","schema":{"type":"string","enum":["1","2"],"default":"1"},"description":"1: 정기신고, 2: 수정신고"}],"responses":{"200":{"description":"법정서식 셀 데이터 및 union 연계값 반환"}}},"put":{"tags":["StatutoryForms"],"summary":"법정서식 셀 입력값 저장 및 WEHAGO CalcProc 자동재계산 + union 테이블 반영","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatutoryFormSaveInput"}}}},"responses":{"200":{"description":"저장 및 재계산 완료된 서식 상태 반환"},"409":{"description":"마감 또는 작성확정 상태인 서식 수정 시 충돌 에러 (RFC 9457 problem+json)"}}}},"/api/v1/forms/{formCode}/calculate":{"post":{"tags":["StatutoryForms"],"summary":"법정서식 후보 셀 값에 대한 실시간 CalcProc 산식 검증 및 세액 계산 (비저장 시뮬레이션)","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatutoryFormSaveInput"}}}},"responses":{"200":{"description":"재계산된 셀 및 union 값 반환"}}}},"/api/v1/forms/{formCode}/reload":{"post":{"tags":["StatutoryForms"],"summary":"WEHAGO [새로불러오기] (NewLoadProc / onNewLoad) 실행 — 회계원장·전표·급여·세무조정·하위서식 union 값 재이관","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"integer","default":1},"gisu":{"type":"integer","default":12},"singoGubun":{"type":"string","default":"1"}}}}}},"responses":{"200":{"description":"새로불러오기 완료된 서식 상태 반환"}}}},"/api/v1/forms/{formCode}/lock":{"post":{"tags":["StatutoryForms"],"summary":"WEHAGO [작성확정 / 확정해제] (SCBD0107_update) 및 [마감 / 마감해제] (iscorclose/isrecclose) 상태 전환","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"integer","default":1},"gisu":{"type":"integer","default":12},"singoGubun":{"type":"string","default":"1"},"isComplete":{"type":"boolean"},"isMagam":{"type":"boolean"}}}}}},"responses":{"200":{"description":"변경된 확정/마감 상태 반환"}}}},"/api/v1/forms/{formCode}/print":{"get":{"tags":["StatutoryForms"],"summary":"국가법령정보센터 별지 제N호서식 A4 공식 인쇄용 HTML 렌더링","parameters":[{"name":"formCode","in":"path","required":true,"schema":{"type":"string","example":"SCTP0102"}},{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"A4 인쇄용 HTML 문서 반환"}}}},"/api/v1/logistics/records":{"get":{"tags":["Logistics"],"summary":"물류/재고관리 화면 레코드 조회 (169개 물류 화면 연동)","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}},{"name":"screenCode","in":"query","schema":{"type":"string","default":"SLSA0101"}}],"responses":{"200":{"description":"물류 레코드 반환"}}},"post":{"tags":["Logistics"],"summary":"물류/재고관리 신규 전표·품목·수불 레코드 입력","responses":{"201":{"description":"생성된 물류 레코드 반환"}}}},"/api/v1/tedge/hometax-items":{"get":{"tags":["TEdge"],"summary":"홈택스 전자세금계산서·계산서·법인카드·현금영수증 수집 내역 및 계정추천 상태 조회 (SAAC0103~SAAC0108)","parameters":[{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"홈택스 수집 내역 반환"}}}},"/api/v1/tedge/hometax-items/collect":{"post":{"tags":["TEdge"],"summary":"공인인증서 기반 홈택스/여신금융협회 전자증빙 자동수집 실행","responses":{"200":{"description":"수집 결과 반환"}}}},"/api/v1/tedge/hometax-items/transmit":{"post":{"tags":["TEdge"],"summary":"수집된 홈택스 전자증빙을 일반전표(SABK0102) / 매입매출전표(SABK0103)로 자동전송","responses":{"200":{"description":"전표 전송 결과 반환"}}}},"/api/v1/efiling/generate":{"post":{"tags":["EFiling"],"summary":"국세청 홈택스 전자신고 변환파일(.201 법인세 / .101 종합소득세 / 부가세 / 원천세) 생성","responses":{"200":{"description":"전자신고 파일 레이아웃 및 검증 결과 반환"}}}},"/api/v1/screens/{screenCode}":{"get":{"tags":["UniversalScreens"],"summary":"전체 1,310개 WEHAGO 화면 범용 스키마·명세·저장 레코드 조회","parameters":[{"name":"screenCode","in":"path","required":true,"schema":{"type":"string","example":"SABK0102"}},{"name":"clientId","in":"query","schema":{"type":"integer","default":1}},{"name":"gisu","in":"query","schema":{"type":"integer","default":12}}],"responses":{"200":{"description":"화면 메타데이터 및 레코드 반환"}}},"post":{"tags":["UniversalScreens"],"summary":"전체 1,310개 WEHAGO 화면 범용 레코드 입력/저장","parameters":[{"name":"screenCode","in":"path","required":true,"schema":{"type":"string","example":"SABK0102"}}],"responses":{"201":{"description":"저장된 레코드 ID 반환"}}}}},"components":{"schemas":{"ClientInput":{"type":"object","required":["name","biz_no"],"properties":{"code":{"type":"string","example":"5324"},"name":{"type":"string","example":"(주)경도기술"},"biz_no":{"type":"string","example":"209-81-62301"},"corp_no":{"type":"string","example":"110111-5473056"},"ceo_name":{"type":"string","example":"배명호"},"entity_type":{"type":"string","enum":["CORP","INDIV"],"default":"CORP"},"current_gisu":{"type":"integer","default":12},"fiscal_year":{"type":"integer","default":2025}}},"VoucherInput":{"type":"object","required":["acct_code","amount"],"properties":{"clientId":{"type":"integer","default":1},"gisu":{"type":"integer","default":12},"voucher_date":{"type":"string","example":"2025-12-31"},"voucher_type":{"type":"string","default":"GENERAL"},"acct_code":{"type":"string","example":"811"},"acct_name":{"type":"string","example":"복리후생비"},"dr_cr":{"type":"string","enum":["DR","CR"],"default":"DR"},"amount":{"type":"number","example":150000},"partner_name":{"type":"string","example":"성북식당"},"summary":{"type":"string","example":"야근 식대 법인카드 결제"},"autoBalance":{"type":"boolean","default":true}}},"EmployeeInput":{"type":"object","required":["emp_name","base_salary"],"properties":{"clientId":{"type":"integer","default":1},"emp_code":{"type":"string","example":"1020"},"emp_name":{"type":"string","example":"김세무"},"dept_name":{"type":"string","example":"기술연구소"},"position":{"type":"string","example":"선임연구원"},"base_salary":{"type":"number","example":4500000},"meal_allowance":{"type":"number","example":200000},"bonus":{"type":"number","example":0}}},"TaxAdjustmentInput":{"type":"object","required":["item_name"],"properties":{"clientId":{"type":"integer","default":1},"gisu":{"type":"integer","default":12},"form_code":{"type":"string","example":"SCIR0101"},"form_name":{"type":"string","example":"소득금액조정합계표"},"category":{"type":"string","example":"익금산입/손금불산입"},"disposition_type":{"type":"string","example":"기타사외유출"},"item_name":{"type":"string","example":"업무무관가지급금 인정이자"},"book_amount":{"type":"number","example":12000000},"tax_limit_amount":{"type":"number","example":10000000},"adj_add_amount":{"type":"number","example":2000000},"adj_deduct_amount":{"type":"number","example":0}}},"StatutoryFormSaveInput":{"type":"object","properties":{"clientId":{"type":"integer","default":1},"gisu":{"type":"integer","default":12},"singoGubun":{"type":"string","enum":["1","2"],"default":"1"},"singoDate":{"type":"string","example":"2026-03-31"},"cells":{"type":"object","additionalProperties":{"oneOf":[{"type":"number"},{"type":"string"},{"type":"object","properties":{"value":{"oneOf":[{"type":"number"},{"type":"string"}]},"remark":{"type":"string"}}}]},"example":{"101":{"value":719607724,"remark":"결산서상 당기순손익"},"102":{"value":1156590,"remark":"익금산입 합계"},"103":{"value":0,"remark":"손금산입 합계"}}}}},"ProblemDetails":{"type":"object","description":"RFC 9457 Problem Details for HTTP APIs","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"timestamp":{"type":"string"}}}},"responses":{"Problem400":{"description":"잘못된 요청 파라미터 또는 필수값 누락 (RFC 9457 application/problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"Problem404":{"description":"리소스를 찾을 수 없음 (RFC 9457 application/problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}