granter API

그랜터 Public Docs API는 자산 연동 현황, 기관 연동 상태, 거래·증빙 데이터, 분류 기준, 잔액 흐름을 외부 시스템과 AI가 함께 이해할 수 있도록 구조화해 제공하는 연동 문서입니다. 발급된 API key와 Basic 인증만으로 권한 범위의 데이터를 안전하게 조회하고, 로그인 기반 기관 연동·재연동을 요청하고, 티켓 데이터 갱신을 요청하고, 티켓의 계정과목·태그·설명·사용 직원과 계좌 거래처를 수정하고, 티켓 간 연결내역을 조회하거나 연결을 생성·해제하고, 수기 카드·계좌와 해당 수기 거래, 수기 세금계산서·현금영수증을 입력하고, 인원 초대, 거래처·전자결재·급여 내역 생성과 세금계산서·현금영수증의 발행, 취소발행, 수정발행 같은 작업까지 자동화할 수 있습니다. 터미널 연동이 필요하면 공식 granter CLI로 같은 API key를 설정해 바로 호출할 수 있습니다.

문서 이해를 위한 빠른 가이드

1) 이 문서가 다루는 범위

- `assets`: 카드, 계좌, 홈택스, 스토어처럼 거래가 들어오는 자산·연동 대상을 조회합니다.

- `organizations`: 은행, 카드, 증권, 홈택스 등 기관의 연동 가능 상태와 현재 연결 상태를 조회합니다.

- `organizations-login-connect`, `organizations-login-reconnect`: 기관 로그인 ID/PW로 신규 연동 또는 재연동을 요청합니다.

- `cards-create`, `bank-accounts-create`: 자동 연동이 아닌 외부 시스템 기준의 수기 카드·계좌를 생성합니다.

- `card-usages-create`, `bank-transactions-create`: 생성된 수기 카드·계좌에 카드 승인/계좌 입출금 거래를 일괄 입력해 티켓을 만듭니다.

- `manual-transactions-create`, `manual-transactions-delete`: 수기관리 전표를 거래처 ID 기준으로 일괄 생성하거나 잘못 생성된 전표를 티켓 ID 기준으로 일괄 삭제합니다.

- `tax-invoices-create`, `cash-receipts-create`: 국세청 발행 없이 외부 시스템 기준의 수기 세금계산서·현금영수증을 입력합니다.

- `tickets`: 카드 승인, 계좌 입출금, 세금계산서, 현금영수증, 결재 등 실제 업무에서 발생한 거래·증빙 이벤트를 조회합니다.

- `tickets-update`: 티켓의 계정과목, 1차/2차 태그, 설명, 사용 직원과 계좌 티켓의 거래처를 단건 또는 묶음으로 수정합니다.

- `tickets-complete-without-reference`, `tickets-uncomplete-without-reference`: 미연결 세금계산서를 연결없이 완료 처리하거나 완료 전 상태로 되돌립니다.

- `ticket-references`: 특정 티켓에 연결된 카드·계좌·증빙·결재 티켓 목록을 조회합니다.

- `ticket-references-create`: 세금계산서·현금영수증·수기관리·결재 같은 증빙/업무 티켓과 카드·계좌 거래 티켓을 연결 생성합니다.

- `ticket-references-create-bulk`: 여러 티켓 연결을 한 요청에서 생성하고 항목별 성공·실패를 확인합니다.

- `ticket-references-delete`: 잘못 연결됐거나 더 이상 유효하지 않은 티켓 연결을 해제합니다. 티켓 원본은 삭제하지 않습니다.

- `tickets-refresh`: 워크스페이스의 거래·증빙 데이터 갱신을 요청합니다. 요청은 비동기로 접수되며 새 데이터 반영까지 시간이 걸릴 수 있습니다.

- `tax-invoices-issue`: 세금계산서를 즉시발행, 예약발행, 반복발행 형태로 생성합니다.

- `tax-invoices-modify-issue`, `tax-invoices-cancel-issue`: 세금계산서 수정발행과 취소발행을 처리합니다.

- `cash-receipts-issue`, `cash-receipts-cancel-issue`: 현금영수증 발행과 취소발행을 처리합니다.

- `people-invite`: 외부 시스템의 구성원 정보를 기준으로 워크스페이스 인원을 초대합니다.

- `tags-create`, `tags-update`, `tag-details-create`, `tag-details-update`, `categories-create`, `categories-update`: 외부 시스템의 분류 기준을 그랜터 태그·계정과목 기준과 맞춥니다. 삭제 API는 아직 공개하지 않습니다.

- `contacts-create`, `contacts-update`: 외부 시스템에서 거래처 기준 데이터를 생성·수정합니다. 거래처 삭제 API는 아직 공개하지 않습니다.

- `workspace-profile`, `user-profiles`: 워크스페이스 이름·아이콘과 구성원 프로필 이미지를 포함한 기본 프로필 정보를 조회합니다.

- `subscription`: 워크스페이스의 현재 요금제, 구독 상태, 활성 자산 수, 예상 결제 금액을 조회합니다.

- `workflows-create`: 외부 시스템에서 전자결재 문서를 생성합니다. 전자결재 수정/삭제 API는 아직 공개하지 않습니다.

- `workflows`: 전자결재 문서, 결재선, 승인 상태처럼 결재 프로세스 자체를 조회합니다.

- `salary-histories`: 직원별 급여 내역, 지급 상태, 공제/수당 상세처럼 급여 도메인 데이터를 조회합니다.

- `salary-histories-create`: 외부 시스템에서 급여 내역을 생성합니다. 급여 수정/삭제 API는 아직 공개하지 않습니다.

- `inventory-products`, `inventories`: 품목 마스터와 현재 재고 수량을 분리해서 조회합니다.

- `balances`: 계좌별 잔액 흐름을 시계열로 조회해 자금 추이와 현금 상태를 파악할 수 있습니다.

- `daily-financial-report`: `balances`, 계좌 거래, 환율, 자산 정보를 조합해 자금일보용 잔액 표를 제공합니다. 대출 계좌는 일반 잔액 합계에서 분리됩니다.

- `workspace-profile`, `user-profiles`, `subscription`, `tags`, `tag-details`, `categories`, `people`, `teams`, `contacts`: 원시 거래를 사람이 이해할 수 있는 회계·운영 언어로 바꾸는 기준 데이터를 조회합니다.

2) 추천 연동 순서

1. 발급된 live key 또는 test key를 준비하고 Basic 인증을 연결합니다.

2. `workspace-profile`, `user-profiles`, `subscription`, `people`, `teams`, `contacts`, `categories`, `tags`, `tag-details`를 먼저 동기화해 회사·담당자·요금제·분류 기준을 맞춥니다.

3. 외부 HR/ERP에서 구성원을 동기화해야 하면 `people-invite`로 먼저 초대하고, 이후 `people`로 워크스페이스 인원 ID를 수집합니다.

4. 외부 분류 체계를 기준으로 맞춰야 하면 `tags-create`, `tags-update`, `tag-details-create`, `tag-details-update`, `categories-create`, `categories-update`를 연결합니다.

5. 외부 CRM/ERP의 거래처 마스터를 기준으로 맞춰야 하면 `contacts-create`, `contacts-update`를 연결합니다. 삭제 동기화는 아직 Public API로 제공하지 않습니다.

6. 외부 시스템에서 결재 문서를 올려야 하면 `workflows-create`를 연결하고, 결재 상태/결재선은 `workflows`로 수집합니다.

7. 외부 급여 시스템에서 산출한 급여대장을 올려야 하면 `salary-histories-create`를 연결하고, 지급 상태/공제 내역은 `salary-histories`로 수집합니다.

8. 급여 분석이나 인건비 자동화가 필요하면 `salary-histories`를 별도 도메인으로 함께 수집합니다.

9. 재고를 운영한다면 `inventory-products`와 `inventories`를 함께 수집해 품목 마스터와 수량 현황을 분리 적재합니다.

10. `organizations`로 지원 기관과 현재 연동 상태를 확인하고, 필요하면 로그인 연동 API로 기관 연결을 먼저 완료합니다.

11. `assets`로 어떤 자산에서 데이터가 들어오는지 파악합니다.

12. 최신 데이터가 필요하면 `tickets-refresh`로 갱신을 요청한 뒤 약 30분 후 `tickets`를 다시 조회합니다.

13. 외부 시스템의 자체 어드민 데이터를 그랜터로 밀어 넣어야 하면 수기 입력 API 묶음(`cards-create`, `bank-accounts-create`, `card-usages-create`, `bank-transactions-create`, `manual-transactions-create`, `manual-transactions-delete`, `tax-invoices-create`, `cash-receipts-create`)을 연결합니다.

14. `tickets`를 수집해 실제 거래·증빙 원천 데이터를 적재합니다.

15. 수집 후 수동 보정이나 외부 자동분류 결과 반영이 필요하면 `tickets-update`로 계정과목, 태그, 설명, 사용 직원과 계좌 티켓의 거래처를 정정합니다.

16. 정산 상태를 함께 적재해야 하면 `ticket-references`로 각 증빙 또는 결제 티켓의 현재 연결내역을 조회합니다.

17. 외부 시스템에서 이미 대금 지급/수납 매칭이 끝난 경우 `ticket-references-create`로 증빙 티켓과 카드·계좌 티켓을 연결합니다. 연결되지 않은 증빙은 거래처별 미수/미지급 후보로 남겨 두고, 실제 입출금·카드 결제가 확인된 시점에 연결하세요.

18. 여러 연결을 한 번에 처리하려면 `ticket-references-create-bulk`를 사용하고 응답의 항목별 결과를 확인합니다.

19. 실제 결제 연결 없이 정산이 끝난 미연결 세금계산서는 `tickets-complete-without-reference`로 완료 처리하고, 잘못 처리한 건은 `tickets-uncomplete-without-reference`로 되돌립니다.

20. 매칭이 잘못됐거나 외부 시스템에서 정산이 취소된 경우 `ticket-references`로 연결 관계 ID(`ticketReferenceId`)를 확인한 뒤 `ticket-references-delete`로 해당 연결을 해제합니다.

21. 세금계산서 또는 현금영수증 발행 자동화가 필요하면 `tax-invoices-issue`, `tax-invoices-modify-issue`, `tax-invoices-cancel-issue`, `cash-receipts-issue`, `cash-receipts-cancel-issue`를 연결합니다.

22. 자금 흐름까지 보려면 `balances`를 별도 주기로 함께 수집합니다.

23. 자금일보 형태의 바로 사용 가능한 표가 필요하면 `daily-financial-report`를 사용합니다.

3) 설계 원칙과 실무 규칙

- 모든 조회는 인증된 권한 범위 안에서만 수행됩니다.

- Public Docs API 앞단의 오용 방지 제한은 클라이언트 IP 기준 분당 120 작업 단위입니다. 일반 요청은 1, `ticket-references-create-bulk`는 연결 항목당 1, 연결없이 완료/되돌리기는 티켓당 2를 사용합니다. 초과 시 `429 Too Many Requests`와 `Retry-After`를 반환합니다.

- `tickets-refresh`는 비동기 갱신 요청입니다. 같은 워크스페이스에서 자동화할 때는 30분 이상 간격으로 호출하세요.

- 기관 로그인 연동/재연동 API는 실제 금융기관 또는 홈택스 인증을 시도합니다. 외부 자동화에서는 사용자 동의, 기관 약관, 인증정보 보관 정책을 먼저 확정하세요.

- `ticket-references`는 특정 기준 티켓에 직접 연결된 상대 티켓 목록을 반환합니다. 여러 단계로 이어진 관계를 추적해야 하면 응답에 포함된 상대 티켓 ID로 다시 조회하세요.

- `ticket-references-create`는 현재 그랜터 내부 통합 API와 같은 `targets` 2개 구조를 사용합니다. 이미 연결된 조합을 다시 보내면 backend에서 중복 연결 오류가 반환될 수 있으므로 외부 시스템에서도 멱등 키와 연결 상태를 관리하세요.

- `ticket-references-delete`는 연결 관계 ID(`ticketReferenceId`) 기준으로 동작합니다. 연결된 티켓 ID가 아니라 `ticket-references` 조회 응답의 `ticketReferenceId`를 사용해야 하며, 해제해도 티켓 원본은 삭제되지 않습니다.

- 정산 연결, 미수/미지급 계산처럼 여러 API가 함께 필요한 개념은 `그랜터 데이터 구조와 활용 관점` 섹션을 먼저 읽고, 각 endpoint 섹션에서는 요청 형식과 제한사항만 확인하세요.

- 데이터 자체를 지우는 API는 현재 수기관리 전표 삭제만 제공합니다. 태그, 계정과목, 거래처, 전자결재, 급여 등 다른 데이터의 삭제는 앱 또는 담당자 안내를 통해 처리하세요. `ticket-references-delete`는 연결 관계만 제거하고 티켓 원본은 삭제하지 않습니다.

- 모든 인증 Public API 응답의 `Granter-API-Revision`, `Granter-API-Changes`, `Link` 헤더에서 현재 계약 리비전과 해당 endpoint의 변경 내역을 확인할 수 있습니다. 전체 변경 로그는 `/api/public-docs/changelog`에서 조회하세요.

- CLI 사용자는 `granter config --api-key YOUR_API_KEY`로 같은 API key를 등록한 뒤 `granter contacts`, `granter categories` 같은 명령으로 기준 데이터를 조회할 수 있습니다.

- 응답은 원본 구조를 최대한 보존하므로, nullable/optional 필드는 자산 종류와 데이터 출처에 따라 비어 있을 수 있습니다.

- 발행 API의 `Idempotency-Key` 헤더는 optional입니다. 미입력 시 서버가 임의 생성한 키로 upstream 요청을 보냅니다. 다만 재시도 시 같은 키를 유지하지 못하므로, 중복 발행 위험을 줄이려면 클라이언트가 직접 키를 넣는 편이 안전합니다.

- 발행 API에서 `Idempotency-Key`는 같은 발행 payload를 네트워크 장애나 timeout 때문에 재시도할 때만 재사용하세요. 새 세금계산서·현금영수증, 금액·거래처·품목이 바뀐 요청, 사용자가 다시 발행 버튼을 누르는 별도 시도에는 반드시 새 키를 생성해야 합니다.

- 같은 `Idempotency-Key`로 다른 발행 payload를 보내면 서버나 외부 발행기관의 멱등 처리에 따라 새 발행이 생성되지 않고 이전 발행 결과(예: 기존 승인번호)가 반환될 수 있습니다.

- 세금계산서·현금영수증 발행은 활성 홈택스 계정과 유효한 인증서를 전제로 합니다.

- `tax-invoices-create`, `cash-receipts-create`는 국세청 발행/전송 없이 그랜터에 수기 증빙 내역만 생성합니다. 실제 발행이 필요하면 발행 API를 사용하세요.

- 발행 request body는 FE와 backend Swagger의 필수값 기준에 맞춰 검증합니다. AI는 이 문서의 `Request Fields`, `requestNotes`, 예시 body를 기준으로 payload를 만들되, 선택 필드는 비어 있으면 생략할 수 있습니다.

- `assets` API의 HOME_TAX_ACCOUNT 응답은 발행용 인증서(`issueCertificate`)를 노출하지 않습니다. 응답에 해당 필드가 없다는 이유만으로 인증서 미등록으로 판단하지 마세요.

- 세금계산서 발행/수정발행/취소발행에서 `supplier`, `contractor`의 필수값은 `registrationNumber`, `companyName`, 대표자명입니다. 대표자명은 `ceoName`으로 전달합니다.

- 세금계산서·현금영수증 발행 계열의 금액 필드는 모두 정수(integer)로 보내세요. 소수점은 허용하지 않는 것으로 가정하는 편이 안전합니다.

- 취소발행은 현재 그랜터에서 발행된 내역만 지원합니다. 외부 시스템이나 다른 채널에서 발행된 증빙은 취소발행 대상이 아닙니다.

- 세금계산서 수정발행은 수정사유에 따라 한 번 또는 두 번의 요청이 필요할 수 있습니다. `기재사항 착오정정`은 일반적으로 취소발행 후 수정발행 순서로 처리합니다.

- 세금계산서 수정발행/취소발행의 허용 사유는 이 문서에 적힌 enum만 사용하세요. backend에 더 많은 사유가 있더라도 현재 Public API에서 바로 허용되지 않을 수 있습니다.

- AI와 사람이 모두 이해하기 쉬운 데이터를 만들려면 `tickets`만 저장하지 말고 `workspace-profile`, `user-profiles`, `subscription`, `workflows`, `salary-histories`, `inventory-products`, `inventories`, `categories`, `tags`, `people`, `teams`, `contacts` 같은 기준 정보도 함께 적재하는 편이 좋습니다.

- 날짜 입력은 `YYYY-MM-DD`, 응답 시각은 주로 ISO-8601 문자열 형식을 사용합니다.

- 금액은 단순 부호보다 `transactionType`, 티켓 타입, endpoint 의미를 함께 보고 해석하는 것이 안전합니다.

API 활용 팁

1) AI에 문서를 전달할 때

- 우측 상단의 `.md 다운로드`로 문서를 내려받아 AI 프롬프트나 지식 파일에 그대로 넣는 방식을 권장합니다.

- Markdown 파일은 endpoint, 요청 필드, 응답 예시가 구조화되어 있어 PDF나 스크린샷보다 AI가 더 안정적으로 읽고 참조할 수 있습니다.

- AI에게 요청할 때는 이 파일 전체를 기준 문서로 주고, 필요한 endpoint와 예시 body를 함께 만들도록 지시하면 가장 안정적입니다.

2) Rate limit 대응

- 여러 endpoint를 한 번에 수집할 때는 동시 요청 수를 낮추고, `429 Too Many Requests`가 오면 잠시 대기한 뒤 재시도하세요.

- 초기 백필이나 대량 적재는 1분 단위 배치로 나누어 호출하는 편이 안전합니다.

3) 조회 기간이 31일을 넘는 경우

- `tickets`는 요청 1회당 최대 366일까지 지원하며, 31일 초과 범위는 서버가 나눠 조회해 합칩니다.

- 그 밖의 기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있습니다. 더 긴 기간은 `startDate`, `endDate`를 31일 이하 구간으로 나눠 순차 조회한 뒤 결과를 합치세요.

- 합칠 때는 응답의 `id`를 기준으로 중복을 제거하고, 적재 테이블에서는 보통 `workspaceId + id` 조합을 키로 둡니다.

[
  { "startDate": "2026-01-01", "endDate": "2026-01-31" },
  { "startDate": "2026-02-01", "endDate": "2026-02-28" },
  { "startDate": "2026-03-01", "endDate": "2026-03-31" }
]

4) 발행 API를 안전하게 호출할 때

- 쓰기 요청의 `Idempotency-Key` 헤더는 optional입니다. 생략해도 호출은 가능하지만, 서버가 요청마다 새 키를 만들 수 있으므로 재시도 안전성이 필요하면 직접 넣는 편이 안전합니다.

- `tax-invoices-issue`, `tax-invoices-modify-issue`, `tax-invoices-cancel-issue`는 `supplier`, `contractor`의 `registrationNumber`, `companyName`, 대표자명을 필요로 합니다. 대표자명은 `ceoName`으로 전달하세요.

- 세금계산서와 현금영수증 발행 계열 금액 필드는 모두 정수로 맞춘 뒤 보내세요. AI가 계산할 때도 소수점 반올림 규칙을 추정하지 말고 호출 전 미리 정수값을 확정하는 편이 안전합니다.

- `tax-invoices-issue`는 공급자/공급받는자 정보와 품목 명세를 그대로 전달하므로, 발행 전 계산값(`supplyValue`, `taxAmount`, `totalAmount`)을 먼저 확정하는 편이 좋습니다.

- `cash-receipts-issue`는 `homeTaxAccountId`가 필요합니다. 먼저 `assets` API에서 `assetType=HOME_TAX_ACCOUNT`로 활성 홈택스 자산을 조회해 사용하세요.

- 세금계산서 수정/취소 사유는 이 문서의 enum만 사용하세요. 현재 Public API에서는 수정발행은 `기재사항 착오정정`, `공급가액 변동`, 취소발행은 `착오에 의한 이중발급`, `계약의 해제`만 허용하는 것으로 보는 편이 안전합니다.

- 세금계산서 `기재사항 착오정정`은 보통 `tax-invoices-cancel-issue`로 원본을 음수 취소발행한 뒤 `tax-invoices-modify-issue`로 정정본을 다시 발행합니다.

granter CLI · Claude Code MCP 연동

1) granter CLI 란

- 터미널에서 `granter` 커맨드로 그랜터 API를 바로 호출할 수 있는 공식 CLI입니다.

- Claude Code 같은 AI 에이전트는 MCP로 연결해 자연어로 그랜터 데이터를 조회·조작할 수 있습니다.

- 패키지: `@granter-biz/cli` · 설치 및 연동 가이드: http://guide.granter.biz/

2) 설치 및 API 키 설정

- 전역 설치: `npm install -g @granter-biz/cli`

- 설치 확인: `granter --version`, `granter --help`

- 개발자센터(`워크스페이스 > 프로필 > API`)에서 발급한 API 키를 등록: `granter config --api-key YOUR_API_KEY`

- 현재 설정 확인: `granter config --show`

3) 기본 조회 커맨드 예시

- 기준 정보: `granter contacts`, `granter categories`, `granter teams`

- 이번 달 카드 사용 내역: `granter tx --type EXPENSE_TICKET --from 2026-04-01 --to 2026-04-17`

- 자산·잔액: `granter assets --type CARD`, `granter bal --from 2026-04-01 --to 2026-04-17`

4) Claude Code MCP 연동

- MCP 서버 등록: `claude mcp add granter -- granter-mcp`

- 이후 `claude` 실행 → Claude Code 안에서 자연어로 "거래처 목록 보여줘", "이번 달 카드 내역 조회해줘", "3월 급여 내역 요약해줘" 처럼 바로 조작할 수 있습니다.

그랜터 데이터 구조와 활용 관점

1) Workspace

Workspace는 하나의 회사 또는 운영 단위를 뜻하는 가장 큰 데이터 경계입니다. 같은 회사 안의 자산, 거래, 태그, 계정과목, 구성원 정보가 모두 이 범위 안에서 조회됩니다. 외부 시스템 입장에서는 "어느 회사의 재무 데이터를 읽고 있는가"를 이해하는 기준이라고 보면 됩니다.

2) Asset (자산)

Asset은 계좌, 카드, 홈택스, 마켓 스토어처럼 거래가 수집되는 연결 대상입니다. 단순 목록이 아니라, 어떤 채널에서 어떤 데이터가 들어오는지 보여주는 출처 정보에 가깝습니다. 자산 유형(`assetType`), 활성 상태(`isActive`), 기관명, 계좌번호/카드번호 같은 식별 정보를 보면 이후 Ticket과 Balance를 어떤 맥락에서 해석해야 하는지 알 수 있습니다.

{
  "id": 101,
  "assetType": "CARD",
  "workspaceId": 123,
  "organizationName": "신한카드",
  "isActive": true
}

3) Ticket (거래 티켓)

Ticket은 실제 업무에서 발생한 거래·증빙 단위 데이터를 의미합니다. 카드 승인 1건, 계좌 입출금 1건, 세금계산서 1건, 현금영수증 1건처럼 "한 번의 재무 이벤트"를 표현한다고 보면 됩니다. 금액(`amount`), 방향(`transactionType`: IN/OUT), 발생일(`transactAt`), 내용(`content`), 분류 상태(`isIncluded`) 등을 가지며, 장부 정리, AI 분류, 분석 리포트, 업무 자동화의 공통 원천 데이터가 됩니다.

{
  "id": 98765,
  "ticketType": "EXPENSE_TICKET",
  "workspaceId": 123,
  "amount": 12000,
  "transactionType": "OUT",
  "transactAt": "2026-02-23T10:15:00.000Z",
  "content": "점심 식대",
  "isIncluded": true
}

4) Ticket Reference (정산 연결)

`ticket-references`는 특정 티켓에 연결된 상대 티켓 목록을 조회하고, `ticket-references-create`는 세금계산서·현금영수증·수기관리·결재 같은 증빙/업무 티켓과 카드 승인·계좌 입출금 같은 실거래 티켓을 연결하며, `ticket-references-delete`는 잘못 맺어진 연결을 해제합니다. 연결은 두 티켓이 같은 경제적 사건에 속한다는 정산 관계를 남기는 작업이며, 연결을 생성하거나 해제해도 원본 증빙을 발행/취소하거나 금융 거래 금액을 생성/수정하지 않습니다.

- 증빙 티켓: `TAX_INVOICE_TICKET`, `CASH_RECEIPT_TICKET`, `MANUAL_TRANSACTION_TICKET`, `WORKFLOW`처럼 매출/매입, 청구, 지출 승인, 채권·채무 발생의 근거가 되는 데이터입니다.

- 실거래 티켓: `EXPENSE_TICKET`, `BANK_TRANSACTION_TICKET`처럼 카드 결제나 계좌 입출금으로 실제 돈이 움직인 데이터입니다.

- 연결내역 응답의 `id`와 `referenceableType`은 연결된 상대 티켓을 가리키고, `ticketReferenceId`는 연결 관계 자체의 ID입니다. 연결 해제 시에는 이 `ticketReferenceId`를 사용합니다.

- 미수금: 매출 세금계산서나 청구성 증빙 중 연결된 입금 거래가 없거나 연결 합계가 증빙 금액보다 작은 금액입니다.

- 미지급금: 매입 세금계산서·현금영수증·결재 증빙 중 연결된 출금/카드 결제가 없거나 연결 합계가 증빙 금액보다 작은 금액입니다.

- 부분 수납/부분 지급은 같은 증빙 티켓에 여러 실거래 티켓을 연결해 표현합니다. 실제 결제·수납이 아직 없으면 임의 실거래 티켓을 만들지 말고 미수/미지급 상태로 유지하세요.

5) Workflow (전자결재 문서)

`workflows`는 기안 문서, 결재 상태, 결재선, 검토자 정보를 담는 전자결재 데이터입니다. `tickets`가 정산·증빙 중심의 재무 이벤트라면, `workflows`는 누가 어떤 안건을 올렸고 현재 몇 차 결재까지 진행됐는지를 보여주는 운영 문서에 가깝습니다. 비용 승인 플로우, 결재 병목 분석, 결재 대기 모니터링, 내부 승인 이력 적재에 적합합니다.

6) Salary History (급여 내역)

`salary-histories`는 급여 지급일, 총급여, 실지급액, 보험료, 세액, 수당·공제 상세를 담는 독립 도메인 데이터입니다. 급여는 티켓 도메인과 별도로 관리되므로, 인건비 분석, 급여 지급 상태 추적, 급여명세 자동화, 노무/세무 협업용 적재가 필요할 때는 `tickets` 대신 `salary-histories`를 직접 읽는 편이 맞습니다. 외부 급여 시스템에서 확정 급여 내역을 그랜터에 올릴 때는 `salary-histories-create`를 사용합니다.

7) Inventory Product / Inventory (품목 / 재고)

`inventory-products`는 품목명, 단가, 통화, 추가 속성 같은 품목 마스터를 조회하는 API이고, `inventories`는 해당 품목의 현재 수량, 메시지 수, 최근 수정 시각 같은 재고 현황을 조회하는 API입니다. 하나는 "무엇을 관리하는가", 다른 하나는 "현재 얼마나 남아 있는가"에 초점이 있으므로 같이 적재하는 편이 자연스럽습니다.

8) Reference Data (분류/담당자 기준 정보)

`categories`, `tags`, `tag-details`, `people`, `teams`, `contacts`는 원시 거래를 사람이 읽을 수 있는 회계·운영 언어로 바꾸는 기준 데이터입니다. 예를 들어 "이 거래가 어떤 비용인지", "어떤 프로젝트/조직/담당자/팀/거래처와 연결되는지"를 설명할 때 사용합니다. 외부 HR/ERP 기준 인원을 그랜터에 추가해야 하면 `people-invite`로 초대한 뒤 `people`에서 ID를 다시 조회합니다. 외부 분류 기준을 그랜터와 맞춰야 하면 태그·상세태그·계정과목의 create/update API를 사용합니다. 티켓 응답만으로도 일부 정보를 볼 수 있지만, AI 분석이나 외부 리포트까지 고려한다면 이 기준 데이터를 별도로 동기화해 두는 편이 훨씬 안정적입니다.

9) Balance (잔액 시계열)

`balances`는 특정 기간의 계좌 잔액 변화를 보여주는 시계열 데이터입니다. `tickets`가 "무슨 거래가 있었는가"를 설명한다면, `balances`는 "그 결과로 계좌에 얼마가 남아 있는가"를 보여줍니다. 자금 추이, 일별 잔액 리포트, 유동성 모니터링, 현금 흐름 대시보드에 적합한 데이터입니다.

10) 관계와 조회 관점

- Workspace 1개 아래에 여러 Asset이 존재합니다.

- Workspace 1개 아래에 여러 Ticket이 존재합니다.

- Workspace 1개 아래에서 세금계산서·현금영수증 발행/취소발행/수정발행 요청이 수행됩니다.

- Workspace 1개 아래에 여러 Workflow(전자결재 문서)가 존재합니다.

- Workspace 1개 아래에 여러 Salary History(급여 내역)가 존재합니다.

- Workspace 1개 아래에 여러 Inventory Product(품목)와 Inventory(재고 엔트리)가 존재합니다.

- Ticket은 특정 Asset에서 수집된 거래나 증빙 이벤트를 표현합니다.

- `workflows` API는 결재 문서, 결재선, 승인 진행 상태를 읽을 때 사용합니다.

- `people-invite` API는 외부 시스템의 구성원 정보를 워크스페이스 초대로 반영할 때 사용합니다.

- `tags-create`, `tags-update`, `tag-details-create`, `tag-details-update`, `categories-create`, `categories-update` API는 외부 분류 기준을 그랜터 기준 데이터에 반영할 때 사용합니다.

- `salary-histories` API는 직원별 급여 내역, 지급 상태, 공제/수당 구성을 읽을 때 사용합니다.

- `salary-histories-create` API는 외부 시스템에서 계산한 급여 내역을 그랜터 급여대장에 추가할 때 사용합니다.

- `inventory-products`는 품목 마스터를, `inventories`는 현재 수량과 재고 상태를 읽을 때 사용합니다.

- `assets` API는 데이터 출처와 연동 상태를 이해할 때, `tickets` API는 실제 거래 원천 데이터를 읽을 때 사용합니다.

- `tickets-update` API는 수집된 티켓의 계정과목, 태그, 설명, 사용 직원과 계좌 티켓의 거래처를 정정하거나 후처리 자동화를 반영할 때 사용합니다.

- `ticket-references` API는 티켓의 현재 정산 연결 상태를 읽을 때 사용합니다.

- `ticket-references-create` API는 증빙 티켓과 실거래 티켓의 정산 관계를 기록할 때 사용합니다.

- `ticket-references-delete` API는 잘못 기록됐거나 취소된 정산 관계를 해제할 때 사용합니다.

- `tax-invoices-issue`, `tax-invoices-modify-issue`, `tax-invoices-cancel-issue`, `cash-receipts-issue`, `cash-receipts-cancel-issue` API는 증빙 발행을 요청하고 승인번호·발행 결과를 응답으로 받습니다.

- `balances` API는 자금 상태와 잔액 흐름을 따로 추적할 때 사용합니다.

- `tags`(1차 태그), `tag-details`(2차 태그), `categories`, `people`, `teams`, `contacts` API는 Ticket을 해석하고 분류하는 기준 데이터로 사용합니다.

11) 통합 시 자주 보는 포인트

- 동일한 회사 데이터를 반복 적재할 때는 `workspaceId + 내부 id` 조합으로 기본 키를 설계하는 것이 일반적입니다.

- 티켓 집계 시에는 `transactionType`, `ticketType`, `isIncluded`를 함께 봐야 사람이 보는 리포트와 AI 분석 결과가 모두 안정적입니다.

- 전자결재 분석이 목적이라면 `workflows.status`, `currentStep`, `steps`를 함께 저장해 결재 대기와 승인 흐름을 추적하는 편이 좋습니다.

- 급여 분석이 목적이라면 `salaryPaymentStatus`, `employmentType`, `recognizedAmount`, `netAmount`를 함께 저장해 지급 현황과 인건비 구조를 분리해서 보는 편이 좋습니다.

- 재고 분석이 목적이라면 `inventory-products`와 `inventories`를 분리 저장하고, `inventoryProductId`로 조인하는 편이 운영 화면과 분석 리포트 양쪽에 유리합니다.

- 자산별 활성 여부와 참조 데이터의 숨김 여부(`isHidden`)는 운영 화면과 외부 리포트에서 의미가 다를 수 있으므로 원본 값을 함께 보관하는 편이 좋습니다.

API 변경 로그

현재 계약 리비전은 2026-08-14.1입니다. 인증 API 응답의 Granter-API-Revision, Granter-API-Changes, Link 헤더에서도 확인할 수 있습니다.

GET JSON 변경 로그

하위호환성 정책: Breaking change 허용

그랜터 Public API는 현재 별도 버전 경로를 운영하지 않으며, 필요한 API 계약 변경에는 breaking change를 허용합니다.

사용자에게 영향을 주는 계약 변경은 이 changelog와 응답의 Granter-API-Revision·Granter-API-Changes 헤더에 기록합니다. 연동 클라이언트는 리비전 변경과 breaking 항목의 migration 안내를 확인해 반영해야 합니다.

2026-08-14.1

2026-08-14

Additivebank-ticket-contact-assignment-added

계좌 티켓의 거래처를 지정하거나 재지정할 수 있도록 bulk-update-individual에 CONTACT와 contactId를 추가합니다.

적용일 2026-08-14 · 대상 tickets-update

Additivesettled-without-reference-added

세금계산서 티켓 응답에 실제 티켓 연결 없이 완료 처리된 상태를 나타내는 settledWithoutReference를 추가합니다.

적용일 2026-08-14 · 대상 tickets

2026-08-05.1

2026-08-05

Additiveticket-date-window-expanded

tickets 조회가 31일 초과 범위를 월 단위로 안전하게 분할·병합하며, 한 요청에서 최대 366일까지 지원합니다.

적용일 2026-08-05 · 대상 tickets

Newticket-references-bulk-create-added

한 요청에서 최대 25개의 티켓 연결을 생성하고 항목별 성공·실패 결과를 반환하는 bulk API를 추가합니다.

적용일 2026-08-05 · 대상 ticket-references-create-bulk

Newtax-invoice-complete-without-reference-added

미연결 세금계산서를 일괄 완료 처리하거나 완료 전 상태로 되돌리는 API를 추가합니다. 연결된 티켓은 안전하게 거부합니다.

적용일 2026-08-05 · 대상 tickets-complete-without-reference, tickets-uncomplete-without-reference

Additivevalidation-error-details-preserved

backend가 제공한 details, errors, fieldErrors 검증 상세를 Public API 오류 응답의 details로 보존합니다.

적용일 2026-08-05 · 대상 모든 Public API

2026-07-29.1

2026-07-29

Additivecontract-change-notices-added

모든 인증 Public API 응답에 현재 계약 리비전, 관련 변경 ID, 변경 로그 링크를 응답 헤더로 제공합니다.

적용일 2026-07-29 · 대상 모든 Public API

Behavioralrate-limit-status-corrected

Public API 앞단 또는 인증 확인 단계의 속도 제한을 401이 아닌 429로 분류하고 Retry-After를 제공합니다.

적용일 2026-07-29 · 대상 모든 Public API

Migration: 401은 API key 오류로만 처리하고, 429는 Retry-After 이후 동일 요청을 재시도하도록 클라이언트 분기를 수정하세요.

Behavioralauth-outage-status-corrected

API key 인증 서버의 일시적 장애를 잘못된 key와 구분하여 401이 아닌 503으로 응답합니다.

적용일 2026-07-29 · 대상 모든 Public API

Migration: 401은 API key를 점검하고, 503은 일시적 장애로 분류하여 지수 백오프로 재시도하세요.

Breakingnickname-canonicalized

응답에 함께 존재하던 nickName과 nickname을 표준 필드 nickname 하나로 통일합니다.

적용일 2026-07-29 · 대상 모든 Public API

Migration: 응답 모델과 필드 접근을 nickname으로 통일하세요.

Additiveticket-connection-summary-added

티켓 응답에 isConnected와 connectionCount 연결 요약을 제공합니다.

적용일 2026-07-29 · 대상 tickets

Newmanual-transactions-create-added

거래처 ID를 포함한 수기관리 전표 다건 생성 API와 안정적인 처리 확인 응답을 추가합니다. upstream이 생성 티켓을 반환하지 않으면 ticketIds와 tickets는 빈 배열입니다.

적용일 2026-07-29 · 대상 manual-transactions-create

Migration: 생성 성공 여부는 ok와 requestedCount로 확인하고, ticketIds가 항상 채워진다고 가정하지 마세요.

Newmanual-transactions-delete-added

수기관리 티켓 ID를 내부 수기거래 ID로 안전하게 변환하고 연결 상태를 확인한 뒤 삭제하는 API를 추가합니다.

적용일 2026-07-29 · 대상 manual-transactions-delete

POST /api/public-docs/tickets

카드, 계좌, 세금계산서, 현금영수증 등 실제 거래·증빙 데이터를 조회합니다.

Request Fields

tickets 기간 조회는 한 요청에서 최대 366일까지 지원합니다. 31일 초과 범위는 서버가 달력월 단위로 나눠 조회하고 티켓 타입과 ID 기준으로 중복 제거해 합칩니다. 조회 기간과 관계없이 결과는 거래일시 내림차순으로 정렬합니다.

`MERCHANT_CARD_TRANSACTION_TICKET`은 포스기 카드 승인·매출전표 단위 조회용입니다. 승인번호, 카드사, 거래금액 같은 원거래 정보를 확인할 때 사용하세요.

`MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET`은 포스기/CREFIA 정산 항목 단위 조회용입니다. `POS-매입금액`, `POS-가맹점수수료`, `POS-포인트수수료`, `POS-기타수수료`처럼 수수료를 포함한 정산 구성 항목을 확인할 때 사용하세요.

ticketTypeenumrequired

조회 대상 티켓 타입. 아래 TicketType 상세 목록을 참고하세요.

▶TicketType 상세(기본 접힘)

EXPENSE_TICKET·카드-카드 승인/사용 내역 티켓

BANK_TRANSACTION_TICKET·계좌-계좌 입출금 거래 티켓

TAX_INVOICE_TICKET·세금계산서-세금계산서 증빙 티켓

CASH_RECEIPT_TICKET·현금영수증-현금영수증 증빙 티켓

MERCHANT_CARD_TRANSACTION_TICKET·포스기 카드거래-카드 승인·매출전표 단위 티켓. 수수료 항목은 정산상세 타입에서 조회합니다.

MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET·포스기정산 상세-포스기/CREFIA 정산 항목 단위 티켓. 매입금액·가맹점수수료·포인트수수료·기타수수료 조회에 사용합니다.

ECOMMERCE_SETTLEMENT_DETAIL_TICKET·이커머스정산 상세-이커머스 정산 상세 티켓

ECOMMERCE_SALES_DETAIL_TICKET·이커머스매출 상세-이커머스 매출 상세 티켓

SOCIAL_INSURANCE_PREMIUM_TICKET·사회보험료-사회보험료 납부 티켓

PG_SETTLEMENT_DETAIL_TICKET·PG정산 상세-PG 정산 상세 티켓

PG_TRANSACTION_TICKET·PG거래-PG 원거래 티켓

MANUAL_TRANSACTION_TICKET·수기관리-수기 입력 거래 티켓

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

contactIdnumberoptional

거래처 ID

contactQueryOption"NONE" | "EXACT_MATCH"optional

거래처 검색 옵션

expenseCategoryIdnumberoptional

계정과목 ID

expenseCategoryQueryOption"NONE" | "EXACT_MATCH"optional

계정과목 검색 옵션

tagDetailIdnumberoptional

2차 태그 ID

tagDetailQueryOption"NONE" | "EXACT_MATCH"optional

2차 태그 검색 옵션

tagIdnumberoptional

1차 태그 ID

assetIdnumberoptional

자산 ID

Response Fields

▶[]Ticketrequiredexpandable

BE `/tickets` 원본 응답 배열의 각 원소

idnumberrequired

티켓 ID

workspaceIdnumberrequired

워크스페이스 ID

contentstringrequired

거래/증빙 내용

amountnumberrequired

거래 금액

transactionType"IN" | "OUT" | "ALL"required

입출금 방향

transactAtISO-8601 stringrequired

거래 일시

modifiedTransactAtISO-8601 stringoptional

수정 거래 일시

descriptionstringrequired

설명

▶expenseCategoryExpenseCategoryoptionalexpandable

계정과목

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

anomalyStatus"NORMAL" | "ABUSE_SUSPECTED" | "ABUSE_CONFIRMED" | "ABUSE_REJECTED"required

이상치 상태

status"NONE" | "CONFIRMED" | "USER_CONFIRMED"required

티켓 상태

tagstringrequired

1차 태그명

tagIdnumber | nullrequired

1차 태그 ID

contactstringrequired

거래처명

contactIdnumber | undefinedrequired

거래처 ID

tagDetailstringrequired

2차 태그명

tagDetailIdnumber | nullrequired

2차 태그 ID

isIncludedbooleanrequired

포함 여부

▶usersUserResponse[]requiredexpandable

연결 유저 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesMessage[]requiredexpandable

메시지 목록

idnumberrequired

메시지 ID

ticketIdnumberrequired

티켓 ID

▶userUserResponserequiredexpandable

작성자

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

userIdnumberrequired

작성자 ID

userNamestringrequired

작성자 이름

contentstringrequired

메시지 내용

typeMessageTyperequired

메시지 타입

createdAtstringrequired

생성 시각

deletedAtstring | nulloptional

삭제 시각

messageCountnumberrequired

메시지 수

▶attachmentsAttachment[]requiredexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

ticketIdnumberrequired

티켓 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

attachmentCountnumberrequired

첨부파일 수

ticketTypeTicketTyperequired

조회 대상 티켓 타입

▶cardUsageCardUsageoptionalexpandable

카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶purchaseUsageCardUsageoptionalexpandable

매입 카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶bankTransactionBankTransactionoptionalexpandable

계좌 거래 상세

bankTransactionIdnumberrequired

은행거래 ID

workspaceIdnumberrequired

워크스페이스 ID

transactionType"IN" | "OUT" | "ALL"required

거래 방향

descriptionstringrequired

설명

afterTransactionBalancenumberrequired

거래 후 잔액

originalAfterTransactionBalancenumberoptional

원본 거래 후 잔액

amountnumberrequired

거래 금액

originalAmountnumberoptional

원본 거래 금액

transactAtstringrequired

거래 일시

▶bankAccountTicketAssetrequiredexpandable

계좌 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

counterpartystringoptional

거래 상대방

descriptionTypestringoptional

설명 분류

contentstringoptional

내용

branchstringoptional

지점

▶taxInvoiceTaxInvoiceoptionalexpandable

세금계산서 상세

idnumberrequired

세금계산서 ID

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶issuerobjectrequiredexpandable

발행자

emailstringrequired

이메일

idnumberrequired

유저 ID

isDeletedbooleanrequired

삭제 여부

namestringrequired

이름

▶trusteeTaxInvoiceUserrequiredexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentType"SUMMARY" | "DETAIL"required

내용 타입

transactionType"SELL" | "BUY" | "TRUSTEE"required

거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestringoptional

전송일자

issueDatestringoptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

purposeType"RECEIPT" | "CHARGE"required

영수/청구 구분

representationItemsstringrequired

대표 품목

notestringrequired

비고

status"REPORTED" | "SENT" | "ISSUED"required

상태

taxInvoiceTypestringrequired

세금계산서 종류

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

modificationReasonstringoptional

수정사유

originalApprovalNumbernumberoptional

원본 승인번호

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

paymentStatus"PAID" | "UNPAID"optional

결제 상태

isConnectedbooleanrequired

다른 티켓과 연결되어 있는지 여부

connectionCountnumberoptional

연결된 티켓 수

settledWithoutReferencebooleanoptional

세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부

createdAtISO-8601 stringrequired

생성 시각

parentIdnumberoptional

부모 티켓 ID

isSplittedbooleanrequired

분할 티켓 여부

purchaseStatus"APPROVED" | "PURCHASED" | "PURCHASE_ONLY"optional

매입 상태

isSoftwareExpenditurebooleanoptional

소프트웨어 지출 여부

▶merchantCardTransactionMerchantCardTransactionoptionalexpandable

가맹점 카드 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypeCardTyperequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

installmentMonthnumberrequired

할부개월

transactionTypestringrequired

거래구분

transactAtstringrequired

거래일시

amountnumberrequired

금액

▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable

가맹점 매입 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypestringrequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

transactAtstringrequired

거래일시

purchaseDatestringrequired

매입일

purchaseAmountnumberrequired

매입 금액

totalFeenumberrequired

총 수수료

merchantServiceFeenumberrequired

가맹점 수수료

pointFeenumberrequired

포인트 수수료

etcFeenumberrequired

기타 수수료

paidAmountnumberrequired

지급 금액

expectedPaymentDatestringrequired

지급 예정일

▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable

포스기/CREFIA 정산 상세

idnumberrequired

정산 상세 ID

settlementIdnumberrequired

정산 ID

assetIdnumberrequired

포스기/CREFIA 자산 ID

namestringrequired

항목명

amountnumberrequired

금액

transactionType"IN" | "OUT"required

입출금 방향

▶cashReceiptCashReceiptoptionalexpandable

현금영수증 상세

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

▶manualTransactionManualTransactionoptionalexpandable

수기거래 상세

idnumberrequired

수기거래 ID

currencyCurrencyCoderequired

통화 코드

manualTransactionType"ETC" | "CASH" | "INVOICE"required

수기거래 타입

▶tradeItemsManualTransactionTradeItem[]requiredexpandable

거래 품목

itemNamestringrequired

품목명

quantitynumberrequired

수량

taxAmountnumberrequired

세액

unitPricenumberrequired

단가

hasPurchaseCanceledUsagesbooleanoptional

매입 취소 사용내역 보유 여부

▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable

이커머스 정산 상세

▶assetobjectrequiredexpandable

이커머스 스토어 자산

idnumberoptional

자산 ID

organizationstringoptional

조직 (COUPANG, NAVER 등)

nicknamestringoptional

별칭

ecommerceSettlementIdnumberrequired

정산 ID

settlementDatestringrequired

정산일

settlementRationumberrequired

정산 비율

namestringrequired

항목명

amountnumberrequired

금액

typestringrequired

정산 상세 타입

transactionType"IN" | "OUT"required

입출금 방향

isRecommendedbooleanoptional

추천 티켓 여부

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

과세 유형

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tickets \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketType": "EXPENSE_TICKET",
  "startDate": "2026-03-01",
  "endDate": "2026-03-07"
}'

POST /api/public-docs/tickets

Ticket Response Example

[
  {
    "id": 49176,
    "ticketType": "EXPENSE_TICKET",
    "workspaceId": 1,
    "description": "",
    "content": "GLOBAL SOFTWARE INC.",
    "amount": 14493,
    "transactionType": "OUT",
    "transactAt": "2026-02-28T17:04:34",
    "status": "CONFIRMED",
    "anomalyStatus": "NORMAL",
    "expenseCategory": {
      "id": 1008,
      "name": "숙박비",
      "subInfo": "판매비와 일반관리비",
      "description": "출장업무 등 숙박에 대한 비용",
      "code": "812",
      "type": "COMMON",
      "isHidden": false,
      "costType": "FIXED",
      "isFavorite": false,
      "taxType": "EXEMPT"
    },
    "users": [
      {
        "id": 73,
        "name": "담당자 A",
        "email": "user-a@example.com",
        "isDeleted": false
      }
    ],
    "owners": [
      {
        "id": 73,
        "name": "소유자 A",
        "email": "owner-a@example.com",
        "isDeleted": false
      }
    ],
    "isIncluded": true,
    "tag": "",
    "tagId": null,
    "contact": "",
    "contactId": null,
    "tagDetail": "",
    "tagDetailId": null,
    "messages": [
      {
        "id": 16099,
        "ticketId": 49176,
        "user": {
          "id": 4,
          "name": "운영자 A",
          "email": "operator@example.com",
          "isDeleted": false
        },
        "userId": 4,
        "userName": "운영자 A",
        "content": "계정과목을 없음에서 숙박비로 변경하였습니다.",
        "type": "COMMON_CHANGE",
        "createdAt": "2026-03-01T21:52:10.826539",
        "deletedAt": null,
        "isDeleted": false
      }
    ],
    "messageCount": 1,
    "attachments": [],
    "attachmentCount": 0,
    "createdAt": "2026-02-28T19:50:38.773108",
    "parentId": null,
    "isSplitted": false,
    "assetId": 53,
    "cardUsage": {
      "workspaceId": 1,
      "card": {
        "id": 53,
        "workspaceId": 1,
        "name": "KB국민 SME기업카드",
        "nickname": "운영 법인카드",
        "number": "558526******0880",
        "organization": "KB",
        "organizationName": "국민카드",
        "businessType": "CD",
        "businessTypeName": "CD",
        "owners": [
          {
            "id": 73,
            "name": "소유자 A",
            "email": "owner-a@example.com",
            "isDeleted": false
          }
        ],
        "isHidden": false,
        "clientType": "CORPORATE",
        "isActive": true,
        "isDormant": false,
        "isPossibleDormant": false,
        "userAutoAssignEnabled": true,
        "isFree": false,
        "hasPassword": false,
        "expirationYear": "2030",
        "expirationMonth": "09",
        "limitAmount": 1000000,
        "usedAmount": 0,
        "remainLimit": 0,
        "previousCardNumber": null
      },
      "organizationName": "국민카드",
      "paymentDate": "2026-02-28T17:04:34",
      "storeName": "GLOBAL SOFTWARE INC.",
      "storeType": "없음",
      "storeAddress": "",
      "storeCorporateNumber": "",
      "amount": 14245,
      "canceledAmount": 0,
      "vat": 0,
      "installmentMonth": 0,
      "paymentType": "FULL",
      "paymentStatus": "NORMAL",
      "approvalNumber": "323461",
      "discountedAmount": 0,
      "originalAmount": "10.00",
      "currency": "USD",
      "isStoreInfoUpdated": true,
      "isPurchased": true
    },
    "purchaseUsage": {
      "workspaceId": 1,
      "card": {
        "id": 53,
        "workspaceId": 1,
        "name": "KB국민 SME기업카드",
        "nickname": "운영 법인카드",
        "number": "558526******0880",
        "organization": "KB",
        "organizationName": "국민카드",
        "businessType": "CD",
        "businessTypeName": "CD",
        "owners": [
          {
            "id": 73,
            "name": "소유자 A",
            "email": "owner-a@example.com",
            "isDeleted": false
          }
        ],
        "isHidden": false,
        "clientType": "CORPORATE",
        "isActive": true,
        "isDormant": false,
        "isPossibleDormant": false,
        "userAutoAssignEnabled": true,
        "isFree": false,
        "hasPassword": false,
        "expirationYear": "2030",
        "expirationMonth": "09",
        "limitAmount": 1000000,
        "usedAmount": 0,
        "remainLimit": 0,
        "previousCardNumber": null
      },
      "organizationName": "국민카드",
      "paymentDate": "2026-02-28T00:00:00",
      "storeName": "GLOBAL SOFTWARE INC.",
      "storeType": "",
      "storeAddress": "",
      "storeCorporateNumber": "",
      "amount": 14493,
      "canceledAmount": 0,
      "vat": 0,
      "installmentMonth": 0,
      "paymentType": "FULL",
      "paymentStatus": "NORMAL",
      "approvalNumber": "GRANTER-0",
      "discountedAmount": 0,
      "originalAmount": "10.000",
      "currency": "USD",
      "purchaseDate": "2026-03-03",
      "exchangeRate": "1449.30",
      "foreignReceiptAmount": "10.00",
      "feeAmount": 187
    },
    "bankTransaction": null,
    "taxInvoice": null,
    "paymentStatus": null,
    "purchaseStatus": "PURCHASED",
    "merchantCardTransaction": null,
    "merchantSettlementDetailTransaction": null,
    "merchantPurchaseTransaction": null,
    "cashReceipt": null,
    "manualTransaction": null,
    "hasPurchaseCanceledUsages": false,
    "ecommerceSettlementDetailTransaction": null,
    "taxType": "EXEMPT"
  }
]

POST /api/public-docs/tickets/bulk-update-individual

티켓의 계정과목, 1차/2차 태그, 설명, 사용 직원과 계좌 티켓의 거래처를 단건 또는 묶음으로 수정합니다.

Request Fields

`ticketType`이 같은 티켓만 한 요청에 묶어 보내세요. 단건 수정도 `items` 배열에 1개만 넣으면 됩니다.

계정과목/태그 ID는 먼저 `categories`, `tags`, `tag-details` API로 조회한 뒤 사용하세요.

사용 직원 ID는 먼저 `people` 또는 `user-profiles` API로 조회하세요.

계좌 티켓의 거래처를 지정하거나 재지정하려면 `ticketType=BANK_TRANSACTION_TICKET`, `updateFields=["CONTACT"]`, `contactId`를 전달하세요. 거래처 ID는 먼저 `contacts` API로 조회하세요.

`updateFields`에는 현재 `EXPENSE_CATEGORY`, `TAG`, `TAG_DETAIL`, `DESCRIPTION`, `USERS`, `CONTACT`를 사용할 수 있습니다. `CONTACT`는 계좌 티켓에만 지원합니다.

`DESCRIPTION`는 기존 설명을 새 문자열로 전체 교체합니다.

`USERS`는 기존 사용 직원 목록을 `userIds` 전체로 교체합니다. 모든 사용 직원 배정을 해제하려면 `userIds`에 `null`을 전달하세요.

ticketTypeenumrequired

수정 대상 티켓 타입

▶허용 값

EXPENSE_TICKET·카드-카드 승인/사용 내역 티켓

BANK_TRANSACTION_TICKET·계좌-계좌 입출금 거래 티켓

TAX_INVOICE_TICKET·세금계산서-세금계산서 증빙 티켓

CASH_RECEIPT_TICKET·현금영수증-현금영수증 증빙 티켓

MANUAL_TRANSACTION_TICKET·수기관리-수기 입력 거래 티켓

items[]arrayrequired

수정할 티켓 목록

items[].ticketIdnumberrequired

수정 대상 티켓 ID

이번 요청에서 적용할 변경 필드 목록

▶허용 값

EXPENSE_CATEGORY·계정과목-`items[].expenseCategoryId`를 함께 전달합니다.

TAG·1차 태그-`items[].tagId`를 함께 전달합니다.

TAG_DETAIL·2차 태그-`items[].tagDetailId`를 함께 전달합니다.

DESCRIPTION·설명-`items[].description`을 함께 전달합니다.

USERS·사용 직원-`items[].userIds`를 함께 전달합니다. 기존 배정 목록을 전체 교체합니다.

CONTACT·계좌 거래처-계좌 티켓에서 `items[].contactId`를 함께 전달합니다.

items[].expenseCategoryIdnumberoptional

`updateFields`에 `EXPENSE_CATEGORY`가 포함되면 필수인 계정과목 ID

items[].tagIdnumberoptional

`updateFields`에 `TAG`가 포함되면 필수인 1차 태그 ID

items[].tagDetailIdnumberoptional

`updateFields`에 `TAG_DETAIL`이 포함되면 필수인 2차 태그 ID

items[].descriptionstringoptional

`updateFields`에 `DESCRIPTION`이 포함되면 필수인 새 설명

items[].userIdsnumber[] | nulloptional

`updateFields`에 `USERS`가 포함되면 필수인 사용 직원 ID 목록. 기존 목록을 전체 교체하며 `null`이면 모두 해제

items[].contactIdnumberoptional

`BANK_TRANSACTION_TICKET`의 `updateFields`에 `CONTACT`가 포함되면 필수인 거래처 ID

Response Fields

okbooleanrequired

수정 요청 처리 성공 여부

ticketTypeTicketTyperequired

이번 요청에 적용된 티켓 타입

requestedCountnumberrequired

요청한 티켓 수정 건수

이번 요청에서 적용한 변경 필드 목록

ticketIdsnumber[]required

수정 요청에 포함된 티켓 ID 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tickets/bulk-update-individual \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketType": "BANK_TRANSACTION_TICKET",
  "items": [
    {
      "ticketId": 18222986,
      "contactId": 252010,
      "updateFields": ["CONTACT"]
    }
  ]
}'

POST /api/public-docs/tickets/bulk-update-individual

Ticket Update Response Example

{
  "ok": true,
  "ticketType": "BANK_TRANSACTION_TICKET",
  "requestedCount": 1,
  "updatedFields": ["CONTACT"],
  "ticketIds": [18222986]
}

POST /api/public-docs/tickets/refresh

워크스페이스에 연결된 카드, 계좌, 홈택스 등 거래·증빙 데이터 갱신을 요청합니다. 요청은 비동기로 접수되며 새 데이터가 즉시 조회되지는 않습니다.

Request Fields

요청 body를 생략하거나 `{}`를 보내면 API key가 연결된 워크스페이스의 지원 자산 전체를 갱신합니다.

특정 자산 종류만 갱신하려면 `assetTypes` 배열을 전달하세요. `requestGroupId`는 서버가 생성하므로 요청에 넣지 않습니다.

응답은 갱신 작업 접수 ACK입니다. 새 데이터 반영까지 약 30분 정도 걸릴 수 있으므로 이후 `tickets`, `balances`, `assets` API를 다시 조회하세요.

중복 수집과 금융기관 중복 로그인을 피하려면 자동화 호출 간격을 30분 이상으로 두세요. 너무 자주 호출하면 백엔드에서 400 또는 429가 반환될 수 있습니다.

assetTypesAssetType[]optional

선택 갱신 대상. 생략/빈 배열이면 지원 자산 전체 갱신

Response Fields

okbooleanrequired

갱신 요청 접수 여부

requestGroupIdstring | nulloptional

백엔드 갱신 작업 추적용 요청 그룹 ID

status"ACCEPTED"required

갱신 요청 접수 상태

estimatedDelayMinutesnumberrequired

새 데이터 반영까지 예상되는 대기 시간(분)

messagestringrequired

갱신 요청 처리 안내 메시지

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tickets/refresh \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "assetTypes": ["CARD", "HOME_TAX_ACCOUNT", "SOCIAL_INSURANCE_ACCOUNT"]
}'

POST /api/public-docs/tickets/refresh

Ticket Refresh Response Example

{
  "ok": true,
  "requestGroupId": "2f5d8c17-88f9-4f2f-8d7a-04d8cce13b5a",
  "status": "ACCEPTED",
  "estimatedDelayMinutes": 30,
  "message": "데이터 갱신 요청이 접수되었습니다. 새 데이터 반영까지 약 30분 정도 걸릴 수 있습니다."
}

GET /api/public-docs/ticket-references

특정 티켓 또는 전자결재 문서에 직접 연결된 티켓 목록을 조회합니다. 세금계산서·현금영수증·결재 증빙이 어떤 카드 승인이나 계좌 입출금으로 정산됐는지 확인할 때 사용합니다.

Request Fields

`referenceableId`, `referenceableType`은 query string으로 전달합니다. GET 요청이므로 JSON body를 보내지 않습니다.

`referenceableId`는 `tickets` 또는 `workflows` API에서 조회한 티켓/문서 ID입니다.

`referenceableType`에는 backend ReferenceableType을 넣습니다. `Total`은 사용할 수 없으며 사회보험료, PG 원거래, 휴가 기록 타입도 지원합니다.

응답은 기준 티켓에 직접 연결된 상대 티켓 목록입니다. 여러 단계의 연결 관계를 따라가야 하면 응답의 `id`, `referenceableType`으로 다시 조회하세요.

연결이 없는 티켓은 빈 배열(`[]`)을 반환합니다.

referenceableIdnumber(query)required

연결내역을 조회할 기준 티켓 또는 전자결재 문서 ID

referenceableTypeReferenceableType(query)required

기준 티켓 타입. `Total`은 사용할 수 없습니다.

▶주요 허용 값

TAX_INVOICE_TICKET·세금계산서-세금계산서 증빙 티켓

CASH_RECEIPT_TICKET·현금영수증-현금영수증 증빙 티켓

MANUAL_TRANSACTION_TICKET·수기관리-수기 입력 거래/증빙 티켓

WORKFLOW·결재-전자결재 문서 티켓

EXPENSE_TICKET·카드-카드 승인/사용 내역 티켓

BANK_TRANSACTION_TICKET·계좌-계좌 입출금 거래 티켓

MERCHANT_CARD_TRANSACTION_TICKET·가맹점 카드거래-포스/가맹점 카드 승인·매출전표 단위 티켓

MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET·포스기 정산상세-포스/CREFIA 정산 항목 단위 티켓. 수수료 연결·조회 시 사용

ECOMMERCE_SETTLEMENT_DETAIL_TICKET·이커머스 정산상세-이커머스 정산 상세 티켓

PG_SETTLEMENT·PG정산-PG 정산 집계 티켓

PG_SETTLEMENT_DETAIL_TICKET·PG정산 상세-PG 정산 상세 티켓

PG_TRANSACTION_TICKET·PG거래-PG 원거래 티켓

SOCIAL_INSURANCE_PREMIUM_TICKET·사회보험료-사회보험료 납부 티켓

LEAVE_RECORD·휴가-휴가 기록

Response Fields

▶[]TicketReferencerequiredexpandable

기준 티켓에 직접 연결된 상대 티켓 목록

ticketReferenceIdnumberrequired

연결 관계 자체의 ID

idnumberrequired

연결된 상대 티켓 ID

contentstringrequired

연결된 상대 티켓의 거래/증빙 내용

amountnumberrequired

연결된 상대 티켓 금액

transactAtISO-8601 stringrequired

연결된 상대 티켓 거래 일시

referenceableTypeTicketTyperequired

연결된 상대 티켓 타입

purposeConnectionPurposerequired

연결 목적

referenceType"DEDUPLICATION" | "PAYMENT_PROOF"required

연결 타입

transactionType"IN" | "OUT" | nulloptional

연결된 상대 티켓의 입출금 방향

▶assetTicketReferenceAssetoptionalexpandable

연결된 상대 티켓의 자산 정보

organizationNamestringrequired

연결된 상대 티켓의 자산 기관명

assetNamestringrequired

연결된 상대 티켓의 자산명

nicknamestringrequired

연결된 상대 티켓의 자산 별칭

assetNumberstringrequired

연결된 상대 티켓의 자산 번호

contactNamestringoptional

연결된 상대 티켓의 거래처명

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/ticket-references?referenceableId=90101&referenceableType=TAX_INVOICE_TICKET \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/ticket-references?referenceableId=90101&referenceableType=TAX_INVOICE_TICKET

Ticket Reference Response Example

[
  {
    "ticketReferenceId": 88001,
    "id": 50102,
    "content": "HR EXCHANGE 2026 참가비 입금",
    "amount": 16500000,
    "transactAt": "2026-05-12T09:30:00",
    "referenceableType": "BANK_TRANSACTION_TICKET",
    "purpose": "TAX_INVOICE_PAYMENT_MANAGEMENT",
    "referenceType": "PAYMENT_PROOF",
    "transactionType": "IN",
    "asset": {
      "organizationName": "하나은행",
      "assetName": "보통예금",
      "nickname": "운영계좌",
      "assetNumber": "123-***-456789"
    },
    "contactName": "주식회사 샘플"
  }
]

POST /api/public-docs/ticket-references

두 티켓을 연결합니다. 세금계산서·현금영수증·수기관리·결재 같은 증빙/업무 티켓과 카드·계좌 거래 티켓을 연결해 증빙이 어떤 실제 결제·수납으로 정산되었는지 기록합니다.

Request Fields

현재 그랜터 내부 통합 API와 같은 `targets` 2개 구조를 사용합니다.

정산 연결의 의미와 미수/미지급 계산 기준은 상단 `그랜터 데이터 구조와 활용 관점 > Ticket Reference`를 먼저 확인하세요.

`targets`에는 서로 다른 두 티켓을 넣어야 하며 `Total` 타입은 사용할 수 없습니다.

`targets[].id`는 `tickets` API에서 조회되는 티켓 ID입니다. 수기 세금계산서/현금영수증 생성 응답의 원천 증빙 ID와 다를 수 있으므로, 생성 직후 연결하려면 `tickets`로 해당 `TAX_INVOICE_TICKET` 또는 `CASH_RECEIPT_TICKET`을 조회해 ID를 확인하세요.

증빙과 결제 거래를 연결할 때는 보통 첫 번째 target에 증빙 티켓(`TAX_INVOICE_TICKET`, `CASH_RECEIPT_TICKET`, `MANUAL_TRANSACTION_TICKET`, `WORKFLOW` 등), 두 번째 target에 결제 티켓(`EXPENSE_TICKET`, `BANK_TRANSACTION_TICKET`)을 넣습니다.

`isUpdateReferredTicket=true`이면 backend가 지원하는 범위 안에서 연결 대상 티켓의 거래처/상태 같은 참조 정보를 함께 갱신할 수 있습니다.

`Idempotency-Key` header는 optional입니다. 같은 연결을 재시도할 수 있으면 클라이언트가 직접 고정 값을 넣으세요.

isUpdateReferredTicketbooleanoptional

연결 대상 티켓의 참조 정보도 함께 갱신할지 여부. 기본 true

targetsTicketReferenceTarget[2]required

연결할 두 티켓

targets[].idnumberrequired

티켓 ID

targets[].typeReferenceableTyperequired

티켓 타입. `Total`은 사용할 수 없습니다.

▶주요 허용 값

TAX_INVOICE_TICKET·세금계산서-세금계산서 증빙 티켓

CASH_RECEIPT_TICKET·현금영수증-현금영수증 증빙 티켓

MANUAL_TRANSACTION_TICKET·수기관리-수기 입력 거래/증빙 티켓

WORKFLOW·결재-전자결재 문서 티켓

EXPENSE_TICKET·카드-카드 승인/사용 내역 티켓

BANK_TRANSACTION_TICKET·계좌-계좌 입출금 거래 티켓

SOCIAL_INSURANCE_PREMIUM_TICKET·사회보험료-사회보험료 납부 티켓

PG_TRANSACTION_TICKET·PG거래-PG 원거래 티켓

LEAVE_RECORD·휴가-휴가 기록

Response Fields

okbooleanrequired

티켓 연결 요청 처리 성공 여부

isUpdateReferredTicketbooleanrequired

연결 대상 티켓의 거래처/상태 등을 함께 갱신하도록 요청했는지 여부

targets{ id: number; type: TicketType }[]required

연결 요청에 포함된 두 티켓

connectedTicketIdsnumber[]required

연결 요청에 포함된 티켓 ID 목록

connectedTicketTypesTicketType[]required

연결 요청에 포함된 티켓 타입 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/ticket-references \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "isUpdateReferredTicket": true,
  "targets": [
    {
      "id": 90101,
      "type": "TAX_INVOICE_TICKET"
    },
    {
      "id": 50102,
      "type": "BANK_TRANSACTION_TICKET"
    }
  ]
}'

POST /api/public-docs/ticket-references

Ticket Reference Create Response Example

{
  "ok": true,
  "isUpdateReferredTicket": true,
  "targets": [
    {
      "id": 90101,
      "type": "TAX_INVOICE_TICKET"
    },
    {
      "id": 50102,
      "type": "BANK_TRANSACTION_TICKET"
    }
  ],
  "connectedTicketIds": [90101, 50102],
  "connectedTicketTypes": ["TAX_INVOICE_TICKET", "BANK_TRANSACTION_TICKET"]
}

POST /api/public-docs/ticket-references/bulk

여러 티켓 연결을 한 요청에서 생성합니다. 기존 단건 연결 API를 안전한 제한 동시성으로 호출하고 각 연결의 성공·실패를 개별 결과로 반환합니다.

Request Fields

`references` 배열로 한 번에 최대 25개의 연결을 생성할 수 있습니다. 더 큰 작업은 25개 이하 묶음으로 나눠 호출하세요.

각 `references[]` 항목은 단건 `ticket-references-create`와 같은 `isUpdateReferredTicket`, `targets` 계약을 사용합니다.

같은 요청 안에 순서만 다른 동일 티켓 쌍을 중복으로 넣을 수 없습니다.

일부 항목이 실패해도 나머지 항목은 계속 처리합니다. HTTP 200 응답의 `ok`, `failedCount`, `results[]`를 반드시 확인하고 실패한 항목만 재시도하세요.

`Idempotency-Key` header를 전달하면 항목별 키를 결정적으로 파생하므로 동일한 요청 body 재시도가 안전합니다. 다른 body에는 새 키를 사용하세요.

referencesTicketReferenceCreateItem[]required

생성할 티켓 연결 목록(1~25개)

references[].isUpdateReferredTicketbooleanoptional

연결 대상 티켓의 참조 정보도 함께 갱신할지 여부. 기본 true

references[].targetsTicketReferenceTarget[2]required

연결할 서로 다른 두 티켓

references[].targets[].idnumberrequired

티켓 ID

references[].targets[].typeReferenceableTyperequired

티켓 타입. `Total`은 사용할 수 없습니다.

Response Fields

okbooleanrequired

모든 티켓 연결 생성 성공 여부

requestedCountnumberrequired

요청한 티켓 연결 수

succeededCountnumberrequired

성공한 티켓 연결 수

failedCountnumberrequired

실패한 티켓 연결 수

▶resultsTicketReferenceBulkCreateResult[]requiredexpandable

요청 순서와 동일한 항목별 처리 결과

indexnumberrequired

요청 references 배열의 0부터 시작하는 항목 위치

okbooleanrequired

해당 티켓 연결 생성 성공 여부

isUpdateReferredTicketbooleanrequired

연결 대상 티켓의 참조 정보도 함께 갱신하도록 요청했는지 여부

targets{ id: number; type: ReferenceableType }[2]required

해당 항목에서 연결을 요청한 두 티켓

statusnumberoptional

실패한 항목의 upstream HTTP 상태

errorstringoptional

실패한 항목의 오류 메시지

codestringoptional

실패한 항목의 오류 코드

detailsunknownoptional

backend가 제공한 구조화 오류 상세

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/ticket-references/bulk \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "references": [
    {
      "isUpdateReferredTicket": true,
      "targets": [
        { "id": 90101, "type": "TAX_INVOICE_TICKET" },
        { "id": 50102, "type": "BANK_TRANSACTION_TICKET" }
      ]
    },
    {
      "isUpdateReferredTicket": true,
      "targets": [
        { "id": 90102, "type": "TAX_INVOICE_TICKET" },
        { "id": 50103, "type": "BANK_TRANSACTION_TICKET" }
      ]
    }
  ]
}'

POST /api/public-docs/ticket-references/bulk

Ticket Reference Bulk Create Response Example

{
  "ok": true,
  "requestedCount": 2,
  "succeededCount": 2,
  "failedCount": 0,
  "results": [
    {
      "index": 0,
      "ok": true,
      "isUpdateReferredTicket": true,
      "targets": [
        { "id": 90101, "type": "TAX_INVOICE_TICKET" },
        { "id": 50102, "type": "BANK_TRANSACTION_TICKET" }
      ]
    },
    {
      "index": 1,
      "ok": true,
      "isUpdateReferredTicket": true,
      "targets": [
        { "id": 90102, "type": "TAX_INVOICE_TICKET" },
        { "id": 50103, "type": "BANK_TRANSACTION_TICKET" }
      ]
    }
  ]
}

DELETE /api/public-docs/ticket-references

티켓 연결을 해제합니다. `ticket-references`로 조회한 연결 관계 ID(`ticketReferenceId`)를 전달하면 해당 정산 연결만 제거하며, 연결돼 있던 티켓 자체는 삭제하지 않습니다.

Request Fields

`ticketReferenceIds`에는 `ticket-references` 조회 응답의 `ticketReferenceId` 값을 넣습니다. 연결된 상대 티켓 ID(`id`)가 아닙니다.

한 번에 1개 이상 100개 이하의 연결을 해제할 수 있습니다. 단건 해제도 ID 1개짜리 배열로 요청하세요.

해제는 연결 관계만 제거합니다. 증빙·거래 티켓 원본은 남아 있으므로, 해제된 증빙은 다시 미수/미지급 후보로 계산됩니다.

이미 해제됐거나 존재하지 않는 `ticketReferenceId`가 포함되면 backend에서 오류가 반환될 수 있습니다. 해제 전 `ticket-references`로 현재 연결 상태를 확인하세요.

`Idempotency-Key` header는 optional입니다. 같은 해제 요청을 재시도할 수 있으면 클라이언트가 직접 고정 값을 넣으세요.

ticketReferenceIdsnumber[]required

해제할 연결 관계 ID 목록(1~100개). `ticket-references` 조회 응답의 `ticketReferenceId` 값

Response Fields

okbooleanrequired

티켓 연결 해제 요청 처리 성공 여부

deletedTicketReferenceIdsnumber[]required

해제된 연결 관계 ID 목록

deletedCountnumberrequired

해제된 연결 관계 수

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X DELETE https://app.granter.biz/api/public-docs/ticket-references \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketReferenceIds": [88001]
}'

DELETE /api/public-docs/ticket-references

Ticket Reference Delete Response Example

{
  "ok": true,
  "deletedTicketReferenceIds": [88001],
  "deletedCount": 1
}

POST /api/public-docs/tickets/complete-without-reference

실제 입금·출금 티켓을 연결하지 않고 정산이 끝난 미연결 세금계산서를 결제완료(PAID) 상태로 일괄 변경합니다.

Request Fields

현재는 앱의 연결없이 완료 기능과 동일하게 `TAX_INVOICE_TICKET`만 지원합니다.

서버가 요청된 티켓을 모두 먼저 확인한 뒤 상태를 변경합니다. 세금계산서가 아니거나 이미 다른 티켓과 연결된 건이 하나라도 있으면 변경 전에 요청 전체를 거부합니다.

이미 PAID인 티켓은 성공 결과의 `unchanged=true`로 반환하며 다시 수정하지 않습니다.

한 번에 최대 25건까지 처리할 수 있습니다. 항목별 처리 실패는 HTTP 200 응답의 `results`와 `failedCount`로 확인하세요.

`Idempotency-Key` header는 optional입니다. 네트워크 오류로 같은 요청을 재시도할 수 있으면 고정 값을 직접 넣으세요.

ticketType"TAX_INVOICE_TICKET"required

현재 지원하는 대상 티켓 타입

ticketIdsnumber[]required

연결없이 완료 처리할 미연결 세금계산서 티켓 ID 목록(1~25개)

Response Fields

okbooleanrequired

모든 상태변경 성공 여부

ticketType"TAX_INVOICE_TICKET"required

처리 대상 티켓 타입

paymentStatus"PAID" | "UNPAID"required

적용한 결제 상태

requestedCountnumberrequired

요청한 세금계산서 티켓 수

succeededCountnumberrequired

성공 또는 기존 상태 유지로 처리된 수

unchangedCountnumberrequired

이미 목표 상태여서 변경하지 않은 수

failedCountnumberrequired

상태변경에 실패한 수

▶resultsTicketPaymentStatusBatchResult[]requiredexpandable

요청 순서와 동일한 티켓별 처리 결과

ticketIdnumberrequired

처리 대상 세금계산서 티켓 ID

okbooleanrequired

해당 티켓의 상태변경 성공 여부

unchangedbooleanrequired

이미 목표 상태여서 변경하지 않았는지 여부

statusnumberoptional

실패한 항목의 upstream HTTP 상태

errorstringoptional

실패한 항목의 오류 메시지

codestringoptional

실패한 항목의 오류 코드

detailsunknownoptional

backend가 제공한 구조화 오류 상세

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tickets/complete-without-reference \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketType": "TAX_INVOICE_TICKET",
  "ticketIds": [2512339, 2519677]
}'

POST /api/public-docs/tickets/complete-without-reference

Complete Without Reference Response Example

{
  "ok": true,
  "ticketType": "TAX_INVOICE_TICKET",
  "paymentStatus": "PAID",
  "requestedCount": 2,
  "succeededCount": 2,
  "unchangedCount": 0,
  "failedCount": 0,
  "results": [
    { "ticketId": 2512339, "ok": true, "unchanged": false },
    { "ticketId": 2519677, "ok": true, "unchanged": false }
  ]
}

POST /api/public-docs/tickets/uncomplete-without-reference

연결없이 완료 처리된 미연결 세금계산서를 미결제(UNPAID) 상태로 일괄 되돌립니다.

Request Fields

현재는 `TAX_INVOICE_TICKET`만 지원하며, 다른 티켓과 연결된 세금계산서는 안전하게 거부합니다.

서버가 요청된 티켓을 모두 먼저 확인한 뒤 상태를 변경합니다.

이미 UNPAID인 티켓은 성공 결과의 `unchanged=true`로 반환하며 다시 수정하지 않습니다.

한 번에 최대 25건까지 처리할 수 있습니다. 항목별 처리 실패는 HTTP 200 응답의 `results`와 `failedCount`로 확인하세요.

`Idempotency-Key` header는 optional입니다. 네트워크 오류로 같은 요청을 재시도할 수 있으면 고정 값을 직접 넣으세요.

ticketType"TAX_INVOICE_TICKET"required

현재 지원하는 대상 티켓 타입

ticketIdsnumber[]required

연결없이 완료 상태를 되돌릴 미연결 세금계산서 티켓 ID 목록(1~25개)

Response Fields

okbooleanrequired

모든 상태변경 성공 여부

ticketType"TAX_INVOICE_TICKET"required

처리 대상 티켓 타입

paymentStatus"PAID" | "UNPAID"required

적용한 결제 상태

requestedCountnumberrequired

요청한 세금계산서 티켓 수

succeededCountnumberrequired

성공 또는 기존 상태 유지로 처리된 수

unchangedCountnumberrequired

이미 목표 상태여서 변경하지 않은 수

failedCountnumberrequired

상태변경에 실패한 수

▶resultsTicketPaymentStatusBatchResult[]requiredexpandable

요청 순서와 동일한 티켓별 처리 결과

ticketIdnumberrequired

처리 대상 세금계산서 티켓 ID

okbooleanrequired

해당 티켓의 상태변경 성공 여부

unchangedbooleanrequired

이미 목표 상태여서 변경하지 않았는지 여부

statusnumberoptional

실패한 항목의 upstream HTTP 상태

errorstringoptional

실패한 항목의 오류 메시지

codestringoptional

실패한 항목의 오류 코드

detailsunknownoptional

backend가 제공한 구조화 오류 상세

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tickets/uncomplete-without-reference \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketType": "TAX_INVOICE_TICKET",
  "ticketIds": [2512339, 2519677]
}'

POST /api/public-docs/tickets/uncomplete-without-reference

Uncomplete Without Reference Response Example

{
  "ok": true,
  "ticketType": "TAX_INVOICE_TICKET",
  "paymentStatus": "UNPAID",
  "requestedCount": 2,
  "succeededCount": 2,
  "unchangedCount": 0,
  "failedCount": 0,
  "results": [
    { "ticketId": 2512339, "ok": true, "unchanged": false },
    { "ticketId": 2519677, "ok": true, "unchanged": false }
  ]
}

GET /api/public-docs/organizations

은행, 카드, 증권, 홈택스 등 기관별 연동 가능 여부와 현재 연동 상태를 조회합니다. 로그인 연동 전에 대상 organization, clientType, 지원 loginType을 확인할 때 사용합니다.

Request Fields

GET query로 `organization`, `clientType`, `businessType`, `loginType`, `isConnected`를 선택적으로 전달해 필터링할 수 있습니다.

Public Docs에서는 `AUTH` 로그인 연동 API만 제공합니다. `supportLoginTypes`는 기관이 지원하는 방식 참고값으로 사용하세요.

로그인 방식으로 연동할 수 없는 기관은 현재 Public Docs 연동 대상에서 제외하고, 앱 안의 기관 연동 화면에서 처리하세요.

organizationstring(query)optional

기관 enum. 예: KUKMIN_BANK, KB, HOME_TAX

clientTypePERSONAL | CORPORATE | ALL(query)optional

개인/기업 구분

businessTypestring(query)optional

BK, CD, ST, NT 등 기관 업무 구분

loginTypeAUTH | CERTIFICATION | TEMP(query)optional

현재 연동된 로그인 방식

isConnectedboolean(query)optional

true면 연동된 기관만, false면 미연동 기관만 조회

Response Fields

▶[]Organizationrequiredexpandable

기관 연동 상태 배열

organizationstringrequired

기관 enum

organizationNamestringrequired

기관명

businessTypeBusinessTyperequired

업무 구분

businessTypeNameBusinessTypeNamerequired

업무 구분명

clientTypeClientTyperequired

개인/기업 구분

isConnectedbooleanoptional

연동 여부

isExpiredbooleanoptional

연동 만료 여부

connectedAtISO-8601 string | nulloptional

연동 시각

homepageUrlstring | nulloptional

기관 홈페이지 URL

loginTypeAUTH | CERTIFICATION | TEMPoptional

현재 연동 방식

supportLoginTypesSupportLoginTypes[]required

지원 연동 방식 목록

▶supportScrapingDurationSupportScrapableDuration[]optionalexpandable

지원 조회 기간

clientTypeClientTyperequired

지원 clientType

durationstring | nulloptional

지원 조회 기간

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/organizations \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/organizations

Organization Connection Status Response Example

[
  {
    "organization": "KUKMIN_BANK",
    "organizationName": "KB국민은행",
    "businessType": "BK",
    "businessTypeName": "은행",
    "clientType": "CORPORATE",
    "isConnected": true,
    "isExpired": false,
    "connectedAt": "2026-04-09T09:30:00.000Z",
    "homepageUrl": "https://obank.kbstar.com",
    "loginType": "AUTH",
    "supportLoginTypes": ["AUTH"],
    "supportScrapingDuration": [
      {
        "clientType": "CORPORATE",
        "duration": "최근 1년"
      }
    ]
  }
]

POST /api/public-docs/organizations/certifications/connect

공동인증서 정보로 기관을 신규 연동합니다. 은행/카드/증권은 organization 목록을 전달하고, 홈택스는 organization에 HOME_TAX와 registrationNumber를 함께 전달합니다.

Request Fields

`organization` 단건 또는 `organizations` 배열 중 하나를 전달하세요. 은행/카드/증권은 여러 기관을 한 번에 요청할 수 있습니다.

`clientType` 기본값은 CORPORATE입니다. organization 상태 조회 응답의 clientType이 ALL이면 실제 대상에 맞게 PERSONAL 또는 CORPORATE를 지정하세요.

홈택스 신규 연동에는 `registrationNumber`가 필요합니다. 홈택스 재연동은 별도 registrationNumber 없이 기존 홈택스 자산 기준으로 처리됩니다.

`certFile`, `keyFile`은 인증서 모듈이나 외부 시스템에서 추출한 인증서 원문/base64 값을 그대로 전달합니다. 기관 정책상 인증서가 해당 기관 사이트에 등록되어 있어야 성공할 수 있습니다.

`requestGroupId`는 생략하는 것을 권장합니다. 서버가 UUID를 생성하며, 직접 전달할 때만 표준 UUID 형식을 사용하세요.

organizationstringoptional

연동할 기관 enum. organizations 대신 단건으로 전달할 때 사용

organizationsstring[]optional

연동할 기관 enum 배열. 예: [KUKMIN_BANK, KB]

clientTypePERSONAL | CORPORATE | ALLoptional

개인/기업 구분. 기본 CORPORATE

certFilestringrequired

인증서 파일 원문 또는 base64 문자열

keyFilestringoptional

개인키 파일 원문 또는 base64 문자열

certFingerPrintstringrequired

인증서 fingerprint

passwordstringrequired

인증서 비밀번호

certificationInformationobjectoptional

인증서 소유자/만료일/발급기관 정보

registrationNumberstringoptional

HOME_TAX 신규 연동 시 필요한 사업자등록번호

requestGroupIdUUIDoptional

선택 추적 ID. 생략 시 서버에서 UUID 생성

Response Fields

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/organizations/certifications/connect \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "organizations": ["KUKMIN_BANK", "KB"],
  "clientType": "CORPORATE",
  "certFile": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "keyFile": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "certFingerPrint": "7A:9B:11:22:33",
  "password": "certificate-password",
  "certificationInformation": {
    "ownerName": "샘플회사",
    "expireDate": "2027-04-08",
    "ca": "금융결제원"
  }
}'

POST /api/public-docs/organizations/certifications/connect

Organization Certificate Connect Response Example

[
  {
    "organization": "KUKMIN_BANK",
    "success": true,
    "message": "기관 연동이 완료되었습니다.",
    "code": "SUCCESS",
    "clientType": "CORPORATE"
  },
  {
    "organization": "KB",
    "success": true,
    "message": "기관 연동이 완료되었습니다.",
    "code": "SUCCESS",
    "clientType": "CORPORATE"
  }
]

POST /api/public-docs/organizations/certifications/reconnect

이미 연동된 기관을 공동인증서 정보로 재연동합니다. 인증서 재발급, 만료, 기관 인증서 등록 변경 후 기존 연결을 갱신할 때 사용합니다.

Request Fields

`organization` 단건 또는 `organizations` 배열 중 하나를 전달하세요.

`requestGroupId` 없이 호출하면 서버가 UUID를 생성합니다. 직접 전달할 때만 표준 UUID 형식을 사용하세요.

응답에 success=false가 포함되면 message를 사용자에게 노출하고, 기관 사이트에서 인증서 등록 상태를 확인하도록 안내하세요.

organizationstringoptional

재연동할 기관 enum. organizations 대신 단건으로 전달할 때 사용

organizationsstring[]optional

재연동할 기관 enum 배열

clientTypePERSONAL | CORPORATE | ALLoptional

개인/기업 구분. 기본 CORPORATE

certFilestringrequired

인증서 파일 원문 또는 base64 문자열

keyFilestringoptional

개인키 파일 원문 또는 base64 문자열

certFingerPrintstringrequired

인증서 fingerprint

passwordstringrequired

인증서 비밀번호

certificationInformationobjectoptional

인증서 소유자/만료일/발급기관 정보

registrationNumberstringoptional

HOME_TAX 재연동에서는 보통 생략

requestGroupIdUUIDoptional

선택 추적 ID. 생략 시 서버에서 UUID 생성

Response Fields

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/organizations/certifications/reconnect \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "organization": "KUKMIN_BANK",
  "clientType": "CORPORATE",
  "certFile": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
  "keyFile": "-----BEGIN PRIVATE KEY-----...-----END PRIVATE KEY-----",
  "certFingerPrint": "7A:9B:11:22:33",
  "password": "certificate-password"
}'

POST /api/public-docs/organizations/certifications/reconnect

Organization Certificate Reconnect Response Example

[
  {
    "organization": "KUKMIN_BANK",
    "success": true,
    "message": "기관 재연동이 완료되었습니다.",
    "code": "SUCCESS",
    "clientType": "CORPORATE"
  }
]

POST /api/public-docs/organizations/login/connect

기관 사이트 로그인 ID/PW로 신규 연동합니다. organization 상태 조회에서 AUTH 로그인을 지원하는 기관에 사용합니다.

Request Fields

`bankingId`/`bankingPassword` 또는 별칭 `loginId`/`loginPassword`를 사용할 수 있습니다.

`clientType` 기본값은 CORPORATE입니다. 개인 계정은 PERSONAL로 지정하세요.

일부 기관은 생년월일, 사업자 정보, OTP 등 추가 인증을 요구할 수 있으며 이 경우 backend message를 그대로 반환합니다.

`requestGroupId`는 생략하는 것을 권장합니다. 서버가 UUID를 생성하며, 직접 전달할 때만 표준 UUID 형식을 사용하세요.

organizationstringrequired

연동할 기관 enum

clientTypePERSONAL | CORPORATE | ALLoptional

개인/기업 구분. 기본 CORPORATE

bankingIdstringoptional

기관 로그인 ID. loginId 별칭 가능

bankingPasswordstringoptional

기관 로그인 비밀번호. loginPassword 별칭 가능

birthDatestringoptional

필요 기관용 생년월일. 예: 19900101

requestGroupIdUUIDoptional

선택 추적 ID. 생략 시 서버에서 UUID 생성

Response Fields

▶[]ConnectResultrequiredexpandable

기관별 연동/재연동 처리 결과

organizationstringrequired

기관 enum

successbooleanrequired

연동 성공 여부

messagestringrequired

처리 메시지

codestringrequired

처리 코드

clientTypeClientTyperequired

개인/기업 구분

reasonstringoptional

실패 사유

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/organizations/login/connect \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "organization": "KUKMIN_BANK",
  "clientType": "CORPORATE",
  "bankingId": "company-login-id",
  "bankingPassword": "company-login-password"
}'

POST /api/public-docs/organizations/login/connect

Organization Login Connect Response Example

[
  {
    "organization": "KUKMIN_BANK",
    "success": true,
    "message": "기관 연동이 완료되었습니다.",
    "code": "SUCCESS",
    "clientType": "CORPORATE"
  }
]

POST /api/public-docs/organizations/login/reconnect

기관 사이트 로그인 ID/PW로 기존 연결을 재연동합니다. 비밀번호 변경, 만료, 인증 오류 후 연결을 갱신할 때 사용합니다.

Request Fields

`bankingId`/`bankingPassword` 또는 별칭 `loginId`/`loginPassword`를 사용할 수 있습니다.

`requestGroupId` 없이 호출하면 서버가 UUID를 생성합니다. 직접 전달할 때만 표준 UUID 형식을 사용하세요.

성공 후 최신 거래 반영까지 기관별 스크래핑 시간이 추가로 걸릴 수 있습니다.

organizationstringrequired

재연동할 기관 enum

clientTypePERSONAL | CORPORATE | ALLoptional

개인/기업 구분. 기본 CORPORATE

bankingIdstringoptional

기관 로그인 ID. loginId 별칭 가능

bankingPasswordstringoptional

기관 로그인 비밀번호. loginPassword 별칭 가능

birthDatestringoptional

필요 기관용 생년월일. 예: 19900101

requestGroupIdUUIDoptional

선택 추적 ID. 생략 시 서버에서 UUID 생성

Response Fields

▶[]ConnectResultrequiredexpandable

기관별 연동/재연동 처리 결과

organizationstringrequired

기관 enum

successbooleanrequired

연동 성공 여부

messagestringrequired

처리 메시지

codestringrequired

처리 코드

clientTypeClientTyperequired

개인/기업 구분

reasonstringoptional

실패 사유

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/organizations/login/reconnect \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "organization": "KUKMIN_BANK",
  "clientType": "CORPORATE",
  "loginId": "company-login-id",
  "loginPassword": "new-company-login-password"
}'

POST /api/public-docs/organizations/login/reconnect

Organization Login Reconnect Response Example

[
  {
    "organization": "KUKMIN_BANK",
    "success": true,
    "message": "기관 재연동이 완료되었습니다.",
    "code": "SUCCESS",
    "clientType": "CORPORATE"
  }
]

POST /api/public-docs/assets

거래가 수집되는 자산과 연동 대상을 조회합니다.

Request Fields

HOME_TAX_ACCOUNT 자산 응답은 홈택스 연결 상태와 사업자 기본 정보를 보여주지만, 발행용 인증서(`issueCertificate`)는 포함하지 않습니다.

assetTypeenumrequired

CARD, BANK_ACCOUNT, HOME_TAX_ACCOUNT, SOCIAL_INSURANCE_ACCOUNT, CUSTOM, MERCHANT_GROUP, SECURITIES_ACCOUNT, ECOMMERCE, PG, MANUAL

Response Fields

▶[]Assetrequiredexpandable

BE `/assets` 원본 응답 배열의 각 원소

idnumberrequired

자산 ID

assetTypeAssetTyperequired

자산 타입

numberstringrequired

자산 번호

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

별칭

organizationOrganizationTyperequired

금융기관 코드

organizationNamestringrequired

금융기관명

businessTypeBusinessTyperequired

업종

businessTypeNameBusinessTypeNamerequired

업종명

isHiddenbooleanrequired

숨김 여부

isActivebooleanrequired

활성 여부

isDormantbooleanrequired

휴면 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isFreebooleanrequired

무료 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientTypeClientTyperequired

고객 유형

userAutoAssignEnabledbooleanrequired

자동 할당 여부

▶cardAssetCardInfooptionalexpandable

카드 자산 정보

expirationYearstringrequired

만료 연도

expirationMonthstringrequired

만료 월

limitAmountnumberrequired

한도 금액

usedAmountnumberrequired

사용 금액

remainLimitnumberrequired

잔여 한도

previousCardNumberstringoptional

이전 카드 번호

▶bankAccountAssetBankAccountInfooptionalexpandable

계좌 자산 정보

accountBalancenumberrequired

계좌 잔액

originalBalancenumberrequired

원본 계좌 잔액

currencyCodestringrequired

통화 코드

startDatestringrequired

조회 시작일

endDatestringrequired

조회 종료일

accountNumberstringrequired

계좌 번호

accountNamestringrequired

계좌명

nicknamestringrequired

별칭

accountTypeAccountTyperequired

계좌 유형

isTransactionVisiblebooleanrequired

거래내역 보유 여부

▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable

홈택스 자산 정보

category"CASH_RECEIPT" | "TAX_INVOICE"required

홈택스 자산 카테고리

registrationNumberstringrequired

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringrequired

회사명

ceoNamestringrequired

대표자명

addressstringrequired

주소

contactNamestringrequired

담당자명

telstringrequired

연락처

businessTypesstringrequired

업태

businessItemsstringrequired

종목

▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable

증권 자산 정보

totalAmountnumberrequired

총액(원화)

depositAmountnumberrequired

예수금(원화)

foreignDepositAmountnumberrequired

외화예수금(원화)

▶foreignDepositsForeignDeposit[]requiredexpandable

외화예수금 보유 목록

idnumberrequired

외화예수금 ID

currencyCurrencyCoderequired

통화 코드

amountnumberrequired

금액

createdAtstringrequired

생성 시각

totalValuationAmountnumberrequired

보유 주식 평가액 합계(원화)

accountNumberstringrequired

계좌번호

▶productsProduct[]requiredexpandable

보유 투자상품

idnumberrequired

상품 ID

productTypestringrequired

상품 유형 코드

productTypeNamestringrequired

상품 유형명

namestringrequired

상품명

codestringoptional

상품 코드

quantitynumberoptional

수량

currencyCurrencyCoderequired

통화 코드

krwPresentAmountnumberoptional

현재 금액(원화)

presentAmountnumberoptional

현재 금액

krwValuationAmountnumberoptional

평가 금액(원화)

valuationAmountnumberoptional

평가 금액

krwValuationPLnumberoptional

평가 손익(원화)

valuationPLnumberoptional

평가 손익

earningsRatenumberoptional

수익률

createdAtstringrequired

생성 시각

▶customAssetAssetCustomInfooptionalexpandable

커스텀 자산 정보

assetType"CASH" | "LIABILITY" | "ASSET"required

커스텀 자산 유형

assetNumberstringrequired

자산 번호

amountnumberrequired

금액

▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable

이커머스 스토어 계정 정보

usernamestringrequired

스토어 사용자명

isOtpVerifiedbooleanrequired

OTP 인증 여부

createdAtstringoptional

생성 시각

modifiedAtstringoptional

수정 시각

hasPasswordbooleanoptional

비밀번호 보유 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/assets \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "assetType": "CARD"
}'

POST /api/public-docs/assets

Asset Response Example

[
  {
    "id": 54,
    "assetType": "CARD",
    "number": "426586******9827",
    "workspaceId": 1,
    "name": "샘플 법인카드",
    "nickname": "운영 카드",
    "organization": "KB",
    "organizationName": "국민카드",
    "businessType": "CD",
    "businessTypeName": "CD",
    "isHidden": false,
    "isActive": true,
    "isDormant": false,
    "isPossibleDormant": false,
    "owners": [
      {
        "id": 67,
        "name": "소유자 A",
        "email": "owner-a@example.com",
        "isDeleted": false
      }
    ],
    "clientType": "CORPORATE",
    "userAutoAssignEnabled": true,
    "isFree": false,
    "hasPassword": false,
    "createdAt": "2024-12-25T13:01:51.863136",
    "modifiedAt": "2026-03-08T12:05:58.877862",
    "card": {
      "expirationYear": "2030",
      "expirationMonth": "09",
      "limitAmount": 1000000,
      "usedAmount": 0,
      "remainLimit": 0,
      "previousCardNumber": null
    },
    "bankAccount": null,
    "homeTaxAccount": null,
    "securitiesAccount": null,
    "customAsset": null,
    "ecommerceAccount": null
  }
]

POST /api/public-docs/balances

계좌별 잔액 흐름과 현금 추이를 조회합니다.

Request Fields

기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.

대출 계좌(`bankAccount.accountType=LOAN`)의 잔액은 일반 예금 잔액과 단순 합산하지 마세요. 대출 실행 시 대출 계좌 잔액과 입금 계좌 잔액이 동시에 증가해 총자산이 과대 집계될 수 있습니다.

자금일보처럼 사람이 보는 현금 현황을 만들 때는 `daily-financial-report` API를 우선 사용하거나, 직접 집계한다면 대출 계좌를 별도 부채/대출 합계로 분리하세요.

startDateYYYY-MM-DDoptional

조회 시작일 (전달 시 endDate와 함께 전달 필수)

endDateYYYY-MM-DDoptional

조회 종료일 (전달 시 startDate와 함께 전달 필수)

Response Fields

▶[]AssetBalancerequiredexpandable

BE `/bank-accounts/daily-balances` 응답을 계좌 기준으로 가공한 배열의 각 원소

▶bankAccountTicketAssetrequiredexpandable

계좌 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

▶balancesBalanceByDate[]requiredexpandable

기간별 잔액 목록

baseDateYYYY-MM-DDrequired

잔액 기준일

accountBalancenumberrequired

계좌 잔액 (원화)

originalBalancenumberrequired

원본 통화 기준 잔액

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/balances \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-03-01",
  "endDate": "2026-03-07"
}'

POST /api/public-docs/balances

Balance Response Example

[
  {
    "bankAccount": {
      "id": 3,
      "assetType": "BANK_ACCOUNT",
      "number": "140014******561",
      "workspaceId": 1,
      "name": "기업자유예금",
      "nickname": "메인 통장",
      "organization": "SHINHAN_BANK",
      "organizationName": "신한은행",
      "businessType": "BK",
      "businessTypeName": "BK",
      "isHidden": false,
      "isActive": true,
      "isDormant": false,
      "isPossibleDormant": false,
      "owners": [
        {
          "id": 9,
          "name": "소유자 B",
          "email": "owner-b@example.com",
          "isDeleted": false
        }
      ],
      "clientType": "CORPORATE",
      "userAutoAssignEnabled": true,
      "isFree": false,
      "hasPassword": false,
      "createdAt": "2024-07-18T11:23:29.369334",
      "modifiedAt": "2026-03-08T12:06:11.683152",
      "card": null,
      "bankAccount": {
        "accountBalance": -89911970,
        "originalBalance": "-89911970",
        "currencyCode": "KRW",
        "startDate": "20240119",
        "endDate": "",
        "accountNumber": "140014******561",
        "accountName": "기업자유예금",
        "nickname": "메인 통장",
        "accountType": "DEPOSIT",
        "isTransactionVisible": true
      },
      "homeTaxAccount": null,
      "securitiesAccount": null,
      "customAsset": null,
      "ecommerceAccount": null
    },
    "balances": [
      {
        "accountBalance": -89911970,
        "baseDate": "2026-03-01",
        "originalBalance": -89911970
      },
      {
        "accountBalance": -89911970,
        "baseDate": "2026-03-02",
        "originalBalance": -89911970
      }
    ]
  }
]

POST /api/public-docs/daily-financial-report

자금일보 화면에서 쓰는 잔액 후처리 로직을 API 응답으로 제공합니다. 날짜별 잔액을 빠짐없이 채우고, 이전/현재 잔액과 입출금 합계, 통화별 합계, 대출 계좌 분리 합계를 함께 반환합니다.

Request Fields

기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.

`startDate`와 `endDate`는 필수입니다. 미래 종료일은 오늘로 보정되어 `effectiveEndDate`에 표시됩니다.

외화 계좌의 `previousBalance`는 이전 기준일 환율, `currentBalance`는 종료 기준일 환율로 원화 환산합니다. `useCurrentExchangeRate=true`이면 둘 다 현재 환율 기준으로 계산합니다.

대출 계좌(`isLoan=true`)는 `total.currentBalance`에서 제외되고 `total.loanBalance` 및 `currencyTotals[].currencyCode=LOAN`에 별도로 표시됩니다. 대출 실행금이 입금 계좌에 들어온 경우에도 대출 잔액을 일반 잔액에 더하지 마세요.

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

useCurrentExchangeRatebooleanoptional

외화 잔액을 현재 환율 기준으로 통일할지 여부. 기본값은 false입니다.

Response Fields

startDateYYYY-MM-DDrequired

요청 시작일

endDateYYYY-MM-DDrequired

요청 종료일

effectiveEndDateYYYY-MM-DDrequired

실제 계산 종료일. 미래 종료일은 오늘로 보정됩니다.

previousDateYYYY-MM-DDrequired

이전 잔액 기준일

▶assetsDailyFinancialReportAssetBalance[]requiredexpandable

자산별 후처리 잔액 목록. 대출 계좌는 isLoan=true로 표시됩니다.

assetIdnumberrequired

자산 ID

assetType"BANK_ACCOUNT" | "SECURITIES_ACCOUNT"required

자산 유형

assetNamestringrequired

자금일보 표시 자산명

assetNumberstringrequired

마스킹된 계좌번호

organizationNamestringrequired

기관명

currencyCodestringrequired

통화 코드. 대출 집계 행은 currencyTotals에서 LOAN으로 분리됩니다.

accountTypestringrequired

계좌 유형. BANK_ACCOUNT의 LOAN은 대출 계좌입니다.

isLoanbooleanrequired

대출 계좌 여부

previousBalancenumberrequired

이전 기준일 표시 잔액. 외화는 이전 기준일 환율로 원화 환산됩니다.

previousOriginalBalancenumberrequired

이전 기준일 원통화 잔액

currentBalancenumberrequired

조회 종료 기준일 표시 잔액. 외화는 종료 기준일 환율로 원화 환산됩니다.

currentOriginalBalancenumberrequired

조회 종료 기준일 원통화 잔액

differencenumberrequired

표시 잔액 기준 이전 대비 증감

originalDifferencenumberrequired

원통화 기준 이전 대비 증감

inAmountnumberrequired

조회 기간 입금 합계

outAmountnumberrequired

조회 기간 출금 합계. 출금은 음수로 표시됩니다.

▶balancesBalanceByDate[]requiredexpandable

조회 기간을 빠짐없이 채운 날짜별 잔액 목록. 원천에 없는 날짜는 0으로 채웁니다.

baseDateYYYY-MM-DDrequired

잔액 기준일

accountBalancenumberrequired

계좌 잔액 (원화)

originalBalancenumberrequired

원본 통화 기준 잔액

▶totalobjectrequiredexpandable

자금일보 합계. 일반 잔액 합계와 대출 잔액을 분리합니다.

previousBalancenumberrequired

대출 제외 이전 잔액 합계

currentBalancenumberrequired

대출 제외 현재 잔액 합계

differencenumberrequired

대출 제외 잔액 증감

inAmountnumberrequired

대출 제외 입금 합계

outAmountnumberrequired

대출 제외 출금 합계

loanBalancenumberrequired

대출 계좌 현재 잔액 합계. 일반 잔액에 더하지 마세요.

netPositionnumberrequired

currentBalance - loanBalance

▶currencyTotalsobject[]requiredexpandable

통화별 합계. 대출 계좌는 LOAN 그룹으로 분리됩니다.

currencyCodestringrequired

통화 코드 또는 LOAN

previousBalancenumberrequired

이전 잔액 합계

currentBalancenumberrequired

현재 잔액 합계

differencenumberrequired

잔액 증감 합계

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/daily-financial-report \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-03-01",
  "endDate": "2026-03-07",
  "useCurrentExchangeRate": false
}'

POST /api/public-docs/daily-financial-report

Daily Financial Report Response Example

{
  "startDate": "2026-03-01",
  "endDate": "2026-03-07",
  "effectiveEndDate": "2026-03-07",
  "previousDate": "2026-02-28",
  "assets": [
    {
      "assetId": 3,
      "assetType": "BANK_ACCOUNT",
      "assetName": "메인 통장",
      "assetNumber": "140014******561",
      "organizationName": "신한은행",
      "currencyCode": "KRW",
      "accountType": "DEPOSIT",
      "isLoan": false,
      "previousBalance": 50000000,
      "previousOriginalBalance": 50000000,
      "currentBalance": 550000000,
      "currentOriginalBalance": 550000000,
      "difference": 500000000,
      "originalDifference": 500000000,
      "inAmount": 500000000,
      "outAmount": 0,
      "balances": [
        {
          "baseDate": "2026-03-01",
          "accountBalance": 550000000,
          "originalBalance": 550000000
        }
      ]
    },
    {
      "assetId": 9,
      "assetType": "BANK_ACCOUNT",
      "assetName": "운전자금 대출",
      "assetNumber": "110123******999",
      "organizationName": "신한은행",
      "currencyCode": "KRW",
      "accountType": "LOAN",
      "isLoan": true,
      "previousBalance": 0,
      "previousOriginalBalance": 0,
      "currentBalance": 500000000,
      "currentOriginalBalance": 500000000,
      "difference": 500000000,
      "originalDifference": 500000000,
      "inAmount": 0,
      "outAmount": 0,
      "balances": [
        {
          "baseDate": "2026-03-01",
          "accountBalance": 500000000,
          "originalBalance": 500000000
        }
      ]
    }
  ],
  "total": {
    "previousBalance": 50000000,
    "currentBalance": 550000000,
    "difference": 500000000,
    "inAmount": 500000000,
    "outAmount": 0,
    "loanBalance": 500000000,
    "netPosition": 50000000
  },
  "currencyTotals": [
    {
      "currencyCode": "KRW",
      "previousBalance": 50000000,
      "currentBalance": 550000000,
      "difference": 500000000
    },
    {
      "currencyCode": "LOAN",
      "previousBalance": 0,
      "currentBalance": 500000000,
      "difference": 500000000
    }
  ]
}

POST /api/public-docs/exchange-rates

기준일의 통화별 환율 정보를 조회합니다.

Request Fields

`baseDate`는 선택값이며, 미입력 시 백엔드 기본 기준일을 사용합니다.

baseDateYYYY-MM-DDoptional

환율 기준일

Response Fields

▶[]ExchangeRaterequiredexpandable

통화별 환율 배열

currencyCodestringrequired

통화 코드

presentNamestringrequired

통화 이름

baseForeignAmountnumberrequired

기준 외화 금액

krwAmountnumberrequired

원화 금액

baseDateYYYY-MM-DDrequired

기준 날짜

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/exchange-rates \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "baseDate": "2026-03-31"
}'

POST /api/public-docs/exchange-rates

Exchange Rate Response Example

[
  {
    "currencyCode": "USD",
    "presentName": "미국 달러",
    "baseForeignAmount": 1,
    "krwAmount": 1472.4,
    "baseDate": "2026-03-31"
  },
  {
    "currencyCode": "JPY",
    "presentName": "일본 엔",
    "baseForeignAmount": 100,
    "krwAmount": 985.31,
    "baseDate": "2026-03-31"
  }
]

GET /api/public-docs/tags

거래를 큰 범주로 묶는 1차 태그 기준 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

Response Fields

▶[]Tagrequiredexpandable

BE `/tags` 원본 응답 배열의 각 원소

idnumberrequired

1차/2차 태그 ID

namestringrequired

1차/2차 태그명

descriptionstringrequired

설명

createdAtstringrequired

생성 시각

modifiedAtstringrequired

수정 시각

type"Tag" | "TagDetail" | "Supplier"required

태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)

workspaceIdnumberoptional

워크스페이스 ID

tagIdnumberoptional

상위 1차 태그 ID (2차 태그에 해당)

codestring | numberoptional

코드

outAmountnumberoptional

지출 집계 금액

inAmountnumberoptional

입금 집계 금액

isHiddennumber | booleanoptional

숨김 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/tags \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/tags

1차 태그 Response Example

[
  {
    "id": 82,
    "name": "프로젝트 A",
    "description": "2025.06.19 ~ 2026.01.05 프로젝트 기준 태그",
    "isHidden": false,
    "createdAt": "2025-09-27T19:48:29.285999",
    "modifiedAt": "2026-02-15T11:59:13.743678"
  }
]

POST /api/public-docs/tags

거래를 큰 범주로 묶는 1차 태그를 생성합니다.

Request Fields

1차 태그 생성만 지원합니다. 태그 삭제 API는 아직 공개하지 않습니다.

요청 재시도 중 중복 생성을 줄이려면 `Idempotency-Key` 헤더를 고정값으로 전달하세요.

`description`은 선택값입니다. 생략하면 빈 설명으로 생성됩니다.

namestringrequired

1차 태그 이름

descriptionstringoptional

1차 태그 설명

Response Fields

idnumberrequired

1차/2차 태그 ID

namestringrequired

1차/2차 태그명

descriptionstringrequired

설명

createdAtstringrequired

생성 시각

modifiedAtstringrequired

수정 시각

type"Tag" | "TagDetail" | "Supplier"required

태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)

workspaceIdnumberoptional

워크스페이스 ID

tagIdnumberoptional

상위 1차 태그 ID (2차 태그에 해당)

codestring | numberoptional

코드

outAmountnumberoptional

지출 집계 금액

inAmountnumberoptional

입금 집계 금액

isHiddennumber | booleanoptional

숨김 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "name": "프로젝트 B"
}'

POST /api/public-docs/tags

1차 태그 Create Response Example

{
  "id": 83,
  "name": "프로젝트 B",
  "description": "",
  "isHidden": false,
  "createdAt": "2026-04-30T10:00:00.000000",
  "modifiedAt": "2026-04-30T10:00:00.000000"
}

PUT /api/public-docs/tags

기존 1차 태그의 이름과 설명을 수정합니다.

Request Fields

1차 태그 수정만 지원합니다. 태그 삭제 API는 아직 공개하지 않습니다.

`id`는 `tags` 조회 또는 `tags-create` 응답에서 받은 1차 태그 ID입니다.

`description`은 선택값입니다. 이름만 바꿀 때는 생략할 수 있습니다.

idnumberrequired

수정할 1차 태그 ID

namestringrequired

수정할 1차 태그 이름

descriptionstringoptional

수정할 1차 태그 설명

Response Fields

okbooleanrequired

수정 요청 처리 성공 여부

tagIdnumberrequired

수정한 1차 태그 ID

updatedFieldsstring[]required

이번 요청에서 수정한 필드 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X PUT https://app.granter.biz/api/public-docs/tags \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "id": 83,
  "name": "프로젝트 B"
}'

PUT /api/public-docs/tags

1차 태그 Update Response Example

{
  "ok": true,
  "tagId": 83,
  "updatedFields": ["name"]
}

GET /api/public-docs/tag-details

1차 태그 아래의 세부 분류 기준 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

Response Fields

▶[]Tagrequiredexpandable

BE `/tag-details` 원본 응답 배열의 각 원소

idnumberrequired

1차/2차 태그 ID

namestringrequired

1차/2차 태그명

descriptionstringrequired

설명

createdAtstringrequired

생성 시각

modifiedAtstringrequired

수정 시각

type"Tag" | "TagDetail" | "Supplier"required

태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)

workspaceIdnumberoptional

워크스페이스 ID

tagIdnumberoptional

상위 1차 태그 ID (2차 태그에 해당)

codestring | numberoptional

코드

outAmountnumberoptional

지출 집계 금액

inAmountnumberoptional

입금 집계 금액

isHiddennumber | booleanoptional

숨김 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/tag-details \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/tag-details

2차 태그 Response Example

[
  {
    "id": 5,
    "workspaceId": 1,
    "name": "마케팅 비용",
    "description": "",
    "tagId": 82,
    "isHidden": false,
    "createdAt": "2024-11-11T19:58:19.541909",
    "modifiedAt": "2026-01-30T14:38:32.668294"
  }
]

POST /api/public-docs/tag-details

2차 태그를 생성합니다. 상위 1차 태그 연결은 선택값입니다.

Request Fields

2차 태그 생성만 지원합니다. 상세 태그 삭제 API는 아직 공개하지 않습니다.

`tagId`를 전달하면 해당 1차 태그 아래에 연결됩니다. 생략하면 상위 1차 태그 없이 생성됩니다.

요청 재시도 중 중복 생성을 줄이려면 `Idempotency-Key` 헤더를 고정값으로 전달하세요.

tagIdnumberoptional

상위 1차 태그 ID

namestringrequired

2차 태그 이름

descriptionstringrequired

2차 태그 설명

Response Fields

idnumberrequired

1차/2차 태그 ID

namestringrequired

1차/2차 태그명

descriptionstringrequired

설명

createdAtstringrequired

생성 시각

modifiedAtstringrequired

수정 시각

type"Tag" | "TagDetail" | "Supplier"required

태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)

workspaceIdnumberoptional

워크스페이스 ID

tagIdnumberoptional

상위 1차 태그 ID (2차 태그에 해당)

codestring | numberoptional

코드

outAmountnumberoptional

지출 집계 금액

inAmountnumberoptional

입금 집계 금액

isHiddennumber | booleanoptional

숨김 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tag-details \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "tagId": 83,
  "name": "마케팅 비용",
  "description": "프로젝트 B의 마케팅 비용 세부 태그"
}'

POST /api/public-docs/tag-details

2차 태그 Create Response Example

{
  "id": 6,
  "workspaceId": 1,
  "name": "마케팅 비용",
  "description": "프로젝트 B의 마케팅 비용 세부 태그",
  "tagId": 83,
  "isHidden": false,
  "createdAt": "2026-04-30T10:00:00.000000",
  "modifiedAt": "2026-04-30T10:00:00.000000"
}

PUT /api/public-docs/tag-details

기존 2차 태그의 이름, 설명, 상위 태그 연결을 수정합니다.

Request Fields

2차 태그 수정만 지원합니다. 상세 태그 삭제 API는 아직 공개하지 않습니다.

`id`는 `tag-details` 조회 또는 `tag-details-create` 응답에서 받은 2차 태그 ID입니다.

`tagId`는 선택값입니다. 상위 1차 태그 연결을 함께 지정할 때만 전달하세요.

idnumberrequired

수정할 2차 태그 ID

tagIdnumberoptional

상위 1차 태그 ID

namestringrequired

수정할 2차 태그 이름

descriptionstringrequired

수정할 2차 태그 설명

Response Fields

okbooleanrequired

수정 요청 처리 성공 여부

tagDetailIdnumberrequired

수정한 2차 태그 ID

updatedFieldsstring[]required

이번 요청에서 수정한 필드 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X PUT https://app.granter.biz/api/public-docs/tag-details \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "id": 6,
  "tagId": 83,
  "name": "마케팅 비용",
  "description": "프로젝트 B 광고·콘텐츠 집행 비용"
}'

PUT /api/public-docs/tag-details

2차 태그 Update Response Example

{
  "ok": true,
  "tagDetailId": 6,
  "updatedFields": ["tagId", "name", "description"]
}

GET /api/public-docs/categories

회계 처리와 분석에 사용하는 계정과목 기준 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

Response Fields

▶[]ExpenseCategoryrequiredexpandable

BE `/expense-categories` 원본 응답 배열의 각 원소

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/categories \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/categories

Category Response Example

[
  {
    "id": 285,
    "name": "가수금",
    "subInfo": "부채",
    "description": "계정과목이 명확치 않은 현금 입금액",
    "code": "257",
    "type": "COMMON",
    "isHidden": false,
    "costType": "VARIABLE",
    "isFavorite": false,
    "taxType": null
  }
]

POST /api/public-docs/categories

회계 처리와 분석에 사용할 커스텀 계정과목을 생성합니다.

Request Fields

계정과목 생성만 지원합니다. 계정과목 삭제 API는 아직 공개하지 않습니다.

요청 재시도 중 중복 생성을 줄이려면 `Idempotency-Key` 헤더를 고정값으로 전달하세요.

`costType`은 `NONE`, `VARIABLE`, `FIXED` 중 하나이며 한국어 `없음`, `변동비`, `고정비`도 허용합니다.

`taxType`은 선택값이며 `DETERMINE_NEEDED`, `TAXABLE`, `EXEMPT`, `ZERO_RATED`, `NONE` 중 하나입니다.

namestringrequired

계정과목 이름

descriptionstringrequired

계정과목 설명

subInfostringrequired

상위 분류. 예: 판매비와관리비, 영업외비용

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

codenumberoptional

계정과목 코드 번호

iconUrlstringoptional

아이콘 이미지 URL

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | "NONE"optional

기본 과세 유형

Response Fields

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "name": "소프트웨어구독료",
  "description": "SaaS 구독 비용",
  "subInfo": "판매비와관리비",
  "costType": "FIXED",
  "code": 842,
  "taxType": "TAXABLE"
}'

POST /api/public-docs/categories

Category Create Response Example

{
  "id": 901,
  "name": "소프트웨어구독료",
  "subInfo": "판매비와관리비",
  "description": "SaaS 구독 비용",
  "code": "842",
  "image": "",
  "type": "CUSTOM",
  "isHidden": false,
  "costType": "FIXED",
  "isFavorite": false,
  "taxType": "TAXABLE"
}

PUT /api/public-docs/categories

기존 커스텀 계정과목의 이름, 설명, 분류, 비용 유형, 과세 유형을 수정합니다.

Request Fields

계정과목 수정만 지원합니다. 계정과목 삭제 API는 아직 공개하지 않습니다.

`id`는 `categories` 조회 또는 `categories-create` 응답에서 받은 계정과목 ID입니다.

수정 요청은 백엔드 계약상 `name`, `description`, `subInfo`, `costType`을 모두 전달해야 합니다.

idnumberrequired

수정할 계정과목 ID

namestringrequired

수정할 계정과목 이름

descriptionstringrequired

수정할 계정과목 설명

subInfostringrequired

수정할 상위 분류

costType"NONE" | "VARIABLE" | "FIXED"required

수정할 비용 유형

codenumberoptional

계정과목 코드 번호

iconUrlstringoptional

아이콘 이미지 URL

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | "NONE"optional

기본 과세 유형

Response Fields

okbooleanrequired

수정 요청 처리 성공 여부

categoryIdnumberrequired

수정한 계정과목 ID

updatedFieldsstring[]required

이번 요청에서 수정한 필드 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X PUT https://app.granter.biz/api/public-docs/categories \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "id": 901,
  "name": "소프트웨어구독료",
  "description": "업무용 SaaS 정기 구독 비용",
  "subInfo": "판매비와관리비",
  "costType": "FIXED",
  "code": 842,
  "taxType": "TAXABLE"
}'

PUT /api/public-docs/categories

Category Update Response Example

{
  "ok": true,
  "categoryId": 901,
  "updatedFields": ["name", "description", "subInfo", "costType", "code", "taxType"]
}

GET /api/public-docs/workspace-profile

API key가 속한 워크스페이스의 이름, 아이콘 이미지, 회사 기본 프로필을 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

`imageUrl`은 워크스페이스 아이콘 이미지 URL입니다.

Response Fields

workspaceIdnumberrequired

워크스페이스 ID

companyNamestringrequired

워크스페이스/회사 이름

imageUrlstring | nulloptional

워크스페이스 아이콘 이미지 URL

companyRegistrationNumberstring | nulloptional

사업자등록번호

membersCountstring | nulloptional

가입 시 선택한 사용 인원 규모

companyTypeCompanyType | nulloptional

회사 유형

businessDescriptionstring | nulloptional

사업 설명

industrialCategoryobject | nulloptional

산업 분류 정보

createdAtstringrequired

워크스페이스 생성 시각

isAccountantbooleanrequired

회계사 워크스페이스 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/workspace-profile \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/workspace-profile

Workspace Profile Response Example

{
  "workspaceId": 1,
  "companyName": "샘플 워크스페이스",
  "imageUrl": "https://cdn.granter.biz/workspaces/1/profile.png",
  "companyRegistrationNumber": "1234567890",
  "membersCount": "10-50",
  "companyType": "STARTUP",
  "businessDescription": "B2B SaaS 운영",
  "industrialCategory": null,
  "createdAt": "2026-01-10T09:00:00",
  "isAccountant": false
}

GET /api/public-docs/user-profiles

워크스페이스 구성원의 이름, 이메일, 팀, 역할, 프로필 이미지 URL을 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

`people` API와 달리 프로필 이미지 URL(`imageUrl`)을 포함한 표시용 프로필 정보를 반환합니다.

Response Fields

▶[]PublicUserProfilerequiredexpandable

워크스페이스 구성원 프로필 배열

idnumberrequired

유저 ID

namestringrequired

이름

nicknamestring | nulloptional

워크스페이스 표시 이름

emailstringrequired

이메일

phoneNumberstring | nulloptional

전화번호

imageUrlstring | nulloptional

사용자 프로필 이미지 URL

workspaceIdnumber | nulloptional

워크스페이스 ID

workspaceNamestring | nulloptional

워크스페이스명

teamIdnumber | nulloptional

팀 ID

teamNamestring | nulloptional

팀명

▶roleWorkspaceRole | nulloptionalexpandable

워크스페이스 역할

idnumberrequired

역할 ID

namestringrequired

역할명

isOwnerbooleanrequired

오너 여부

isDefaultbooleanrequired

기본 역할 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/user-profiles \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/user-profiles

User Profiles Response Example

[
  {
    "id": 4,
    "name": "구성원 A",
    "nickname": "담당자 A",
    "email": "member-a@example.com",
    "phoneNumber": "01012345678",
    "imageUrl": "https://cdn.granter.biz/users/4/profile.png",
    "workspaceId": 1,
    "workspaceName": "샘플 워크스페이스",
    "teamId": 133,
    "teamName": "마케팅팀",
    "role": {
      "id": 1,
      "name": "소유자",
      "isOwner": true,
      "isDefault": false
    }
  }
]

GET /api/public-docs/subscription

API key가 속한 워크스페이스의 현재 요금제, 구독 상태, 활성 자산 수, 예상 결제 금액을 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

결제 카드 번호, 카드사, 결제수단 식별자 같은 민감한 결제수단 정보는 반환하지 않습니다.

`expectedPaymentAmount`는 현재 요금제와 할인, 리워드, 부가 요금 정책에 따라 backend가 계산한 예상 결제 금액입니다.

Response Fields

idnumberrequired

구독 ID

workspaceIdnumberrequired

워크스페이스 ID

statusACTIVE | INACTIVE | PENDING_INACTIVE | BILLING_FAILED | stringrequired

구독 상태

isFreePlanbooleanrequired

무료 플랜 여부

activeAssetCountnumberrequired

요금 산정 대상 활성 자산 수

rewardBalancenumberrequired

보유 리워드 잔액

expectedChargeAmountnumberrequired

예상 청구 금액

expectedPaymentAmountnumberrequired

예상 결제 금액

nextPaymentDateYYYY-MM-DD | ISO-8601 string | nulloptional

다음 결제 예정일

endedAtISO-8601 string | nulloptional

구독 종료 시각

freePlanEndedAtISO-8601 string | nulloptional

무료 플랜 종료 시각

▶subscriptionPlanSubscriptionPlan | nulloptionalexpandable

현재 요금제 정보

namestringrequired

요금제 이름

descriptionstringrequired

요금제 설명

sectionDescriptionstringrequired

요금제 섹션 설명

▶discountSubscriptionDiscount | nulloptionalexpandable

적용 중인 할인 정보

discountPercentagenumberrequired

할인율

discountEndDateYYYY-MM-DD | ISO-8601 stringrequired

할인 종료일

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/subscription \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/subscription

Subscription Response Example

{
  "id": 42,
  "workspaceId": 1,
  "status": "ACTIVE",
  "isFreePlan": false,
  "activeAssetCount": 12,
  "rewardBalance": 0,
  "expectedChargeAmount": 99000,
  "expectedPaymentAmount": 89100,
  "nextPaymentDate": "2026-06-01",
  "endedAt": null,
  "freePlanEndedAt": "2026-01-31T23:59:59",
  "subscriptionPlan": {
    "name": "그랜터 원 스탠다드",
    "description": "복수 자산 연동과 자동 회계 처리를 지원하는 기본 요금제",
    "sectionDescription": "연동 자산 수 기준 월 과금"
  },
  "discount": {
    "discountPercentage": 10,
    "discountEndDate": "2026-12-31"
  }
}

GET /api/public-docs/people

담당자, 결재자, 분류 주체로 활용되는 워크스페이스 구성원 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

Response Fields

▶[]Userrequiredexpandable

BE `/workspaces` 응답의 `users` 배열 원본

idnumberrequired

유저 ID

namestringrequired

이름

emailstringrequired

이메일

workspaceIdnumberoptional

워크스페이스 ID

workspaceNamestringoptional

워크스페이스명

teamIdnumberoptional

팀 ID

teamNamestringoptional

팀명

phoneNumberstringoptional

전화번호

▶roleWorkspaceRolerequiredexpandable

워크스페이스 역할

idnumberrequired

역할 ID

namestringrequired

역할명

isOwnerbooleanrequired

오너 여부

isDefaultbooleanrequired

기본 역할 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/people \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/people

People Response Example

[
  {
    "id": 4,
    "name": "구성원 A",
    "email": "member-a@example.com",
    "workspaceId": 1,
    "workspaceName": "샘플 워크스페이스",
    "teamId": 133,
    "teamName": "마케팅팀",
    "nickname": "담당자 A",
    "phoneNumber": "01012345678",
    "role": {
      "id": 1,
      "name": "소유자",
      "isOwner": true,
      "isDefault": false
    },
    "cards": [],
    "notificationConfig": {
      "userId": 4,
      "slack": false,
      "appPush": false,
      "email": false,
      "kakao": false
    }
  }
]

POST /api/public-docs/people

외부 시스템의 구성원 정보를 기준으로 워크스페이스 인원을 초대합니다.

Request Fields

인원 초대만 지원합니다. 인원 삭제나 역할 부여 API는 아직 공개하지 않습니다.

요청 재시도 중 중복 초대 위험을 줄이려면 `Idempotency-Key` 헤더를 고정값으로 전달하세요.

`users` 배열에는 최소 1명 이상을 전달해야 합니다.

초대 처리 결과는 사용자별 `isSuccess`, `message`, `email`, `name` 배열로 반환됩니다.

usersInviteUserRequest[]required

초대 대상 목록

users[].emailstringrequired

초대 대상 이메일

users[].namestringrequired

초대 대상 이름

users[].imageUrlstringoptional

프로필 이미지 URL

users[].phoneNumberstringoptional

전화번호

users[].slackTokenstringoptional

Slack 초대 토큰. 일반 이메일 초대에서는 생략합니다.

Response Fields

▶[]InviteUserResponserequiredexpandable

BE `/workspaces/bulk-invitation` 원본 응답 배열의 각 원소

isSuccessbooleanrequired

초대 성공 여부

messagestringrequired

초대 처리 메시지

emailstringrequired

초대 대상 이메일

namestringrequired

초대 대상 이름

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/people \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "users": [
    {
      "email": "member-a@example.com",
      "name": "구성원 A",
      "phoneNumber": "01012345678"
    },
    {
      "email": "member-b@example.com",
      "name": "구성원 B"
    }
  ]
}'

POST /api/public-docs/people

People Invite Response Example

[
  {
    "isSuccess": true,
    "message": "초대가 완료되었습니다.",
    "email": "member-a@example.com",
    "name": "구성원 A"
  },
  {
    "isSuccess": true,
    "message": "초대가 완료되었습니다.",
    "email": "member-b@example.com",
    "name": "구성원 B"
  }
]

GET /api/public-docs/teams

구성원을 조직 단위로 묶어 관리하는 팀 기준 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

Response Fields

▶[]Teamrequiredexpandable

BE `/teams` 원본 응답 배열의 각 원소

idnumberrequired

팀 ID

namestringrequired

팀명

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/teams \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/teams

Team Response Example

[
  {
    "id": 6,
    "name": "인사팀"
  }
]

GET /api/public-docs/contacts

거래처, 고객사, 공급사처럼 상대방 기준으로 관리하는 거래처 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

현재 응답은 최신 거래처 목록 기준으로 최대 100건을 조회합니다.

Response Fields

▶[]Contactrequiredexpandable

BE `/contacts` 원본 응답 배열의 각 원소

idnumberrequired

거래처 ID

workspaceIdnumberrequired

워크스페이스 ID

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringrequired

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstring | nulloptional

이메일

email2string | nulloptional

보조 이메일

phonestring | nulloptional

휴대전화

telstring | nulloptional

전화번호

lastIssuedAtstringrequired

최근 발행 시각

region"DOMESTIC" | "FOREIGN"optional

거래처 지역 구분

isHiddenbooleanoptional

숨김 여부

▶managersContactManager[]optionalexpandable

거래처 담당자 목록

idnumberrequired

거래처 담당자 ID

contactIdnumberrequired

거래처 ID

namestringrequired

담당자 이름

phoneNumberstring | nulloptional

휴대전화

telNumberstring | nulloptional

전화번호

faxNumberstring | nulloptional

팩스번호

emailstring | nulloptional

이메일

memostringrequired

메모

nationstringoptional

국가

accountNumberstring | nulloptional

계좌번호

bankNamestring | nulloptional

은행명

bankAccountOwnerNamestring | nulloptional

예금주명

memostringoptional

메모

isFavoritebooleanoptional

즐겨찾기 여부

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/contacts \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/contacts

Contact Response Example

[
  {
    "id": 928,
    "workspaceId": 1,
    "registrationNumber": "1111111111",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 A",
    "businessTypes": "",
    "businessItems": "",
    "businessPlace": "",
    "email": null,
    "email2": null,
    "phone": null,
    "tel": null,
    "bankName": null,
    "bankAccountOwnerName": null,
    "accountNumber": null,
    "lastIssuedAt": "2026-02-19T16:32:29.514778",
    "managers": [],
    "region": "DOMESTIC",
    "nation": "",
    "isHidden": false,
    "memo": "",
    "isFavorite": false
  }
]

POST /api/public-docs/contacts

외부 CRM, ERP, 영업관리 시스템에서 관리하는 거래처를 그랜터 거래처 마스터에 생성합니다.

Request Fields

쓰기 요청입니다. 재시도 안전성이 필요하면 `Idempotency-Key` 헤더를 고정 값으로 전달하세요.

거래처 생성 권한이 없는 API key 또는 플랜에서는 403 응답이 반환될 수 있습니다.

백엔드는 `registrationNumber`를 필수·고유 값으로 처리합니다. 빈 문자열은 기존 미등록 거래처와 중복될 수 있으므로 실제 식별 값을 전달하세요.

거래처 삭제 API는 아직 Public API로 제공하지 않습니다.

companyNamestringrequired

거래처 상호명/회사명

registrationNumberstringrequired

고유 사업자/거래처 식별번호 (`-` 없이 10자리 권장)

ceoNamestringoptional

대표자명

businessTypesstringoptional

업태

businessItemsstringoptional

종목

businessPlacestringoptional

사업장 주소

emailstringoptional

대표 이메일

email2stringoptional

보조 이메일

phonestringoptional

휴대전화

telstringoptional

유선 전화번호

region"DOMESTIC" | "FOREIGN"optional

거래처 지역 구분. 기본값은 DOMESTIC

memostringoptional

메모/비고

accountNumberstringoptional

입금 계좌번호

bankNamestringoptional

입금 은행명

bankAccountOwnerNamestringoptional

예금주명

Response Fields

idnumberrequired

거래처 ID

workspaceIdnumberrequired

워크스페이스 ID

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringrequired

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstring | nulloptional

이메일

email2string | nulloptional

보조 이메일

phonestring | nulloptional

휴대전화

telstring | nulloptional

전화번호

lastIssuedAtstringrequired

최근 발행 시각

region"DOMESTIC" | "FOREIGN"optional

거래처 지역 구분

isHiddenbooleanoptional

숨김 여부

▶managersContactManager[]optionalexpandable

거래처 담당자 목록

idnumberrequired

거래처 담당자 ID

contactIdnumberrequired

거래처 ID

namestringrequired

담당자 이름

phoneNumberstring | nulloptional

휴대전화

telNumberstring | nulloptional

전화번호

faxNumberstring | nulloptional

팩스번호

emailstring | nulloptional

이메일

memostringrequired

메모

nationstringoptional

국가

accountNumberstring | nulloptional

계좌번호

bankNamestring | nulloptional

은행명

bankAccountOwnerNamestring | nulloptional

예금주명

memostringoptional

메모

isFavoritebooleanoptional

즐겨찾기 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "companyName": "샘플 거래처",
  "registrationNumber": "1111111111",
  "ceoName": "대표자 A",
  "businessTypes": "서비스업",
  "businessItems": "소프트웨어 개발",
  "businessPlace": "서울특별시 강남구 테헤란로 1",
  "email": "finance@example.com",
  "phone": "01012345678",
  "region": "DOMESTIC",
  "memo": "외부 ERP에서 동기화"
}'

POST /api/public-docs/contacts

Contact Create Response Example

{
  "id": 928,
  "workspaceId": 1,
  "registrationNumber": "1111111111",
  "companyName": "샘플 거래처",
  "ceoName": "대표자 A",
  "businessTypes": "서비스업",
  "businessItems": "소프트웨어 개발",
  "businessPlace": "서울특별시 강남구 테헤란로 1",
  "email": "finance@example.com",
  "email2": null,
  "phone": "01012345678",
  "tel": null,
  "bankName": null,
  "bankAccountOwnerName": null,
  "accountNumber": null,
  "lastIssuedAt": "2026-02-19T16:32:29.514778",
  "managers": [],
  "region": "DOMESTIC",
  "nation": "",
  "isHidden": false,
  "memo": "외부 ERP에서 동기화",
  "isFavorite": false
}

PUT /api/public-docs/contacts

기존 거래처의 기본 정보, 연락처, 계좌 정보, 메모를 부분 수정합니다.

Request Fields

쓰기 요청입니다. `contactId`와 수정할 필드를 1개 이상 전달해야 합니다.

전달하지 않은 필드는 변경하지 않습니다.

거래처 수정 권한이 없는 API key 또는 플랜에서는 403 응답이 반환될 수 있습니다.

거래처 삭제 API는 아직 Public API로 제공하지 않습니다.

contactIdnumberrequired

수정 대상 거래처 ID

companyNamestringoptional

거래처 상호명/회사명

registrationNumberstringoptional

사업자등록번호 (`-` 없이 10자리 권장)

ceoNamestringoptional

대표자명

businessTypesstringoptional

업태

businessItemsstringoptional

종목

businessPlacestringoptional

사업장 주소

emailstringoptional

대표 이메일

email2stringoptional

보조 이메일

phonestringoptional

휴대전화

telstringoptional

유선 전화번호

memostringoptional

메모/비고

accountNumberstringoptional

입금 계좌번호

bankNamestringoptional

입금 은행명

bankAccountOwnerNamestringoptional

예금주명

Response Fields

okbooleanrequired

수정 요청 처리 성공 여부

contactIdnumberrequired

수정한 거래처 ID

updatedFieldsstring[]required

이번 요청에서 수정한 거래처 필드 목록

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X PUT https://app.granter.biz/api/public-docs/contacts \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "contactId": 928,
  "email": "new-finance@example.com",
  "memo": "담당 이메일 변경"
}'

PUT /api/public-docs/contacts

Contact Update Response Example

{
  "ok": true,
  "contactId": 928,
  "updatedFields": ["email", "memo"]
}

GET /api/public-docs/workflows

기안 문서, 결재 상태, 결재선 정보를 포함한 전자결재 데이터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

직접 호출 시 `status`, `draftedByMe`, `limit`, `offset` query string을 사용할 수 있습니다.

테스트 패널은 기본 목록 조회를 수행합니다.

status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"optional

결재 상태 필터

draftedByMebooleanoptional

내가 올린 결재만 조회할지 여부

limitnumberoptional

조회 건수 제한. 지정하지 않으면 최대 100건까지 조회합니다.

offsetnumberoptional

페이지 오프셋

Response Fields

▶[]Workflowrequiredexpandable

BE `/workflows` 원본 응답 배열의 각 원소

idnumberrequired

전자결재 ID

workspaceIdnumberrequired

워크스페이스 ID

titlestringrequired

결재안 제목

contentstringrequired

결재 내용

amountnumberrequired

결재 금액

originalAmountnumberrequired

원본 결재 금액

expectedPaymentDateYYYY-MM-DDrequired

이체 요청일

status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required

결재 상태

currencystringrequired

통화 코드

createdAtISO-8601 stringrequired

결재 요청 시각

modifiedAtISO-8601 stringrequired

최종 수정 시각

currentStepnumberrequired

현재 결재 차수

tagstring | nulloptional

연결된 태그명

tagIdnumber | nulloptional

연결된 태그 ID

▶userUserrequiredexpandable

기안자 정보

idnumberrequired

기안자 ID

namestringrequired

기안자 이름

emailstringrequired

기안자 이메일

isDeletedbooleanrequired

삭제 여부

▶refundAccountRefundAccountoptionalexpandable

환급 계좌 정보

accountHolderstringrequired

예금주명

accountNumberstringrequired

계좌번호

organizationNamestringrequired

은행명

▶stepsWorkflowStep[]requiredexpandable

결재 단계 목록

idnumberrequired

결재 단계 ID

stepnumberrequired

결재 차수

status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required

결재 단계 상태

createdAtISO-8601 stringrequired

생성 시각

modifiedAtISO-8601 stringrequired

수정 시각

▶approverApproverrequiredexpandable

결재자 정보

idnumberrequired

결재자 ID

namestringrequired

결재자 이름

emailstringrequired

결재자 이메일

isDeletedbooleanrequired

삭제 여부

▶reviewersReviewer[]requiredexpandable

검토자 목록

idnumberrequired

검토자 연결 ID

▶reviewerUserResponserequiredexpandable

검토자 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesWorkflowMessage[]optionalexpandable

결재 메시지 목록

idnumberrequired

메시지 ID

contentstringrequired

메시지 내용

typestringrequired

메시지 타입

createdAtISO-8601 stringrequired

생성 시각

deletedAtISO-8601 string | nulloptional

삭제 시각

▶userUserResponserequiredexpandable

작성자 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶attachmentsWorkflowAttachment[]optionalexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/workflows \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/workflows

Workflow Response Example

[
  {
    "id": 333,
    "workspaceId": 1,
    "user": {
      "id": 8,
      "name": "기안자 A",
      "email": "drafter@example.com",
      "isDeleted": false
    },
    "title": "3월 운영비 집행",
    "content": "<p>3월 운영비 집행 승인 요청입니다.</p>",
    "amount": 50000,
    "originalAmount": 50000,
    "expectedPaymentDate": "2026-02-11",
    "status": "COMPLETED",
    "currentStep": 1,
    "currency": "KRW",
    "createdAt": "2026-02-11T11:12:14.478782",
    "messages": [
      {
        "id": 878,
        "user": {
          "id": 8,
          "name": "기안자 A",
          "email": "drafter@example.com",
          "isDeleted": false
        },
        "content": "1차 결재가 승인되었습니다.",
        "type": "SYSTEM",
        "createdAt": "2026-02-11T11:12:25.120704",
        "deletedAt": null
      },
      {
        "id": 879,
        "user": {
          "id": 8,
          "name": "기안자 A",
          "email": "drafter@example.com",
          "isDeleted": false
        },
        "content": "결재 상태가 결재완료로 변경되었습니다.",
        "type": "SYSTEM",
        "createdAt": "2026-02-11T11:12:27.811770",
        "deletedAt": null
      }
    ],
    "attachments": [],
    "refundAccount": null,
    "steps": [
      {
        "id": 573,
        "approver": {
          "id": 8,
          "name": "결재자 A",
          "email": "approver@example.com",
          "isDeleted": false
        },
        "step": 1,
        "status": "APPROVED",
        "createdAt": "2026-02-11T11:12:14.483147",
        "modifiedAt": "2026-02-11T11:12:25.137155"
      }
    ],
    "reviewers": [],
    "tag": null,
    "tagId": null,
    "modifiedAt": "2026-02-11T11:12:27.813271"
  }
]

POST /api/public-docs/workflows

외부 시스템에서 결재 제목, 내용, 금액, 결재자 순서를 지정해 전자결재 문서를 생성합니다.

Request Fields

쓰기 요청입니다. 재시도 안전성이 필요하면 `Idempotency-Key` 헤더를 고정 값으로 전달하세요.

전자결재 생성만 지원합니다. 전자결재 수정/삭제 API는 아직 공개하지 않습니다.

`approverIds` 순서가 결재 단계 순서가 됩니다. 최소 1명의 결재자가 필요합니다.

`expectedPaymentDate`를 생략하면 요청 처리일 기준 날짜가 사용됩니다.

전자결재 생성 권한이 없는 API key 또는 플랜에서는 403 응답이 반환될 수 있습니다.

titlestringrequired

결재 제목

contentstringrequired

결재 내용. HTML 문자열도 전달할 수 있습니다.

originalAmountnumber | stringrequired

결재 금액. `150,000원` 같은 문자열도 허용합니다.

approverIdsnumber[]required

결재자 ID 배열. 배열 순서대로 1차, 2차 결재자가 됩니다.

reviewerIdsnumber[]optional

검토자/참조자 ID 배열

expectedPaymentDateYYYY-MM-DDoptional

지급예정일. 생략 시 요청 처리일 기준 날짜

currencystringoptional

통화 코드. 기본값은 KRW

refundAccountobjectoptional

환불/이체 계좌 정보. 제공 시 accountHolder, accountNumber, organizationName이 모두 필요합니다.

refundAccount.accountHolderstringoptional

예금주

refundAccount.accountNumberstringoptional

계좌번호

refundAccount.organizationNamestringoptional

은행명/기관명

Response Fields

idnumberrequired

전자결재 ID

workspaceIdnumberrequired

워크스페이스 ID

titlestringrequired

결재안 제목

contentstringrequired

결재 내용

amountnumberrequired

결재 금액

originalAmountnumberrequired

원본 결재 금액

expectedPaymentDateYYYY-MM-DDrequired

이체 요청일

status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required

결재 상태

currencystringrequired

통화 코드

createdAtISO-8601 stringrequired

결재 요청 시각

modifiedAtISO-8601 stringrequired

최종 수정 시각

currentStepnumberrequired

현재 결재 차수

tagstring | nulloptional

연결된 태그명

tagIdnumber | nulloptional

연결된 태그 ID

▶userUserrequiredexpandable

기안자 정보

idnumberrequired

기안자 ID

namestringrequired

기안자 이름

emailstringrequired

기안자 이메일

isDeletedbooleanrequired

삭제 여부

▶refundAccountRefundAccountoptionalexpandable

환급 계좌 정보

accountHolderstringrequired

예금주명

accountNumberstringrequired

계좌번호

organizationNamestringrequired

은행명

▶stepsWorkflowStep[]requiredexpandable

결재 단계 목록

idnumberrequired

결재 단계 ID

stepnumberrequired

결재 차수

status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required

결재 단계 상태

createdAtISO-8601 stringrequired

생성 시각

modifiedAtISO-8601 stringrequired

수정 시각

▶approverApproverrequiredexpandable

결재자 정보

idnumberrequired

결재자 ID

namestringrequired

결재자 이름

emailstringrequired

결재자 이메일

isDeletedbooleanrequired

삭제 여부

▶reviewersReviewer[]requiredexpandable

검토자 목록

idnumberrequired

검토자 연결 ID

▶reviewerUserResponserequiredexpandable

검토자 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesWorkflowMessage[]optionalexpandable

결재 메시지 목록

idnumberrequired

메시지 ID

contentstringrequired

메시지 내용

typestringrequired

메시지 타입

createdAtISO-8601 stringrequired

생성 시각

deletedAtISO-8601 string | nulloptional

삭제 시각

▶userUserResponserequiredexpandable

작성자 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶attachmentsWorkflowAttachment[]optionalexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/workflows \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "title": "4월 운영비 집행",
  "content": "<p>4월 운영비 집행 승인 요청입니다.</p>",
  "originalAmount": 150000,
  "expectedPaymentDate": "2026-04-30",
  "currency": "KRW",
  "approverIds": [8],
  "reviewerIds": [],
  "refundAccount": {
    "accountHolder": "그랜터",
    "accountNumber": "1234567890",
    "organizationName": "국민은행"
  }
}'

POST /api/public-docs/workflows

Workflow Create Response Example

{
  "id": 333,
  "workspaceId": 1,
  "user": {
    "id": 8,
    "name": "기안자 A",
    "email": "drafter@example.com",
    "isDeleted": false
  },
  "title": "4월 운영비 집행",
  "content": "<p>4월 운영비 집행 승인 요청입니다.</p>",
  "amount": 150000,
  "originalAmount": 150000,
  "expectedPaymentDate": "2026-04-30",
  "status": "REQUESTED",
  "currentStep": 1,
  "currency": "KRW",
  "createdAt": "2026-04-30T11:12:14.478782",
  "messages": [],
  "attachments": [],
  "refundAccount": {
    "accountHolder": "그랜터",
    "accountNumber": "1234567890",
    "organizationName": "국민은행"
  },
  "steps": [
    {
      "id": 573,
      "approver": {
        "id": 8,
        "name": "결재자 A",
        "email": "approver@example.com",
        "isDeleted": false
      },
      "step": 1,
      "status": "REQUESTED",
      "createdAt": "2026-04-30T11:12:14.483147",
      "modifiedAt": "2026-04-30T11:12:14.483147"
    }
  ],
  "reviewers": [],
  "tag": null,
  "tagId": null,
  "modifiedAt": "2026-04-30T11:12:14.483147"
}

POST /api/public-docs/salary-histories

직원별 급여 내역, 지급 상태, 보험료, 수당·공제 상세를 조회합니다.

Request Fields

급여는 티켓과 분리된 독립 도메인입니다.

조회 시 `startDate`, `endDate`는 필수입니다.

기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.

`employmentType`, `salaryPaymentStatus`, `employeeId`, `keyword`는 선택 필터입니다.

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

고용 형태 필터. 단일 값 또는 배열을 전달할 수 있습니다.

salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID" | arrayoptional

급여 지급 상태 필터. 단일 값 또는 배열을 전달할 수 있습니다.

employeeIdnumberoptional

직원 ID 필터

keywordstringoptional

직원명 또는 설명 키워드 검색

Response Fields

▶[]SalaryHistoryrequiredexpandable

BE `/salary-histories` 원본 응답 배열의 각 원소

idnumberrequired

급여 이력 ID

workspaceIdnumberrequired

워크스페이스 ID

▶employeeUserResponseoptionalexpandable

직원 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

employeeIdnumberrequired

직원 ID

employeeNamestringoptional

직원명

employeeEmailstring | nulloptional

직원 이메일

고용 형태

totalAmountnumberrequired

총급여

recognizedAmountnumberrequired

실질인정금액

paymentDateYYYY-MM-DDrequired

지급일

mealAmountnumberrequired

비과세 식대

bonusAmountnumberrequired

상여금

allowanceAmountnumberrequired

수당 합계

pensionInsuranceAmountnumberrequired

국민연금

healthInsuranceAmountnumberrequired

건강보험

employInsuranceAmountnumberrequired

고용보험

careInsuranceAmountnumberrequired

장기요양보험

bankstringoptional

은행명

bankAccountstringoptional

은행 계좌번호

netAmountnumberrequired

실지급액

descriptionstringoptional

설명

employmentDiscount"NONE" | "GENERAL" | "YOUTH"required

고용 할인 유형

incomeTaxAmountnumberoptional

소득세

localIncomeTaxAmountnumberoptional

지방소득세

salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID"required

급여 지급 상태

isEmailNotifiedbooleanrequired

명세서 email 발송 여부

emailNotifiedAtISO-8601 string | nulloptional

email 발송 시각

messageCountnumberrequired

메시지 개수

scheduledWorkHoursnumberrequired

당월 근무 시간

shortfallHoursnumberrequired

미달 근무 시간

unpaidLeaveHoursnumberoptional

무급휴가 시간

recognizedWorkHoursnumberrequired

근무 인정 시간

appliedRatioTypestringoptional

적용 비율 타입

appliedRationumberoptional

적용 비율

▶taxExemptionsTitleAmount[]optionalexpandable

비과세급 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶incentivesTitleAmount[]optionalexpandable

인센티브 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶allowancesTitleAmount[]optionalexpandable

수당 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶deductionsTitleAmount[]optionalexpandable

공제 상세

titlestringrequired

항목명

amountnumberrequired

금액

createdAtISO-8601 stringrequired

생성 시각

modifiedAtISO-8601 stringrequired

수정 시각

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/salary-histories \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-02-01",
  "endDate": "2026-02-28"
}'

POST /api/public-docs/salary-histories

Salary History Response Example

[
  {
    "id": 303,
    "workspaceId": 1,
    "employee": {
      "id": 67,
      "name": "직원 A",
      "email": "employee-a@example.com",
      "isDeleted": false
    },
    "employeeName": "직원 A",
    "employeeEmail": null,
    "employmentType": "REGULAR_EMPLOYEE",
    "totalAmount": 5000000,
    "paymentDate": "2026-02-01",
    "mealAmount": 3000,
    "bonusAmount": 10000,
    "pensionInsuranceAmount": 261000,
    "healthInsuranceAmount": 198080,
    "employInsuranceAmount": 49580,
    "careInsuranceAmount": 26020,
    "bank": "국민은행",
    "bankAccount": "123-45-****",
    "recognizedAmount": 5003000,
    "netAmount": 4519877,
    "description": "",
    "employmentDiscount": "NONE",
    "incomeTaxAmount": 405590,
    "localIncomeTaxAmount": 40550,
    "salaryPaymentStatus": "PENDING",
    "isEmailNotified": false,
    "emailNotifiedAt": null,
    "messageCount": 0,
    "scheduledWorkHours": 28,
    "shortfallHours": 0,
    "unpaidLeaveHours": 0,
    "recognizedWorkHours": 28,
    "allowanceAmount": 500000,
    "appliedRatioType": "",
    "appliedRatio": 1,
    "taxExemptions": [{ "title": "비과세급", "amount": 3000 }],
    "incentives": [{ "title": "상여금", "amount": 10000 }],
    "allowances": [{ "title": "직책수당", "amount": 500000 }],
    "deductions": [{ "title": "기타 공제", "amount": 12303 }],
    "createdAt": "2026-02-11T14:02:48.545431",
    "modifiedAt": "2026-02-28T14:22:59.327028"
  }
]

POST /api/public-docs/salary-histories-create

외부 시스템에서 계산한 직원별 급여 내역을 생성합니다.

Request Fields

급여 내역 생성만 지원합니다. 급여 수정/삭제 API는 아직 공개하지 않습니다.

요청 재시도 중 중복 생성을 줄이려면 `Idempotency-Key` 헤더를 고정값으로 전달하세요.

`employeeId`, `employeeName`, `employeeEmail` 중 하나는 필요합니다. 기존 구성원 급여라면 `people` API에서 조회한 `employeeId`를 사용하는 편이 가장 안전합니다.

금액·근무시간 상세를 생략하면 public proxy가 0 또는 지급월 기준 일수로 보수적으로 채워 upstream에 전달합니다. 외부 급여 시스템의 확정값이 있으면 직접 전달하세요.

employeeIdnumberoptional

직원 ID. 기존 구성원 급여 생성 시 권장

employeeNamestringoptional

직원명. 비회원 또는 수동 급여 생성 시 사용

employeeEmailstringoptional

직원 이메일

고용 형태

totalAmountnumberrequired

기본 급여 또는 총 급여 기준 금액

paymentDateYYYY-MM-DDrequired

지급일

mealAmountnumberoptional

비과세 식대. 생략 시 0

bonusAmountnumberoptional

상여금. 생략 시 0

allowanceAmountnumberoptional

수당 합계. 생략 시 allowances 합계 또는 0

pensionInsuranceAmountnumberoptional

국민연금. 생략 시 0

healthInsuranceAmountnumberoptional

건강보험. 생략 시 0

employInsuranceAmountnumberoptional

고용보험. 생략 시 0

careInsuranceAmountnumberoptional

장기요양보험. 생략 시 0

bankstringoptional

급여 입금 은행명

bankAccountstringoptional

급여 입금 계좌번호

descriptionstringoptional

급여 내역 메모

recognizedAmountnumberoptional

실질인정금액. 생략 시 totalAmount + mealAmount

netAmountnumberoptional

실지급액. 생략 시 지급/공제 항목으로 계산

employmentDiscount"NONE" | "GENERAL" | "YOUTH"optional

고용 할인 유형. 생략 시 NONE

incomeTaxAmountnumberoptional

소득세. 생략 시 0

localIncomeTaxAmountnumberoptional

지방소득세. 생략 시 0

salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID"optional

급여 지급 상태. 생략 시 PENDING

scheduledWorkHoursnumberoptional

당월 근무 시간/일수. 생략 시 지급월 일수

shortfallHoursnumberoptional

미달 근무 시간/일수. 생략 시 0

unpaidLeaveHoursnumberoptional

무급휴가 시간/일수. 생략 시 0

recognizedWorkHoursnumberoptional

근무 인정 시간/일수. 생략 시 scheduledWorkHours - shortfallHours - unpaidLeaveHours

appliedRatioTypestringoptional

적용 비율 타입. 생략 시 빈 문자열

appliedRationumberoptional

적용 비율. 생략 시 1

taxExemptions{ title: string; amount: number }[]optional

비과세급 상세. 생략 시 빈 배열

incentives{ title: string; amount: number }[]optional

인센티브 상세. 생략 시 빈 배열

allowances{ title: string; amount: number }[]optional

수당 상세. 생략 시 빈 배열

deductions{ title: string; amount: number }[]optional

공제 상세. 생략 시 빈 배열

Response Fields

idnumberrequired

급여 이력 ID

workspaceIdnumberrequired

워크스페이스 ID

▶employeeUserResponseoptionalexpandable

직원 정보

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

employeeIdnumberrequired

직원 ID

employeeNamestringoptional

직원명

employeeEmailstring | nulloptional

직원 이메일

고용 형태

totalAmountnumberrequired

총급여

recognizedAmountnumberrequired

실질인정금액

paymentDateYYYY-MM-DDrequired

지급일

mealAmountnumberrequired

비과세 식대

bonusAmountnumberrequired

상여금

allowanceAmountnumberrequired

수당 합계

pensionInsuranceAmountnumberrequired

국민연금

healthInsuranceAmountnumberrequired

건강보험

employInsuranceAmountnumberrequired

고용보험

careInsuranceAmountnumberrequired

장기요양보험

bankstringoptional

은행명

bankAccountstringoptional

은행 계좌번호

netAmountnumberrequired

실지급액

descriptionstringoptional

설명

employmentDiscount"NONE" | "GENERAL" | "YOUTH"required

고용 할인 유형

incomeTaxAmountnumberoptional

소득세

localIncomeTaxAmountnumberoptional

지방소득세

salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID"required

급여 지급 상태

isEmailNotifiedbooleanrequired

명세서 email 발송 여부

emailNotifiedAtISO-8601 string | nulloptional

email 발송 시각

messageCountnumberrequired

메시지 개수

scheduledWorkHoursnumberrequired

당월 근무 시간

shortfallHoursnumberrequired

미달 근무 시간

unpaidLeaveHoursnumberoptional

무급휴가 시간

recognizedWorkHoursnumberrequired

근무 인정 시간

appliedRatioTypestringoptional

적용 비율 타입

appliedRationumberoptional

적용 비율

▶taxExemptionsTitleAmount[]optionalexpandable

비과세급 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶incentivesTitleAmount[]optionalexpandable

인센티브 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶allowancesTitleAmount[]optionalexpandable

수당 상세

titlestringrequired

항목명

amountnumberrequired

금액

▶deductionsTitleAmount[]optionalexpandable

공제 상세

titlestringrequired

항목명

amountnumberrequired

금액

createdAtISO-8601 stringrequired

생성 시각

modifiedAtISO-8601 stringrequired

수정 시각

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/salary-histories-create \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "employeeId": 67,
  "employeeName": "직원 A",
  "employmentType": "REGULAR_EMPLOYEE",
  "totalAmount": 5000000,
  "paymentDate": "2026-04-25",
  "mealAmount": 200000,
  "bonusAmount": 100000,
  "pensionInsuranceAmount": 225000,
  "healthInsuranceAmount": 180000,
  "employInsuranceAmount": 45000,
  "careInsuranceAmount": 23000,
  "incomeTaxAmount": 405590,
  "localIncomeTaxAmount": 40550,
  "salaryPaymentStatus": "PENDING",
  "allowances": [{ "title": "직책수당", "amount": 300000 }],
  "deductions": [{ "title": "기타 공제", "amount": 10000 }]
}'

POST /api/public-docs/salary-histories-create

Salary History Create Response Example

{
  "id": 331,
  "workspaceId": 1,
  "employee": {
    "id": 67,
    "name": "직원 A",
    "email": "employee-a@example.com",
    "isDeleted": false
  },
  "employeeName": "직원 A",
  "employeeEmail": null,
  "employmentType": "REGULAR_EMPLOYEE",
  "totalAmount": 5000000,
  "paymentDate": "2026-04-25",
  "mealAmount": 200000,
  "bonusAmount": 100000,
  "pensionInsuranceAmount": 225000,
  "healthInsuranceAmount": 180000,
  "employInsuranceAmount": 45000,
  "careInsuranceAmount": 23000,
  "bank": "국민은행",
  "bankAccount": "123-45-****",
  "recognizedAmount": 5200000,
  "netAmount": 4670860,
  "description": "",
  "employmentDiscount": "NONE",
  "incomeTaxAmount": 405590,
  "localIncomeTaxAmount": 40550,
  "salaryPaymentStatus": "PENDING",
  "isEmailNotified": false,
  "emailNotifiedAt": null,
  "messageCount": 0,
  "scheduledWorkHours": 30,
  "shortfallHours": 0,
  "unpaidLeaveHours": 0,
  "recognizedWorkHours": 30,
  "allowanceAmount": 300000,
  "appliedRatioType": "",
  "appliedRatio": 1,
  "taxExemptions": [{ "title": "비과세 식대", "amount": 200000 }],
  "incentives": [],
  "allowances": [{ "title": "직책수당", "amount": 300000 }],
  "deductions": [{ "title": "기타 공제", "amount": 10000 }],
  "createdAt": "2026-04-30T10:00:00.000000",
  "modifiedAt": "2026-04-30T10:00:00.000000"
}

GET /api/public-docs/inventory-products

품목명, 단가, 통화, 추가 속성으로 구성된 품목 마스터를 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

직접 호출 시 `limit`, `lastSeenId` query string을 사용할 수 있습니다.

limitnumberoptional

조회 건수 제한

lastSeenIdnumberoptional

페이지네이션 기준 ID

Response Fields

▶[]InventoryProductrequiredexpandable

BE `/inventory-products` 원본 응답 배열의 각 원소

idnumberrequired

품목 ID

namestringrequired

품목명

unitPricenumberrequired

단가

currencyCurrencyCoderequired

통화 코드

▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable

추가 속성 목록

idnumberrequired

추가 속성 ID

keystringrequired

속성명

valuestringrequired

속성값

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/inventory-products \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/inventory-products

Inventory Product Response Example

[
  {
    "id": 63,
    "name": "샘플 품목 A",
    "unitPrice": 123,
    "currency": "KRW",
    "additionalProperties": [
      { "id": 23, "key": "EXP date", "value": "" },
      { "id": 22, "key": "창고", "value": "" },
      { "id": 13, "key": "커스텀속성2", "value": "" }
    ]
  }
]

GET /api/public-docs/inventories

품목별 현재 재고 수량, 재고 메시지 수, 최근 수정 시각을 포함한 재고 현황을 조회합니다.

Request Fields

요청 body는 사용하지 않습니다.

직접 호출 시 `limit`, `lastSeenId` query string을 사용할 수 있습니다.

limitnumberoptional

조회 건수 제한

lastSeenIdnumberoptional

페이지네이션 기준 ID

Response Fields

▶[]InventoryStockrequiredexpandable

BE `/inventories` 원본 응답 배열의 각 원소

idnumberrequired

재고 엔트리 ID

inventoryProductIdnumberrequired

품목 ID

namestringrequired

품목명

unitPricenumberrequired

단가

quantitynumberrequired

현재 재고 수량

currencyCurrencyCoderequired

통화 코드

createdAtISO-8601 stringrequired

생성 시각

modifiedAtISO-8601 stringrequired

수정 시각

messageCountnumberrequired

메시지 개수

▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable

추가 속성 목록

idnumberrequired

추가 속성 ID

keystringrequired

속성명

valuestringrequired

속성값

호출

API KEY

호출 예시

cURL

curl -X GET https://app.granter.biz/api/public-docs/inventories \
  -H "Authorization: Basic <BASE64(API_KEY:)>"

GET /api/public-docs/inventories

Inventory Stock Response Example

[
  {
    "id": 3,
    "inventoryProductId": 2,
    "name": "샘플 재고 품목 A",
    "unitPrice": 880000,
    "quantity": 10,
    "currency": "KRW",
    "createdAt": "2025-12-05T12:29:29.850909",
    "modifiedAt": "2026-02-11T13:05:46.900783",
    "messageCount": 0,
    "additionalProperties": [
      { "id": 18, "key": "1211", "value": "123123" },
      { "id": 14, "key": "123", "value": "123" },
      { "id": 22, "key": "창고", "value": "" }
    ]
  }
]

POST /api/public-docs/attendances

구성원의 출퇴근 기록과 휴가 사용 내역을 기간별로 조회합니다.

Request Fields

조회 시 `startDate`, `endDate`는 필수입니다.

기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.

`userIds`로 특정 구성원만 필터링하거나, `recordType`으로 근무/휴가를 구분할 수 있습니다.

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

userIdsnumber[]optional

조회 대상 유저 ID 목록

recordType"WORK" | "LEAVE"optional

기록 타입 필터. WORK: 근무만, LEAVE: 휴가만, 미입력 시 전체

Response Fields

▶[]TimeCardRecordrequiredexpandable

근무/휴가 기록 배열

▶timeCardTimeCardrequiredexpandable

타임카드 정보

workspaceIdnumberrequired

워크스페이스 ID

userIdnumberrequired

유저 ID

baseDateYYYY-MM-DDrequired

기준일

startedAtISO-8601 stringrequired

시작 일시

endedAtISO-8601 stringoptional

종료 일시

createdAtISO-8601 stringrequired

생성 일시

modifiedAtISO-8601 stringrequired

수정 일시

▶workRecordWorkRecord | nulloptionalexpandable

근무 기록 (휴가인 경우 null)

workRecordIdnumberrequired

근무 기록 ID

▶clockInLocationClockLocationrequiredexpandable

출근 위치

ipstringrequired

IP 주소

addressstringrequired

주소

addressDetailstringrequired

상세 주소

latitudenumberrequired

위도

longitudenumberrequired

경도

radiusnumberrequired

허용 반경 (m)

▶clockOutLocationClockLocation | nulloptionalexpandable

퇴근 위치

ipstringrequired

IP 주소

addressstringrequired

주소

addressDetailstringrequired

상세 주소

latitudenumberrequired

위도

longitudenumberrequired

경도

radiusnumberrequired

허용 반경 (m)

isRemotebooleanrequired

원격 근무 여부

breakStartedAtISO-8601 string | nulloptional

기본 휴게 시작 일시

breakEndedAtISO-8601 string | nulloptional

기본 휴게 종료 일시

▶additionalBreakTimesWorkBreakTime[]requiredexpandable

추가 휴게시간 목록

startedAtISO-8601 stringrequired

추가 휴게 시작 일시

endedAtISO-8601 stringrequired

추가 휴게 종료 일시

▶leaveRecordLeaveRecord | nulloptionalexpandable

휴가 기록 (근무인 경우 null)

leaveRecordIdnumberrequired

휴가 기록 ID

approverUserIdnumber | nulloptional

결재자 유저 ID

reasonstringrequired

휴가 사유

statusREQUESTED | APPROVED | REJECTEDrequired

승인 상태

approvedAtISO-8601 string | nulloptional

승인 일시

rejectedAtISO-8601 string | nulloptional

반려 일시

rejectedReasonstring | nulloptional

반려 사유

createdAtISO-8601 stringrequired

생성 일시

modifiedAtISO-8601 stringrequired

수정 일시

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/attendances \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-03-01",
  "endDate": "2026-03-15"
}'

POST /api/public-docs/attendances

Attendance Response Example

[
  {
    "timeCard": {
      "workspaceId": 1,
      "userId": 67,
      "baseDate": "2026-03-10",
      "startedAt": "2026-03-10T09:00:00",
      "endedAt": "2026-03-10T18:00:00",
      "createdAt": "2026-03-10T09:00:12.345678",
      "modifiedAt": "2026-03-10T18:00:45.123456"
    },
      "workRecord": {
        "workRecordId": 101,
        "clockInLocation": {
          "ip": "192.168.1.10",
          "address": "서울특별시 강남구",
        "addressDetail": "테헤란로 123",
        "latitude": 37.5065,
        "longitude": 127.0536,
        "radius": 200.0
      },
      "clockOutLocation": {
        "ip": "192.168.1.10",
        "address": "서울특별시 강남구",
        "addressDetail": "테헤란로 123",
        "latitude": 37.5065,
          "longitude": 127.0536,
          "radius": 200.0
        },
        "isRemote": false,
        "breakStartedAt": "2026-03-10T12:00:00",
        "breakEndedAt": "2026-03-10T13:00:00",
        "additionalBreakTimes": [
          {
            "startedAt": "2026-03-10T18:00:00",
            "endedAt": "2026-03-10T18:30:00"
          }
        ]
      },
    "leaveRecord": null
  },
  {
    "timeCard": {
      "workspaceId": 1,
      "userId": 67,
      "baseDate": "2026-03-12",
      "startedAt": "2026-03-12T00:00:00",
      "endedAt": "2026-03-12T23:59:59",
      "createdAt": "2026-03-11T15:30:00.000000",
      "modifiedAt": "2026-03-12T10:00:00.000000"
    },
    "workRecord": null,
    "leaveRecord": {
      "leaveRecordId": 55,
      "approverUserId": 4,
      "reason": "개인 사유",
      "status": "APPROVED",
      "approvedAt": "2026-03-11T16:00:00",
      "rejectedAt": null,
      "rejectedReason": null,
      "createdAt": "2026-03-11T15:30:00.000000",
      "modifiedAt": "2026-03-11T16:00:00.000000"
    }
  }
]

POST /api/public-docs/leave-balances

구성원별 잔여 연차 현황을 조회합니다.

Request Fields

`baseDate`는 선택값이며, 미입력 시 백엔드 기본 기준일로 계산합니다.

baseDateYYYY-MM-DDoptional

잔여 연차를 계산할 기준일

Response Fields

▶[]LeaveBalancerequiredexpandable

구성원별 잔여 연차 배열

workspaceUserIdnumberrequired

워크스페이스 유저 ID

userIdnumberrequired

유저 ID

isUnlimitedbooleanrequired

무제한 연차 여부. true이면 나머지 일수 필드는 null일 수 있습니다.

theoreticalDaysnumber | nulloptional

정책과 입사일 기준으로 계산한 이론적 발생 연차 일수

adjustmentDaysnumber | nulloptional

수동 조정, 사용, 소멸을 반영한 가감 일수 합계

employmentDateYYYY-MM-DD | nulloptional

입사일. 휴가 정책 승인자가 아니거나 급여 정보가 없으면 null입니다.

retirementDateYYYY-MM-DD | nulloptional

퇴사일. 휴가 정책 승인자가 아니거나 급여 정보가 없으면 null입니다.

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/leave-balances \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "baseDate": "2026-03-31"
}'

POST /api/public-docs/leave-balances

Leave Balance Response Example

[
  {
    "workspaceUserId": 18,
    "userId": 67,
    "isUnlimited": false,
    "theoreticalDays": 15,
    "adjustmentDays": -3,
    "employmentDate": "2024-03-01",
    "retirementDate": null
  }
]

POST /api/public-docs/leave-histories

구성원의 연차 변경 내역을 기간별로 조회합니다.

Request Fields

조회 시 `startDate`, `endDate`는 필수입니다.

기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.

휴가 사용, 사용 취소, 소멸, 수동 조정 내역이 함께 반환됩니다.

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

Response Fields

▶[]LeaveHistoryrequiredexpandable

연차 변경 이력 배열

idnumberrequired

연차 변경 이력 ID

userIdnumberrequired

대상 유저 ID

requestUserIdnumberrequired

변경을 요청한 유저 ID

daysnumberrequired

변경 일수

연차 변경 유형

occurredAtYYYY-MM-DDrequired

변경 발생일

expiresAtYYYY-MM-DD | nulloptional

소멸 예정일

timeCardIdnumber | nulloptional

연관 타임카드 ID

memostring | nulloptional

메모

createdAtISO-8601 stringrequired

생성 일시

modifiedAtISO-8601 stringrequired

수정 일시

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/leave-histories \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-03-01",
  "endDate": "2026-03-31"
}'

POST /api/public-docs/leave-histories

Leave History Response Example

[
  {
    "id": 91,
    "userId": 67,
    "requestUserId": 4,
    "days": 1,
    "type": "USAGE",
    "occurredAt": "2026-03-12",
    "expiresAt": null,
    "timeCardId": 310,
    "memo": "개인 사유",
    "createdAt": "2026-03-11T15:30:00.000000",
    "modifiedAt": "2026-03-11T16:00:00.000000"
  },
  {
    "id": 92,
    "userId": 67,
    "requestUserId": 4,
    "days": 2,
    "type": "ADJUSTMENT_ADD",
    "occurredAt": "2026-03-20",
    "expiresAt": "2027-03-19",
    "timeCardId": null,
    "memo": "관리자 수동 부여",
    "createdAt": "2026-03-20T09:00:00.000000",
    "modifiedAt": "2026-03-20T09:00:00.000000"
  }
]

POST /api/public-docs/holidays

기간 내 한국 공휴일 목록을 조회합니다.

Request Fields

조회 시 `startDate`, `endDate`는 필수입니다.

공공데이터포털 또는 대체 공휴일 소스에서 공휴일을 조회하며, 소스 장애 시 `enabled=false`로 응답합니다.

startDateYYYY-MM-DDrequired

조회 시작일

endDateYYYY-MM-DDrequired

조회 종료일

Response Fields

enabledbooleanrequired

공휴일 조회 가능 여부

reasonstring | nulloptional

조회 실패 사유

datesYYYY-MM-DD[]required

공휴일 날짜 목록

▶holidaysHoliday[]requiredexpandable

공휴일 상세 목록

dateYYYY-MM-DDrequired

공휴일 날짜

namestringrequired

공휴일 이름

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/holidays \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31"
}'

POST /api/public-docs/holidays

Holiday Response Example

{
  "enabled": true,
  "dates": ["2026-05-05", "2026-05-25"],
  "holidays": [
    {
      "date": "2026-05-05",
      "name": "어린이날"
    },
    {
      "date": "2026-05-25",
      "name": "부처님오신날"
    }
  ]
}

POST /api/public-docs/cards

자동 연동이 아닌 외부 시스템 기준의 수기 카드를 생성합니다. 생성된 카드 ID는 수기 카드거래 입력 API의 cardId로 사용합니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`organization`은 카드사 enum 또는 한국어 라벨(예: 롯데카드, 하나카드, KB국민카드)을 사용할 수 있으며, 직접 생성 카드는 `CUSTOM_CARD`를 권장합니다.

`cardNumber`는 백엔드 필수값입니다. JavaScript 정수 정밀도 손실을 막기 위해 숫자만 포함한 문자열로 전달하세요.

namestringrequired

카드 별칭/이름

organizationCardOrganizationrequired

카드사 enum. 수기 카드는 CUSTOM_CARD 권장

cardNumberstringrequired

카드번호. 숫자만 포함한 문자열로 전달

Response Fields

▶[]Assetrequiredexpandable

BE `/assets` 원본 응답 배열의 각 원소

idnumberrequired

자산 ID

assetTypeAssetTyperequired

자산 타입

numberstringrequired

자산 번호

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

별칭

organizationOrganizationTyperequired

금융기관 코드

organizationNamestringrequired

금융기관명

businessTypeBusinessTyperequired

업종

businessTypeNameBusinessTypeNamerequired

업종명

isHiddenbooleanrequired

숨김 여부

isActivebooleanrequired

활성 여부

isDormantbooleanrequired

휴면 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isFreebooleanrequired

무료 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientTypeClientTyperequired

고객 유형

userAutoAssignEnabledbooleanrequired

자동 할당 여부

▶cardAssetCardInfooptionalexpandable

카드 자산 정보

expirationYearstringrequired

만료 연도

expirationMonthstringrequired

만료 월

limitAmountnumberrequired

한도 금액

usedAmountnumberrequired

사용 금액

remainLimitnumberrequired

잔여 한도

previousCardNumberstringoptional

이전 카드 번호

▶bankAccountAssetBankAccountInfooptionalexpandable

계좌 자산 정보

accountBalancenumberrequired

계좌 잔액

originalBalancenumberrequired

원본 계좌 잔액

currencyCodestringrequired

통화 코드

startDatestringrequired

조회 시작일

endDatestringrequired

조회 종료일

accountNumberstringrequired

계좌 번호

accountNamestringrequired

계좌명

nicknamestringrequired

별칭

accountTypeAccountTyperequired

계좌 유형

isTransactionVisiblebooleanrequired

거래내역 보유 여부

▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable

홈택스 자산 정보

category"CASH_RECEIPT" | "TAX_INVOICE"required

홈택스 자산 카테고리

registrationNumberstringrequired

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringrequired

회사명

ceoNamestringrequired

대표자명

addressstringrequired

주소

contactNamestringrequired

담당자명

telstringrequired

연락처

businessTypesstringrequired

업태

businessItemsstringrequired

종목

▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable

증권 자산 정보

totalAmountnumberrequired

총액(원화)

depositAmountnumberrequired

예수금(원화)

foreignDepositAmountnumberrequired

외화예수금(원화)

▶foreignDepositsForeignDeposit[]requiredexpandable

외화예수금 보유 목록

idnumberrequired

외화예수금 ID

currencyCurrencyCoderequired

통화 코드

amountnumberrequired

금액

createdAtstringrequired

생성 시각

totalValuationAmountnumberrequired

보유 주식 평가액 합계(원화)

accountNumberstringrequired

계좌번호

▶productsProduct[]requiredexpandable

보유 투자상품

idnumberrequired

상품 ID

productTypestringrequired

상품 유형 코드

productTypeNamestringrequired

상품 유형명

namestringrequired

상품명

codestringoptional

상품 코드

quantitynumberoptional

수량

currencyCurrencyCoderequired

통화 코드

krwPresentAmountnumberoptional

현재 금액(원화)

presentAmountnumberoptional

현재 금액

krwValuationAmountnumberoptional

평가 금액(원화)

valuationAmountnumberoptional

평가 금액

krwValuationPLnumberoptional

평가 손익(원화)

valuationPLnumberoptional

평가 손익

earningsRatenumberoptional

수익률

createdAtstringrequired

생성 시각

▶customAssetAssetCustomInfooptionalexpandable

커스텀 자산 정보

assetType"CASH" | "LIABILITY" | "ASSET"required

커스텀 자산 유형

assetNumberstringrequired

자산 번호

amountnumberrequired

금액

▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable

이커머스 스토어 계정 정보

usernamestringrequired

스토어 사용자명

isOtpVerifiedbooleanrequired

OTP 인증 여부

createdAtstringoptional

생성 시각

modifiedAtstringoptional

수정 시각

hasPasswordbooleanoptional

비밀번호 보유 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/cards \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "name": "외부 ERP 법인카드",
  "organization": "CUSTOM_CARD",
  "cardNumber": "4111111111111111"
}'

POST /api/public-docs/cards

Manual Card Create Response Example

{
  "id": 3101,
  "assetType": "CARD",
  "name": "외부 ERP 법인카드",
  "organization": "CUSTOM_CARD",
  "number": "4111111111111111",
  "isActive": true,
  "source": "USER"
}

POST /api/public-docs/bank-accounts

자동 연동이 아닌 외부 시스템 기준의 수기 계좌를 생성합니다. 생성된 계좌 ID는 수기 계좌거래 입력 API의 bankAccountId로 사용합니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`organization`은 은행 enum 또는 한국어 라벨(예: 신한은행, 하나은행, KB국민은행)을 사용할 수 있으며, 직접 생성 계좌는 `CUSTOM_BANK_ACCOUNT`를 권장합니다.

`nickname`, `accountBalance`, `currencyCode`, `accountType`을 생략하면 각각 accountName, 0, KRW, DEPOSIT(비KRW는 FOREIGN)로 처리됩니다.

organizationBankAccountOrganizationrequired

은행 enum. 수기 계좌는 CUSTOM_BANK_ACCOUNT 권장

accountNamestringrequired

계좌명

nicknamestringoptional

계좌 별칭

accountNumberinteger | stringrequired

계좌번호. 문자열이면 하이픈 포함 가능

accountBalancenumber | stringoptional

초기 잔액

currencyCodestringoptional

통화 코드. 기본 KRW

accountTypestringoptional

계좌 유형. DEPOSIT, FOREIGN, FUND, LOAN, INSURANCE, PENSION, CASH 등

Response Fields

▶[]Assetrequiredexpandable

BE `/assets` 원본 응답 배열의 각 원소

idnumberrequired

자산 ID

assetTypeAssetTyperequired

자산 타입

numberstringrequired

자산 번호

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

별칭

organizationOrganizationTyperequired

금융기관 코드

organizationNamestringrequired

금융기관명

businessTypeBusinessTyperequired

업종

businessTypeNameBusinessTypeNamerequired

업종명

isHiddenbooleanrequired

숨김 여부

isActivebooleanrequired

활성 여부

isDormantbooleanrequired

휴면 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isFreebooleanrequired

무료 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientTypeClientTyperequired

고객 유형

userAutoAssignEnabledbooleanrequired

자동 할당 여부

▶cardAssetCardInfooptionalexpandable

카드 자산 정보

expirationYearstringrequired

만료 연도

expirationMonthstringrequired

만료 월

limitAmountnumberrequired

한도 금액

usedAmountnumberrequired

사용 금액

remainLimitnumberrequired

잔여 한도

previousCardNumberstringoptional

이전 카드 번호

▶bankAccountAssetBankAccountInfooptionalexpandable

계좌 자산 정보

accountBalancenumberrequired

계좌 잔액

originalBalancenumberrequired

원본 계좌 잔액

currencyCodestringrequired

통화 코드

startDatestringrequired

조회 시작일

endDatestringrequired

조회 종료일

accountNumberstringrequired

계좌 번호

accountNamestringrequired

계좌명

nicknamestringrequired

별칭

accountTypeAccountTyperequired

계좌 유형

isTransactionVisiblebooleanrequired

거래내역 보유 여부

▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable

홈택스 자산 정보

category"CASH_RECEIPT" | "TAX_INVOICE"required

홈택스 자산 카테고리

registrationNumberstringrequired

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringrequired

회사명

ceoNamestringrequired

대표자명

addressstringrequired

주소

contactNamestringrequired

담당자명

telstringrequired

연락처

businessTypesstringrequired

업태

businessItemsstringrequired

종목

▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable

증권 자산 정보

totalAmountnumberrequired

총액(원화)

depositAmountnumberrequired

예수금(원화)

foreignDepositAmountnumberrequired

외화예수금(원화)

▶foreignDepositsForeignDeposit[]requiredexpandable

외화예수금 보유 목록

idnumberrequired

외화예수금 ID

currencyCurrencyCoderequired

통화 코드

amountnumberrequired

금액

createdAtstringrequired

생성 시각

totalValuationAmountnumberrequired

보유 주식 평가액 합계(원화)

accountNumberstringrequired

계좌번호

▶productsProduct[]requiredexpandable

보유 투자상품

idnumberrequired

상품 ID

productTypestringrequired

상품 유형 코드

productTypeNamestringrequired

상품 유형명

namestringrequired

상품명

codestringoptional

상품 코드

quantitynumberoptional

수량

currencyCurrencyCoderequired

통화 코드

krwPresentAmountnumberoptional

현재 금액(원화)

presentAmountnumberoptional

현재 금액

krwValuationAmountnumberoptional

평가 금액(원화)

valuationAmountnumberoptional

평가 금액

krwValuationPLnumberoptional

평가 손익(원화)

valuationPLnumberoptional

평가 손익

earningsRatenumberoptional

수익률

createdAtstringrequired

생성 시각

▶customAssetAssetCustomInfooptionalexpandable

커스텀 자산 정보

assetType"CASH" | "LIABILITY" | "ASSET"required

커스텀 자산 유형

assetNumberstringrequired

자산 번호

amountnumberrequired

금액

▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable

이커머스 스토어 계정 정보

usernamestringrequired

스토어 사용자명

isOtpVerifiedbooleanrequired

OTP 인증 여부

createdAtstringoptional

생성 시각

modifiedAtstringoptional

수정 시각

hasPasswordbooleanoptional

비밀번호 보유 여부

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/bank-accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "organization": "CUSTOM_BANK_ACCOUNT",
  "accountName": "외부 ERP 현금계좌",
  "nickname": "ERP 현금",
  "accountNumber": "999-000-123456",
  "accountBalance": 1000000,
  "currencyCode": "KRW",
  "accountType": "DEPOSIT"
}'

POST /api/public-docs/bank-accounts

Manual Bank Account Create Response Example

{
  "id": 4201,
  "assetType": "BANK_ACCOUNT",
  "accountName": "외부 ERP 현금계좌",
  "nickname": "ERP 현금",
  "organization": "CUSTOM_BANK_ACCOUNT",
  "number": "999000123456",
  "accountBalance": "1000000",
  "currencyCode": "KRW",
  "isActive": true,
  "source": "USER"
}

POST /api/public-docs/card-usages

수기 카드에 카드 승인/취소 거래를 일괄 입력해 카드 티켓을 생성합니다. 먼저 수기 카드 생성 API 또는 자산 조회 API로 cardId를 확보하세요.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`cardId`에는 그랜터 카드 자산 ID를 넣습니다. 보통 `cards-create` 응답의 `id` 또는 `assets` 응답의 카드 `id`를 사용합니다.

취소 거래는 `paymentStatus=CANCELED`로 전달하고 `amount`는 양수로 유지하세요.

생성 API는 처리 ACK를 반환합니다. 생성된 티켓 ID가 필요하면 같은 기간과 `EXPENSE_TICKET`으로 `tickets` API를 조회하세요.

cardIdintegerrequired

대상 카드 자산 ID

cardUsagesCardUsageItem[]required

카드 사용 내역 배열

cardUsages[].paymentDateYYYY-MM-DD | ISO-8601 stringrequired

결제 일시

cardUsages[].storeNamestringrequired

가맹점명

cardUsages[].amountnumberrequired

결제 금액

cardUsages[].paymentStatus"NORMAL" | "CANCELED"optional

결제 상태. 기본 NORMAL

cardUsages[].isErrorbooleanoptional

오류 거래 표시

Response Fields

▶[]Ticketrequiredexpandable

BE `/tickets` 원본 응답 배열의 각 원소

idnumberrequired

티켓 ID

workspaceIdnumberrequired

워크스페이스 ID

contentstringrequired

거래/증빙 내용

amountnumberrequired

거래 금액

transactionType"IN" | "OUT" | "ALL"required

입출금 방향

transactAtISO-8601 stringrequired

거래 일시

modifiedTransactAtISO-8601 stringoptional

수정 거래 일시

descriptionstringrequired

설명

▶expenseCategoryExpenseCategoryoptionalexpandable

계정과목

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

anomalyStatus"NORMAL" | "ABUSE_SUSPECTED" | "ABUSE_CONFIRMED" | "ABUSE_REJECTED"required

이상치 상태

status"NONE" | "CONFIRMED" | "USER_CONFIRMED"required

티켓 상태

tagstringrequired

1차 태그명

tagIdnumber | nullrequired

1차 태그 ID

contactstringrequired

거래처명

contactIdnumber | undefinedrequired

거래처 ID

tagDetailstringrequired

2차 태그명

tagDetailIdnumber | nullrequired

2차 태그 ID

isIncludedbooleanrequired

포함 여부

▶usersUserResponse[]requiredexpandable

연결 유저 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesMessage[]requiredexpandable

메시지 목록

idnumberrequired

메시지 ID

ticketIdnumberrequired

티켓 ID

▶userUserResponserequiredexpandable

작성자

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

userIdnumberrequired

작성자 ID

userNamestringrequired

작성자 이름

contentstringrequired

메시지 내용

typeMessageTyperequired

메시지 타입

createdAtstringrequired

생성 시각

deletedAtstring | nulloptional

삭제 시각

messageCountnumberrequired

메시지 수

▶attachmentsAttachment[]requiredexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

ticketIdnumberrequired

티켓 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

attachmentCountnumberrequired

첨부파일 수

ticketTypeTicketTyperequired

조회 대상 티켓 타입

▶cardUsageCardUsageoptionalexpandable

카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶purchaseUsageCardUsageoptionalexpandable

매입 카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶bankTransactionBankTransactionoptionalexpandable

계좌 거래 상세

bankTransactionIdnumberrequired

은행거래 ID

workspaceIdnumberrequired

워크스페이스 ID

transactionType"IN" | "OUT" | "ALL"required

거래 방향

descriptionstringrequired

설명

afterTransactionBalancenumberrequired

거래 후 잔액

originalAfterTransactionBalancenumberoptional

원본 거래 후 잔액

amountnumberrequired

거래 금액

originalAmountnumberoptional

원본 거래 금액

transactAtstringrequired

거래 일시

▶bankAccountTicketAssetrequiredexpandable

계좌 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

counterpartystringoptional

거래 상대방

descriptionTypestringoptional

설명 분류

contentstringoptional

내용

branchstringoptional

지점

▶taxInvoiceTaxInvoiceoptionalexpandable

세금계산서 상세

idnumberrequired

세금계산서 ID

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶issuerobjectrequiredexpandable

발행자

emailstringrequired

이메일

idnumberrequired

유저 ID

isDeletedbooleanrequired

삭제 여부

namestringrequired

이름

▶trusteeTaxInvoiceUserrequiredexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentType"SUMMARY" | "DETAIL"required

내용 타입

transactionType"SELL" | "BUY" | "TRUSTEE"required

거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestringoptional

전송일자

issueDatestringoptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

purposeType"RECEIPT" | "CHARGE"required

영수/청구 구분

representationItemsstringrequired

대표 품목

notestringrequired

비고

status"REPORTED" | "SENT" | "ISSUED"required

상태

taxInvoiceTypestringrequired

세금계산서 종류

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

modificationReasonstringoptional

수정사유

originalApprovalNumbernumberoptional

원본 승인번호

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

paymentStatus"PAID" | "UNPAID"optional

결제 상태

isConnectedbooleanrequired

다른 티켓과 연결되어 있는지 여부

connectionCountnumberoptional

연결된 티켓 수

settledWithoutReferencebooleanoptional

세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부

createdAtISO-8601 stringrequired

생성 시각

parentIdnumberoptional

부모 티켓 ID

isSplittedbooleanrequired

분할 티켓 여부

purchaseStatus"APPROVED" | "PURCHASED" | "PURCHASE_ONLY"optional

매입 상태

isSoftwareExpenditurebooleanoptional

소프트웨어 지출 여부

▶merchantCardTransactionMerchantCardTransactionoptionalexpandable

가맹점 카드 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypeCardTyperequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

installmentMonthnumberrequired

할부개월

transactionTypestringrequired

거래구분

transactAtstringrequired

거래일시

amountnumberrequired

금액

▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable

가맹점 매입 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypestringrequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

transactAtstringrequired

거래일시

purchaseDatestringrequired

매입일

purchaseAmountnumberrequired

매입 금액

totalFeenumberrequired

총 수수료

merchantServiceFeenumberrequired

가맹점 수수료

pointFeenumberrequired

포인트 수수료

etcFeenumberrequired

기타 수수료

paidAmountnumberrequired

지급 금액

expectedPaymentDatestringrequired

지급 예정일

▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable

포스기/CREFIA 정산 상세

idnumberrequired

정산 상세 ID

settlementIdnumberrequired

정산 ID

assetIdnumberrequired

포스기/CREFIA 자산 ID

namestringrequired

항목명

amountnumberrequired

금액

transactionType"IN" | "OUT"required

입출금 방향

▶cashReceiptCashReceiptoptionalexpandable

현금영수증 상세

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

▶manualTransactionManualTransactionoptionalexpandable

수기거래 상세

idnumberrequired

수기거래 ID

currencyCurrencyCoderequired

통화 코드

manualTransactionType"ETC" | "CASH" | "INVOICE"required

수기거래 타입

▶tradeItemsManualTransactionTradeItem[]requiredexpandable

거래 품목

itemNamestringrequired

품목명

quantitynumberrequired

수량

taxAmountnumberrequired

세액

unitPricenumberrequired

단가

hasPurchaseCanceledUsagesbooleanoptional

매입 취소 사용내역 보유 여부

▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable

이커머스 정산 상세

▶assetobjectrequiredexpandable

이커머스 스토어 자산

idnumberoptional

자산 ID

organizationstringoptional

조직 (COUPANG, NAVER 등)

nicknamestringoptional

별칭

ecommerceSettlementIdnumberrequired

정산 ID

settlementDatestringrequired

정산일

settlementRationumberrequired

정산 비율

namestringrequired

항목명

amountnumberrequired

금액

typestringrequired

정산 상세 타입

transactionType"IN" | "OUT"required

입출금 방향

isRecommendedbooleanoptional

추천 티켓 여부

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

과세 유형

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/card-usages \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "cardId": 3101,
  "cardUsages": [
    {
      "paymentDate": "2026-04-09T13:20:00+09:00",
      "storeName": "외부몰 정기구독",
      "amount": 55000,
      "paymentStatus": "NORMAL"
    }
  ]
}'

POST /api/public-docs/card-usages

Manual Card Usage Create Response Example

{
  "ok": true,
  "cardId": 3101,
  "requestedCount": 1,
  "message": "카드 사용내역 생성 요청이 처리되었습니다. 생성된 티켓은 tickets API로 조회하세요."
}

POST /api/public-docs/bank-transactions

수기 계좌에 입출금 거래를 일괄 입력해 계좌 거래 티켓을 생성합니다. 먼저 수기 계좌 생성 API 또는 자산 조회 API로 bankAccountId를 확보하세요.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`bankAccountId`에는 그랜터 계좌 자산 ID를 넣습니다. 보통 `bank-accounts-create` 응답의 `id` 또는 `assets` 응답의 계좌 `id`를 사용합니다.

입금/출금 방향은 `transactionType`으로 구분하고 `amount`는 양수로 전달하세요.

생성 API는 처리 ACK를 반환합니다. 생성된 티켓 ID가 필요하면 같은 기간과 `BANK_TRANSACTION_TICKET`으로 `tickets` API를 조회하세요.

bankAccountIdintegerrequired

대상 계좌 자산 ID

bankTransactionsBankTransactionItem[]required

계좌 거래 배열

bankTransactions[].transactAtYYYY-MM-DD | ISO-8601 stringrequired

거래 일시

bankTransactions[].transactionType"IN" | "OUT"required

거래 방향

bankTransactions[].contentstringrequired

적요/거래 내용

bankTransactions[].amountnumberrequired

거래 금액

bankTransactions[].afterTransactionBalancenumberoptional

거래 후 잔액

bankTransactions[].counterpartystringoptional

거래 상대방

bankTransactions[].isErrorbooleanoptional

오류 거래 표시

Response Fields

▶[]Ticketrequiredexpandable

BE `/tickets` 원본 응답 배열의 각 원소

idnumberrequired

티켓 ID

workspaceIdnumberrequired

워크스페이스 ID

contentstringrequired

거래/증빙 내용

amountnumberrequired

거래 금액

transactionType"IN" | "OUT" | "ALL"required

입출금 방향

transactAtISO-8601 stringrequired

거래 일시

modifiedTransactAtISO-8601 stringoptional

수정 거래 일시

descriptionstringrequired

설명

▶expenseCategoryExpenseCategoryoptionalexpandable

계정과목

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

anomalyStatus"NORMAL" | "ABUSE_SUSPECTED" | "ABUSE_CONFIRMED" | "ABUSE_REJECTED"required

이상치 상태

status"NONE" | "CONFIRMED" | "USER_CONFIRMED"required

티켓 상태

tagstringrequired

1차 태그명

tagIdnumber | nullrequired

1차 태그 ID

contactstringrequired

거래처명

contactIdnumber | undefinedrequired

거래처 ID

tagDetailstringrequired

2차 태그명

tagDetailIdnumber | nullrequired

2차 태그 ID

isIncludedbooleanrequired

포함 여부

▶usersUserResponse[]requiredexpandable

연결 유저 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesMessage[]requiredexpandable

메시지 목록

idnumberrequired

메시지 ID

ticketIdnumberrequired

티켓 ID

▶userUserResponserequiredexpandable

작성자

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

userIdnumberrequired

작성자 ID

userNamestringrequired

작성자 이름

contentstringrequired

메시지 내용

typeMessageTyperequired

메시지 타입

createdAtstringrequired

생성 시각

deletedAtstring | nulloptional

삭제 시각

messageCountnumberrequired

메시지 수

▶attachmentsAttachment[]requiredexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

ticketIdnumberrequired

티켓 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

attachmentCountnumberrequired

첨부파일 수

ticketTypeTicketTyperequired

조회 대상 티켓 타입

▶cardUsageCardUsageoptionalexpandable

카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶purchaseUsageCardUsageoptionalexpandable

매입 카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶bankTransactionBankTransactionoptionalexpandable

계좌 거래 상세

bankTransactionIdnumberrequired

은행거래 ID

workspaceIdnumberrequired

워크스페이스 ID

transactionType"IN" | "OUT" | "ALL"required

거래 방향

descriptionstringrequired

설명

afterTransactionBalancenumberrequired

거래 후 잔액

originalAfterTransactionBalancenumberoptional

원본 거래 후 잔액

amountnumberrequired

거래 금액

originalAmountnumberoptional

원본 거래 금액

transactAtstringrequired

거래 일시

▶bankAccountTicketAssetrequiredexpandable

계좌 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

counterpartystringoptional

거래 상대방

descriptionTypestringoptional

설명 분류

contentstringoptional

내용

branchstringoptional

지점

▶taxInvoiceTaxInvoiceoptionalexpandable

세금계산서 상세

idnumberrequired

세금계산서 ID

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶issuerobjectrequiredexpandable

발행자

emailstringrequired

이메일

idnumberrequired

유저 ID

isDeletedbooleanrequired

삭제 여부

namestringrequired

이름

▶trusteeTaxInvoiceUserrequiredexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentType"SUMMARY" | "DETAIL"required

내용 타입

transactionType"SELL" | "BUY" | "TRUSTEE"required

거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestringoptional

전송일자

issueDatestringoptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

purposeType"RECEIPT" | "CHARGE"required

영수/청구 구분

representationItemsstringrequired

대표 품목

notestringrequired

비고

status"REPORTED" | "SENT" | "ISSUED"required

상태

taxInvoiceTypestringrequired

세금계산서 종류

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

modificationReasonstringoptional

수정사유

originalApprovalNumbernumberoptional

원본 승인번호

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

paymentStatus"PAID" | "UNPAID"optional

결제 상태

isConnectedbooleanrequired

다른 티켓과 연결되어 있는지 여부

connectionCountnumberoptional

연결된 티켓 수

settledWithoutReferencebooleanoptional

세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부

createdAtISO-8601 stringrequired

생성 시각

parentIdnumberoptional

부모 티켓 ID

isSplittedbooleanrequired

분할 티켓 여부

purchaseStatus"APPROVED" | "PURCHASED" | "PURCHASE_ONLY"optional

매입 상태

isSoftwareExpenditurebooleanoptional

소프트웨어 지출 여부

▶merchantCardTransactionMerchantCardTransactionoptionalexpandable

가맹점 카드 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypeCardTyperequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

installmentMonthnumberrequired

할부개월

transactionTypestringrequired

거래구분

transactAtstringrequired

거래일시

amountnumberrequired

금액

▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable

가맹점 매입 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypestringrequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

transactAtstringrequired

거래일시

purchaseDatestringrequired

매입일

purchaseAmountnumberrequired

매입 금액

totalFeenumberrequired

총 수수료

merchantServiceFeenumberrequired

가맹점 수수료

pointFeenumberrequired

포인트 수수료

etcFeenumberrequired

기타 수수료

paidAmountnumberrequired

지급 금액

expectedPaymentDatestringrequired

지급 예정일

▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable

포스기/CREFIA 정산 상세

idnumberrequired

정산 상세 ID

settlementIdnumberrequired

정산 ID

assetIdnumberrequired

포스기/CREFIA 자산 ID

namestringrequired

항목명

amountnumberrequired

금액

transactionType"IN" | "OUT"required

입출금 방향

▶cashReceiptCashReceiptoptionalexpandable

현금영수증 상세

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

▶manualTransactionManualTransactionoptionalexpandable

수기거래 상세

idnumberrequired

수기거래 ID

currencyCurrencyCoderequired

통화 코드

manualTransactionType"ETC" | "CASH" | "INVOICE"required

수기거래 타입

▶tradeItemsManualTransactionTradeItem[]requiredexpandable

거래 품목

itemNamestringrequired

품목명

quantitynumberrequired

수량

taxAmountnumberrequired

세액

unitPricenumberrequired

단가

hasPurchaseCanceledUsagesbooleanoptional

매입 취소 사용내역 보유 여부

▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable

이커머스 정산 상세

▶assetobjectrequiredexpandable

이커머스 스토어 자산

idnumberoptional

자산 ID

organizationstringoptional

조직 (COUPANG, NAVER 등)

nicknamestringoptional

별칭

ecommerceSettlementIdnumberrequired

정산 ID

settlementDatestringrequired

정산일

settlementRationumberrequired

정산 비율

namestringrequired

항목명

amountnumberrequired

금액

typestringrequired

정산 상세 타입

transactionType"IN" | "OUT"required

입출금 방향

isRecommendedbooleanoptional

추천 티켓 여부

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

과세 유형

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/bank-transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "bankAccountId": 4201,
  "bankTransactions": [
    {
      "transactAt": "2026-04-09T09:30:00+09:00",
      "transactionType": "IN",
      "content": "외부 ERP 매출 입금",
      "amount": 110000,
      "afterTransactionBalance": 1110000,
      "counterparty": "샘플 거래처"
    }
  ]
}'

POST /api/public-docs/bank-transactions

Manual Bank Transaction Create Response Example

{
  "ok": true,
  "bankAccountId": 4201,
  "requestedCount": 1,
  "message": "계좌 거래내역 생성 요청이 처리되었습니다. 생성된 티켓은 tickets API로 조회하세요."
}

POST /api/public-docs/manual-transactions

세금계산서를 발행하지 않는 매출·매입을 수기관리 전표로 일괄 생성합니다. 거래처 문자열 추정 대신 contactId로 정확히 귀속할 수 있습니다.

Request Fields

`manualTransactions` 배열로 한 번에 최대 100건까지 생성할 수 있습니다.

`contactId`는 필수이며 적요 문자열과 무관하게 해당 거래처로 지정됩니다.

`currency`는 생략 시 KRW, `description`은 생략 시 빈 문자열, `tradeItems`는 생략 시 빈 배열로 처리됩니다.

현재 backend 계약에 없는 `accountId`, `tradeItems[].supplyValue` 같은 필드는 조용히 무시하지 않고 400으로 거부합니다.

`Idempotency-Key` header는 optional입니다. 재시도 중복 방지가 필요하면 호출 단위로 고정된 값을 직접 넣으세요.

응답의 `tickets`와 `ticketIds`는 backend가 생성 티켓을 응답한 경우에만 채워집니다. 현재 backend Swagger는 생성 응답 body를 보장하지 않으므로 빈 배열일 수 있습니다.

manualTransactionsManualTransaction[]required

생성할 수기관리 전표 배열. 최대 100건

manualTransactions[].contactIdintegerrequired

거래처 ID

manualTransactions[].transactionType"IN" | "OUT"required

매출/매입 방향

manualTransactions[].manualTransactionType"ETC" | "CASH" | "INVOICE"required

수기거래 유형

manualTransactions[].transactAtYYYY-MM-DD | ISO-8601 stringrequired

거래 일시

manualTransactions[].amountnumberrequired

거래 금액

manualTransactions[].contentstringrequired

적요/거래 내용

manualTransactions[].currencystringoptional

통화 코드. 기본 KRW

manualTransactions[].descriptionstringoptional

추가 설명. 기본 빈 문자열

manualTransactions[].expenseCategoryIdintegeroptional

계정과목 ID

manualTransactions[].tagIdintegeroptional

1차 태그 ID

manualTransactions[].tagDetailIdintegeroptional

2차 태그 ID

manualTransactions[].tradeItemsManualTransactionTradeItem[]optional

품목 배열

manualTransactions[].tradeItems[].itemNamestringrequired

품목명

manualTransactions[].tradeItems[].quantitynumberrequired

수량

manualTransactions[].tradeItems[].unitPricenumberrequired

단가

manualTransactions[].tradeItems[].taxAmountnumberrequired

세액

Response Fields

okbooleanrequired

수기관리 전표 생성 요청 성공 여부

requestedCountnumberrequired

생성을 요청한 전표 수

ticketIdsnumber[]required

backend 생성 응답에서 확인된 수기관리 티켓 ID 목록. 응답 body가 없으면 빈 배열

▶ticketsTicket[]requiredexpandable

backend가 생성 티켓을 응답한 경우의 공개 티켓 목록. 응답 body가 없으면 빈 배열

▶[]Ticketrequiredexpandable

BE `/tickets` 원본 응답 배열의 각 원소

idnumberrequired

티켓 ID

workspaceIdnumberrequired

워크스페이스 ID

contentstringrequired

거래/증빙 내용

amountnumberrequired

거래 금액

transactionType"IN" | "OUT" | "ALL"required

입출금 방향

transactAtISO-8601 stringrequired

거래 일시

modifiedTransactAtISO-8601 stringoptional

수정 거래 일시

descriptionstringrequired

설명

▶expenseCategoryExpenseCategoryoptionalexpandable

계정과목

idnumberrequired

계정과목 ID

namestringrequired

계정과목명

subInfostringrequired

부가 정보

descriptionstringrequired

설명

codenumber | stringrequired

코드

type"COMMON" | "CUSTOM"required

카테고리 타입

isHiddenbooleanrequired

숨김 여부

costType"NONE" | "VARIABLE" | "FIXED"required

비용 유형

isFavoritebooleanrequired

즐겨찾기 여부

workspaceIdnumberoptional

워크스페이스 ID

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

기본 과세 유형

anomalyStatus"NORMAL" | "ABUSE_SUSPECTED" | "ABUSE_CONFIRMED" | "ABUSE_REJECTED"required

이상치 상태

status"NONE" | "CONFIRMED" | "USER_CONFIRMED"required

티켓 상태

tagstringrequired

1차 태그명

tagIdnumber | nullrequired

1차 태그 ID

contactstringrequired

거래처명

contactIdnumber | undefinedrequired

거래처 ID

tagDetailstringrequired

2차 태그명

tagDetailIdnumber | nullrequired

2차 태그 ID

isIncludedbooleanrequired

포함 여부

▶usersUserResponse[]requiredexpandable

연결 유저 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

▶messagesMessage[]requiredexpandable

메시지 목록

idnumberrequired

메시지 ID

ticketIdnumberrequired

티켓 ID

▶userUserResponserequiredexpandable

작성자

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

userIdnumberrequired

작성자 ID

userNamestringrequired

작성자 이름

contentstringrequired

메시지 내용

typeMessageTyperequired

메시지 타입

createdAtstringrequired

생성 시각

deletedAtstring | nulloptional

삭제 시각

messageCountnumberrequired

메시지 수

▶attachmentsAttachment[]requiredexpandable

첨부파일 목록

idnumberrequired

첨부파일 ID

ticketIdnumberrequired

티켓 ID

namestringrequired

파일명

uploadedUrlstringrequired

업로드 URL

contentTypestringrequired

MIME 타입

attachmentCountnumberrequired

첨부파일 수

ticketTypeTicketTyperequired

조회 대상 티켓 타입

▶cardUsageCardUsageoptionalexpandable

카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶purchaseUsageCardUsageoptionalexpandable

매입 카드 사용 상세

workspaceIdnumberrequired

워크스페이스 ID

▶cardTicketAssetrequiredexpandable

카드 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

paymentDatestringrequired

결제일

storeNamestringrequired

가맹점명

storeAddressstringrequired

가맹점 주소

amountnumberrequired

사용 금액

canceledAmountnumberrequired

취소 금액

discountedAmountnumberrequired

할인 금액

vatnumberrequired

부가세

installmentMonthnumberrequired

할부 개월

paymentTypestringrequired

결제 방식

paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required

결제 상태

approvalNumbernumberrequired

승인번호

storeCorporateNumbernumberrequired

가맹점 사업자번호

originalAmountnumberrequired

원본 금액

currencystringrequired

통화 코드

exchangeRatenumberoptional

환율

purchaseDatestringoptional

매입일

feeAmountnumberoptional

수수료

isPurchasedbooleanoptional

매입 여부

▶bankTransactionBankTransactionoptionalexpandable

계좌 거래 상세

bankTransactionIdnumberrequired

은행거래 ID

workspaceIdnumberrequired

워크스페이스 ID

transactionType"IN" | "OUT" | "ALL"required

거래 방향

descriptionstringrequired

설명

afterTransactionBalancenumberrequired

거래 후 잔액

originalAfterTransactionBalancenumberoptional

원본 거래 후 잔액

amountnumberrequired

거래 금액

originalAmountnumberoptional

원본 거래 금액

transactAtstringrequired

거래 일시

▶bankAccountTicketAssetrequiredexpandable

계좌 자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

counterpartystringoptional

거래 상대방

descriptionTypestringoptional

설명 분류

contentstringoptional

내용

branchstringoptional

지점

▶taxInvoiceTaxInvoiceoptionalexpandable

세금계산서 상세

idnumberrequired

세금계산서 ID

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶issuerobjectrequiredexpandable

발행자

emailstringrequired

이메일

idnumberrequired

유저 ID

isDeletedbooleanrequired

삭제 여부

namestringrequired

이름

▶trusteeTaxInvoiceUserrequiredexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentType"SUMMARY" | "DETAIL"required

내용 타입

transactionType"SELL" | "BUY" | "TRUSTEE"required

거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestringoptional

전송일자

issueDatestringoptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

purposeType"RECEIPT" | "CHARGE"required

영수/청구 구분

representationItemsstringrequired

대표 품목

notestringrequired

비고

status"REPORTED" | "SENT" | "ISSUED"required

상태

taxInvoiceTypestringrequired

세금계산서 종류

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

modificationReasonstringoptional

수정사유

originalApprovalNumbernumberoptional

원본 승인번호

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

paymentStatus"PAID" | "UNPAID"optional

결제 상태

isConnectedbooleanrequired

다른 티켓과 연결되어 있는지 여부

connectionCountnumberoptional

연결된 티켓 수

settledWithoutReferencebooleanoptional

세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부

createdAtISO-8601 stringrequired

생성 시각

parentIdnumberoptional

부모 티켓 ID

isSplittedbooleanrequired

분할 티켓 여부

purchaseStatus"APPROVED" | "PURCHASED" | "PURCHASE_ONLY"optional

매입 상태

isSoftwareExpenditurebooleanoptional

소프트웨어 지출 여부

▶merchantCardTransactionMerchantCardTransactionoptionalexpandable

가맹점 카드 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypeCardTyperequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

installmentMonthnumberrequired

할부개월

transactionTypestringrequired

거래구분

transactAtstringrequired

거래일시

amountnumberrequired

금액

▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable

가맹점 매입 거래 상세

▶assetTicketAssetrequiredexpandable

자산 정보

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

cardCompanystringrequired

카드사

cardNamestringrequired

카드명

cardTypestringrequired

카드 타입

cardNumberstringrequired

카드번호

approvalNumberstringrequired

승인번호

transactAtstringrequired

거래일시

purchaseDatestringrequired

매입일

purchaseAmountnumberrequired

매입 금액

totalFeenumberrequired

총 수수료

merchantServiceFeenumberrequired

가맹점 수수료

pointFeenumberrequired

포인트 수수료

etcFeenumberrequired

기타 수수료

paidAmountnumberrequired

지급 금액

expectedPaymentDatestringrequired

지급 예정일

▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable

포스기/CREFIA 정산 상세

idnumberrequired

정산 상세 ID

settlementIdnumberrequired

정산 ID

assetIdnumberrequired

포스기/CREFIA 자산 ID

namestringrequired

항목명

amountnumberrequired

금액

transactionType"IN" | "OUT"required

입출금 방향

▶cashReceiptCashReceiptoptionalexpandable

현금영수증 상세

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

▶manualTransactionManualTransactionoptionalexpandable

수기거래 상세

idnumberrequired

수기거래 ID

currencyCurrencyCoderequired

통화 코드

manualTransactionType"ETC" | "CASH" | "INVOICE"required

수기거래 타입

▶tradeItemsManualTransactionTradeItem[]requiredexpandable

거래 품목

itemNamestringrequired

품목명

quantitynumberrequired

수량

taxAmountnumberrequired

세액

unitPricenumberrequired

단가

hasPurchaseCanceledUsagesbooleanoptional

매입 취소 사용내역 보유 여부

▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable

이커머스 정산 상세

▶assetobjectrequiredexpandable

이커머스 스토어 자산

idnumberoptional

자산 ID

organizationstringoptional

조직 (COUPANG, NAVER 등)

nicknamestringoptional

별칭

ecommerceSettlementIdnumberrequired

정산 ID

settlementDatestringrequired

정산일

settlementRationumberrequired

정산 비율

namestringrequired

항목명

amountnumberrequired

금액

typestringrequired

정산 상세 타입

transactionType"IN" | "OUT"required

입출금 방향

isRecommendedbooleanoptional

추천 티켓 여부

taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional

과세 유형

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/manual-transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "manualTransactions": [
    {
      "contactId": 469653,
      "transactionType": "IN",
      "manualTransactionType": "ETC",
      "transactAt": "2026-04-01",
      "amount": 50000,
      "content": "관리비고지서 및 전산이용료(소사푸르지오상가)",
      "tradeItems": [
        {
          "itemName": "관리비고지서 및 전산이용료",
          "quantity": 1,
          "unitPrice": 50000,
          "taxAmount": 0
        }
      ]
    }
  ]
}'

POST /api/public-docs/manual-transactions

Manual Transaction Create Response Example

{
  "ok": true,
  "requestedCount": 1,
  "ticketIds": [23860366],
  "tickets": [
    {
      "id": 23860366,
      "ticketType": "MANUAL_TRANSACTION_TICKET",
      "contactId": 469653,
      "content": "관리비고지서 및 전산이용료(소사푸르지오상가)",
      "manualTransaction": {
        "id": 91001,
        "currency": "KRW",
        "manualTransactionType": "ETC"
      }
    }
  ]
}

DELETE /api/public-docs/manual-transactions

잘못 생성됐거나 중복된 수기관리 전표를 티켓 ID 기준으로 일괄 삭제합니다.

Request Fields

`ticketIds`에는 수기거래 내부 ID가 아니라 수기관리 티켓의 `id`를 넣습니다.

한 번에 최대 100건까지 삭제할 수 있으며 중복 ID는 허용하지 않습니다.

서버가 각 티켓의 워크스페이스, 티켓 타입, 내부 수기거래 ID를 확인한 뒤 삭제하며 연결된 전표는 409로 거부합니다. 먼저 티켓 연결 해제 API로 연결을 제거하세요.

`Idempotency-Key` header는 optional입니다. 안전한 재시도가 필요하면 호출 단위로 고정된 값을 직접 넣으세요.

ticketIdsinteger[]required

삭제할 수기관리 티켓 ID 배열. 최대 100건

Response Fields

okbooleanrequired

수기관리 전표 삭제 성공 여부

deletedTicketIdsnumber[]required

삭제된 수기관리 티켓 ID 목록

deletedManualTransactionIdsnumber[]required

티켓에서 확인해 실제 upstream 삭제에 사용한 내부 수기거래 ID 목록

deletedCountnumberrequired

삭제된 전표 수

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X DELETE https://app.granter.biz/api/public-docs/manual-transactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "ticketIds": [23860366, 23860367]
}'

DELETE /api/public-docs/manual-transactions

Manual Transaction Delete Response Example

{
  "ok": true,
  "deletedTicketIds": [23860366, 23860367],
  "deletedManualTransactionIds": [91001, 91002],
  "deletedCount": 2
}

POST /api/public-docs/tax-invoices

국세청 발행 없이 외부 시스템 기준의 세금계산서 내역을 수기로 입력합니다. 실제 전자세금계산서 발행이 아니라 그랜터 증빙/티켓 데이터 생성용입니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`supplier`, `contractor`는 실제 발행 API와 달리 모두 request body에 직접 전달합니다.

`supplier.registrationNumber`는 워크스페이스에 활성 홈택스 계정으로 등록된 사업자번호와 일치해야 합니다.

`taxAmount`, `totalAmount`, `tradeItems`를 생략하면 `supplyValue`, `taxType`, `reportingDate` 기준으로 단일 품목을 자동 구성합니다.

사업자등록번호는 하이픈 포함 입력도 가능하며 upstream 전달 전 숫자만 남깁니다.

issueTypestringoptional

발행 구분. 기본 정발행

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"optional

과세 유형. 기본 TAX

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"optional

공급받는 자 구분. 기본 BUSINESS

purposeType"RECEIPT" | "CHARGE" | "NONE"optional

영수/청구 구분. 기본 RECEIPT

reportingDateYYYY-MM-DDrequired

작성일자

supplyValuenumberrequired

공급가액

taxAmountnumberoptional

세액. 생략 시 과세 건은 공급가액의 10%

totalAmountnumberoptional

합계금액. 생략 시 공급가액 + 세액

notestringoptional

비고

supplier.registrationNumberstringrequired

공급자 사업자등록번호

supplier.companyNamestringrequired

공급자 상호

supplier.ceoNamestringoptional

공급자 대표자명. 생략 시 companyName 사용

supplier.emailstringoptional

공급자 이메일

contractor.registrationNumberstringrequired

공급받는 자 사업자등록번호

contractor.companyNamestringrequired

공급받는 자 상호

contractor.ceoNamestringoptional

공급받는 자 대표자명. 생략 시 companyName 사용

contractor.emailstringoptional

공급받는 자 이메일

tradeItemsTradeItem[]optional

품목 배열. 생략 시 공급가액 기준 1건 자동 생성

Response Fields

idnumberrequired

세금계산서 ID

issueUuidstringoptional

발행 요청 UUID

▶accountTicketAssetrequiredexpandable

발행에 사용된 홈택스 자산

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶trusteeTaxInvoiceUser | nulloptionalexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentTypestringrequired

내용 타입

transactionTypestringrequired

거래 타입

taxtransactionTypestringrequired

세금계산서 거래 타입

etaxtransactionTypestringrequired

전자세금계산서 거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestring | nulloptional

전송일자

issueDatestring | nulloptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

totalCountnumber | nulloptional

총 건수

cashnumberrequired

현금 금액

checknumberrequired

수표 금액

bankBillnumberrequired

어음 금액

accountReceivablenumber | nulloptional

외상미수금 금액

purposeTypestringrequired

영수/청구 구분

representationItemsstringrequired

대표 품목

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

notestringrequired

비고

statusstringrequired

발행 상태

resultCodenumberoptional

발행 결과 코드

resultMessagestringoptional

발행 결과 메시지

importDeclarationNumberstring | nulloptional

수입신고번호

commStartDatestring | nulloptional

통신 시작일

commEndDatestring | nulloptional

통신 종료일

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

modificationReasonstring | nulloptional

수정사유

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tax-invoices \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "issueType": "정발행",
  "taxType": "TAX",
  "contractorType": "BUSINESS",
  "purposeType": "RECEIPT",
  "reportingDate": "2026-04-09",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "note": "외부 ERP 수기 입력",
  "supplier": {
    "registrationNumber": "123-45-67890",
    "companyName": "그랜터",
    "ceoName": "대표자",
    "email": "accounting@example.com"
  },
  "contractor": {
    "registrationNumber": "111-22-33333",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "email": "buyer@example.com"
  },
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "SaaS 이용료",
      "standards": "ea",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ]
}'

POST /api/public-docs/tax-invoices

Manual Tax Invoice Create Response Example

{
  "id": 90101,
  "approvalNumber": null,
  "issueName": "SaaS 이용료",
  "reportingDate": "2026-04-09",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "purposeType": "RECEIPT",
  "status": "REPORTED",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "그랜터"
  },
  "contractor": {
    "registrationNumber": "1112233333",
    "companyName": "샘플 거래처"
  }
}

POST /api/public-docs/cash-receipts

국세청 발행 없이 외부 시스템 기준의 현금영수증 내역을 수기로 입력합니다. 실제 현금영수증 발행이 아니라 그랜터 증빙/티켓 데이터 생성용입니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 재시도 안전성이 필요하면 직접 넣으세요.

`issuer`와 `buyer`를 직접 전달합니다. 발행 API와 달리 홈택스 계정 ID가 필요하지 않습니다.

`supplyValue`, `vat`를 생략하면 `totalAmount`, `serviceFee`, `taxationType` 기준으로 자동 계산합니다.

사업자등록번호, 휴대폰번호, 주민등록번호 등 식별번호는 하이픈 포함 입력도 가능하며 upstream 전달 전 숫자만 남깁니다.

transactAtYYYY-MM-DD | ISO-8601 stringrequired

거래일시. upstream에는 YYYY-MM-DDTHH:mm:ss로 정규화

contentstringoptional

거래 내용. 기본 현금영수증

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"optional

용도. 기본 EXPENSE_PROOF

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세 형태. 기본 TAXABLE

totalAmountnumberrequired

총금액

supplyValuenumberoptional

공급가액. 생략 시 자동 계산

vatnumberoptional

부가세. 생략 시 자동 계산

serviceFeenumberoptional

봉사료. 기본 0

issuer.registrationNumberstringrequired

발행자 사업자등록번호

issuer.companyNamestringrequired

발행자 상호

buyer.identityNumberstringrequired

구매자 식별번호

buyer.userNamestringoptional

구매자 이름/상호

Response Fields

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/cash-receipts \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "transactAt": "2026-04-09T13:20:00+09:00",
  "content": "외부 ERP 현금 매출",
  "usage": "EXPENSE_PROOF",
  "taxationType": "TAXABLE",
  "totalAmount": 110000,
  "issuer": {
    "registrationNumber": "123-45-67890",
    "companyName": "그랜터"
  },
  "buyer": {
    "identityNumber": "111-22-33333",
    "userName": "샘플 거래처"
  }
}'

POST /api/public-docs/cash-receipts

Manual Cash Receipt Create Response Example

{
  "id": 80101,
  "transactAt": "2026-04-09T13:20:00",
  "usage": "EXPENSE_PROOF",
  "taxationType": "TAXABLE",
  "totalAmount": 110000,
  "supplyValue": 100000,
  "vat": 10000,
  "serviceFee": 0,
  "content": "외부 ERP 현금 매출",
  "issuer": {
    "registrationNumber": "1234567890",
    "companyName": "그랜터"
  },
  "buyer": {
    "identityNumber": "1112233333",
    "userName": "샘플 거래처"
  }
}

POST /api/public-docs/tax-invoices/issue

세금계산서를 즉시발행, 예약발행, 반복발행 형태로 신규 발행합니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 다만 timeout, 네트워크 끊김처럼 같은 발행 요청을 재시도해야 하는 경우에는 클라이언트가 직접 넣어야 중복 발행을 줄일 수 있습니다.

`Idempotency-Key`는 실제 발행 요청을 보내는 순간 생성하고, 같은 payload 재시도에만 같은 값을 재사용하세요. 화면 진입, 세션, 임시저장, 거래처 선택 같은 긴 수명에 묶어 재사용하지 마세요.

payload의 금액, 거래처, 품목, 작성일자, 발행 일정이 바뀌었거나 사용자가 새 세금계산서를 발행하는 경우에는 이전 `Idempotency-Key`를 재사용하지 말고 새 값을 생성하세요.

이미 사용한 `Idempotency-Key`로 다른 payload를 보내면 새 세금계산서가 발행되지 않고 기존 요청의 승인번호/결과가 반환될 수 있으므로, 외부 시스템에서는 payload fingerprint와 키를 함께 관리하는 것을 권장합니다.

`supplier`, `contractor`, `tradeItems`를 포함한 발행 payload를 JSON body로 전달합니다.

AI 또는 외부 시스템은 `issueScheduleType`를 항상 명시하고, `supplier`와 `contractor`에는 `registrationNumber`, `companyName`, 대표자명(`ceoName`)을 넣어야 합니다.

금액 필드(`supplyValue`, `taxAmount`, `totalAmount`, `cash`, `check`, `bankBill`, `accountReceivable`, `tradeItems[].supplyValue`, `tradeItems[].taxAmount`)는 모두 정수(integer)로 전달하세요.

`cash`, `check`, `bankBill`, `accountReceivable`를 전달하면 네 금액의 합이 `totalAmount`와 같아야 합니다. 결제수단을 따로 관리하지 않으면 보통 `accountReceivable`에 `totalAmount`를 넣습니다.

`tradeItems[].taxItemName`은 발행된 세금계산서의 품목란에 그대로 표시됩니다. 내부 테스트명, 검증 문구, 추적용 메모는 `taxItemName`이 아니라 `memo`에 넣으세요.

`note`는 세금계산서 상단 비고란, `tradeItems[].note`는 품목 행 비고란에 표시됩니다. 외부에 보이지 않는 내부 메모는 `memo`를 사용하세요.

`issueScheduleType`이 `RECURRING`이면 `reportingDate`는 `null`, `recurringScheduleOption`은 필수입니다.

수정발행/취소발행은 각각 `tax-invoices-modify-issue`, `tax-invoices-cancel-issue` endpoint를 사용하세요.

`assets` API의 HOME_TAX_ACCOUNT 응답에는 `issueCertificate`가 포함되지 않습니다. 발행용 인증서 미등록 여부는 `assets` 응답의 필드 누락만으로 판단하지 마세요.

issueTypestringrequired

발행 타입. 일반적으로 `정발행`을 사용합니다.

taxTypeenumrequired

과세 유형

▶허용 값

TAX·과세

ZERO_TAX_RATE·영세율

TAX_EXEMPTION·면세

chargeDirectionstringrequired

청구 방향. 일반적으로 `정과금`을 사용합니다.

reportingDateYYYY-MM-DD | nullrequired

작성일자. 반복발행이면 `null`입니다.

issueScheduleTypeenumrequired

발행 스케줄 타입

▶허용 값

IMMEDIATE·즉시발행

SCHEDULED·예약발행

RECURRING·반복발행

recurringScheduleOption.dayOfMonthintegeroptional

반복발행(RECURRING)일 때 필요한 발행 일자 (1~31)

recurringScheduleOption.endDateYYYY-MM-DDoptional

반복발행(RECURRING)일 때 필요한 종료일

purposeTypeenumrequired

영수/청구 구분

▶허용 값

RECEIPT·영수

CHARGE·청구

supplyValueintegerrequired

공급가액

taxAmountintegerrequired

세액

totalAmountintegerrequired

합계금액

cashintegeroptional

현금 금액

checkintegeroptional

수표 금액

bankBillintegeroptional

어음 금액

accountReceivableintegeroptional

외상미수금 금액. 결제수단 금액 합계는 totalAmount와 같아야 합니다.

notestringrequired

세금계산서 상단 비고란에 표시되는 비고

contractorTypeenumrequired

공급받는자 유형

▶허용 값

BUSINESS·사업자

INDIVIDUAL·개인

FOREIGNER·외국인

forceIssuebooleanoptional

강제 발행 여부

writeSpecificationbooleanoptional

명세 작성 여부

memostringrequired

그랜터 내부 메모. 세금계산서 품목/비고에는 표시되지 않습니다.

supplier.registrationNumberstringrequired

공급자 사업자등록번호

supplier.companyNamestringrequired

공급자 회사명

supplier.ceoNamestringrequired

공급자 대표자명

supplier.emailstringoptional

공급자 이메일

supplier.email2stringoptional

공급자 보조 이메일

supplier.telstringoptional

발행 세금계산서 담당자 연락처에 반영되는 공급자 연락처

supplier.phonestringoptional

기존 호환용 연락처 alias. tel 미입력 시 연락처로 사용되며, tel과 함께 보내면 tel이 우선됩니다.

supplier.businessTypesstringoptional

공급자 업태

supplier.businessItemsstringoptional

공급자 종목

supplier.businessPlacestringoptional

공급자 사업장 주소

contractor.registrationNumberstringrequired

공급받는자 사업자등록번호

contractor.companyNamestringrequired

공급받는자 회사명

contractor.ceoNamestringrequired

공급받는자 대표자명

contractor.emailstringoptional

공급받는자 이메일

contractor.email2stringoptional

공급받는자 보조 이메일

contractor.telstringoptional

발행 세금계산서 담당자 연락처에 반영되는 공급받는자 연락처

contractor.phonestringoptional

기존 호환용 연락처 alias. tel 미입력 시 연락처로 사용되며, tel과 함께 보내면 tel이 우선됩니다.

contractor.businessTypesstringoptional

공급받는자 업태

contractor.businessItemsstringoptional

공급받는자 종목

contractor.businessPlacestringoptional

공급받는자 사업장 주소

tradeItems[].purchaseExpiryDateYYYY-MM-DD | nulloptional

공급일자

tradeItems[].taxItemNamestringrequired

세금계산서 품목란에 그대로 표시되는 품목명

tradeItems[].standardsstringrequired

규격

tradeItems[].quantitynumberrequired

수량

tradeItems[].unitPricenumberrequired

단가

tradeItems[].supplyValueintegerrequired

품목 공급가액

tradeItems[].taxAmountintegerrequired

품목 세액

tradeItems[].notestringoptional

품목 행 비고란에 표시되는 비고

Response Fields

idnumberrequired

세금계산서 ID

issueUuidstringoptional

발행 요청 UUID

▶accountTicketAssetrequiredexpandable

발행에 사용된 홈택스 자산

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶trusteeTaxInvoiceUser | nulloptionalexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentTypestringrequired

내용 타입

transactionTypestringrequired

거래 타입

taxtransactionTypestringrequired

세금계산서 거래 타입

etaxtransactionTypestringrequired

전자세금계산서 거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestring | nulloptional

전송일자

issueDatestring | nulloptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

totalCountnumber | nulloptional

총 건수

cashnumberrequired

현금 금액

checknumberrequired

수표 금액

bankBillnumberrequired

어음 금액

accountReceivablenumber | nulloptional

외상미수금 금액

purposeTypestringrequired

영수/청구 구분

representationItemsstringrequired

대표 품목

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

notestringrequired

비고

statusstringrequired

발행 상태

resultCodenumberoptional

발행 결과 코드

resultMessagestringoptional

발행 결과 메시지

importDeclarationNumberstring | nulloptional

수입신고번호

commStartDatestring | nulloptional

통신 시작일

commEndDatestring | nulloptional

통신 종료일

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

modificationReasonstring | nulloptional

수정사유

호출

API KEY

REQUEST EXAMPLE (JSON)

{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-09",
  "issueScheduleType": "IMMEDIATE",
  "purposeType": "CHARGE",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 110000,
  "note": "4월 개발 용역",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ],
  "memo": "Public API 발행 테스트"
}

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tax-invoices/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-09",
  "issueScheduleType": "IMMEDIATE",
  "purposeType": "CHARGE",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 110000,
  "note": "4월 개발 용역",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ],
  "memo": "Public API 발행 테스트"
}'

POST /api/public-docs/tax-invoices/issue

Tax Invoice Issue Response Example

{
  "id": 501,
  "issueUuid": "a5d9d5b7-8bc9-4b4d-9e77-5677f40b8c2a",
  "account": {
    "id": 41,
    "workspaceId": 1,
    "name": "세금계산서 홈택스",
    "nickname": "발행용 홈택스",
    "organization": "HOME_TAX",
    "organizationName": "홈택스",
    "isActive": true,
    "isPossibleDormant": false,
    "isDormant": false,
    "number": "1234567890",
    "owners": [
      {
        "id": 73,
        "name": "소유자 A",
        "email": "owner-a@example.com",
        "isDeleted": false
      }
    ],
    "clientType": "CORPORATE",
    "businessType": "HTX",
    "businessTypeName": "홈택스",
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "address": "서울특별시 강남구 테헤란로 1",
    "contactName": "재무담당자",
    "email": "billing@supplier.example",
    "tel": "0212345678",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "category": "TAX_INVOICE"
  },
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "trustee": null,
  "approvalNumber": "20260409-000001",
  "contentType": "SUMMARY",
  "transactionType": "SELL",
  "taxtransactionType": "SELL",
  "etaxtransactionType": "SELL",
  "issueName": "정발행",
  "reportingDate": "2026-04-09",
  "sendDate": "2026-04-09T08:31:00.000Z",
  "issueDate": "2026-04-09T08:31:02.000Z",
  "supplyValue": 100000,
  "taxAmount": 10000,
  "totalAmount": 110000,
  "totalCount": 1,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 110000,
  "purposeType": "CHARGE",
  "representationItems": "개발 용역",
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": 100000,
      "supplyValue": 100000,
      "taxAmount": 10000,
      "note": ""
    }
  ],
  "note": "4월 개발 용역",
  "status": "ISSUED",
  "resultCode": 1,
  "resultMessage": "SUCCESS",
  "importDeclarationNumber": null,
  "commStartDate": null,
  "commEndDate": null,
  "issueOption": {
    "issueType": "정발행",
    "taxType": "TAX",
    "chargeDirection": "정과금",
    "kwon": 1,
    "ho": 1,
    "contractorType": "BUSINESS",
    "forceIssue": false,
    "writeSpecification": true,
    "closeDownStatus": "ACTIVE",
    "closeDownDate": ""
  },
  "modificationReason": null
}

POST /api/public-docs/tax-invoices/modify-issue

세금계산서를 수정발행합니다. 공급가액 변동이나 기재사항 착오정정처럼 원본 승인번호를 기준으로 정정할 때 사용합니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 같은 수정발행 payload를 재시도할 때만 같은 값을 재사용하고, 정정 내용이 바뀌면 새 값을 생성하세요.

`modificationOption.originalApprovalNumber`에는 정정 대상 원본 승인번호를 넣어야 합니다.

`supplier`와 `contractor`에는 정발행과 동일하게 `registrationNumber`, `companyName`, 대표자명(`ceoName`)이 필요합니다.

금액 필드와 `tradeItems[].supplyValue`, `tradeItems[].taxAmount`는 모두 정수(integer)로 전달하세요.

`tradeItems[].taxItemName`은 발행된 수정세금계산서의 품목란에 그대로 표시됩니다. 내부 추적용 문구는 `memo`를 사용하세요.

`modificationOption.modificationReason`은 현재 Public API에서 `기재사항 착오정정` 또는 `공급가액 변동`만 허용합니다.

`기재사항 착오정정`은 보통 `tax-invoices-cancel-issue`로 원본을 먼저 음수 취소발행한 뒤, 정정된 본문을 이 endpoint로 다시 발행합니다.

modificationOption.modificationReasonenumrequired

수정사유

▶허용 값

기재사항 착오정정·기재사항 착오 정정

공급가액 변동·공급가액 변동

modificationOption.originalApprovalNumberstringrequired

원본 승인번호

reportingDateYYYY-MM-DDrequired

수정세금계산서 작성일자

tradeItems[]arrayrequired

정정 또는 차액 기준 품목 목록. 공급가액 변동은 차액을, 기재사항 착오정정은 정정본 내용을 전달합니다.

supplyValueintegerrequired

공급가액. 차액 수정이면 음수/양수 모두 가능

taxAmountintegerrequired

세액. 차액 수정이면 음수/양수 모두 가능

totalAmountintegerrequired

합계금액. 차액 수정이면 음수/양수 모두 가능

Response Fields

idnumberrequired

세금계산서 ID

issueUuidstringoptional

발행 요청 UUID

▶accountTicketAssetrequiredexpandable

발행에 사용된 홈택스 자산

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶trusteeTaxInvoiceUser | nulloptionalexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentTypestringrequired

내용 타입

transactionTypestringrequired

거래 타입

taxtransactionTypestringrequired

세금계산서 거래 타입

etaxtransactionTypestringrequired

전자세금계산서 거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestring | nulloptional

전송일자

issueDatestring | nulloptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

totalCountnumber | nulloptional

총 건수

cashnumberrequired

현금 금액

checknumberrequired

수표 금액

bankBillnumberrequired

어음 금액

accountReceivablenumber | nulloptional

외상미수금 금액

purposeTypestringrequired

영수/청구 구분

representationItemsstringrequired

대표 품목

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

notestringrequired

비고

statusstringrequired

발행 상태

resultCodenumberoptional

발행 결과 코드

resultMessagestringoptional

발행 결과 메시지

importDeclarationNumberstring | nulloptional

수입신고번호

commStartDatestring | nulloptional

통신 시작일

commEndDatestring | nulloptional

통신 종료일

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

modificationReasonstring | nulloptional

수정사유

호출

API KEY

REQUEST EXAMPLE (JSON)

{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-12",
  "purposeType": "CHARGE",
  "supplyValue": 20000,
  "taxAmount": 2000,
  "totalAmount": 22000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 22000,
  "note": "공급가액 변동 차액분",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "modificationOption": {
    "modificationReason": "공급가액 변동",
    "originalApprovalNumber": "20260409-000001"
  },
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-12",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 0,
      "unitPrice": 20000,
      "supplyValue": 20000,
      "taxAmount": 2000,
      "note": "Difference"
    }
  ],
  "memo": "공급가액 변동 정정"
}

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tax-invoices/modify-issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-12",
  "purposeType": "CHARGE",
  "supplyValue": 20000,
  "taxAmount": 2000,
  "totalAmount": 22000,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 22000,
  "note": "공급가액 변동 차액분",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "modificationOption": {
    "modificationReason": "공급가액 변동",
    "originalApprovalNumber": "20260409-000001"
  },
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-12",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 0,
      "unitPrice": 20000,
      "supplyValue": 20000,
      "taxAmount": 2000,
      "note": "Difference"
    }
  ],
  "memo": "공급가액 변동 정정"
}'

POST /api/public-docs/tax-invoices/modify-issue

Tax Invoice Modify Issue Response Example

{
  "id": 502,
  "issueUuid": "5a0b2f56-60f4-4d59-b5ff-6e70f29c0c11",
  "account": {
    "id": 41,
    "workspaceId": 1,
    "name": "세금계산서 홈택스",
    "nickname": "발행용 홈택스",
    "organization": "HOME_TAX",
    "organizationName": "홈택스",
    "isActive": true,
    "isPossibleDormant": false,
    "isDormant": false,
    "number": "1234567890",
    "owners": [
      {
        "id": 73,
        "name": "소유자 A",
        "email": "owner-a@example.com",
        "isDeleted": false
      }
    ],
    "clientType": "CORPORATE",
    "businessType": "HTX",
    "businessTypeName": "홈택스",
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "address": "서울특별시 강남구 테헤란로 1",
    "contactName": "재무담당자",
    "email": "billing@supplier.example",
    "tel": "0212345678",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "category": "TAX_INVOICE"
  },
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "trustee": null,
  "approvalNumber": "20260412-000003",
  "contentType": "SUMMARY",
  "transactionType": "SELL",
  "taxtransactionType": "SELL",
  "etaxtransactionType": "SELL",
  "issueName": "수정발행",
  "reportingDate": "2026-04-12",
  "sendDate": "2026-04-12T08:30:00.000Z",
  "issueDate": "2026-04-12T08:30:02.000Z",
  "supplyValue": 20000,
  "taxAmount": 2000,
  "totalAmount": 22000,
  "totalCount": 1,
  "cash": 0,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 22000,
  "purposeType": "CHARGE",
  "representationItems": "개발 용역",
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-12",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 0,
      "unitPrice": 20000,
      "supplyValue": 20000,
      "taxAmount": 2000,
      "note": "Difference"
    }
  ],
  "note": "공급가액 변동 차액분",
  "status": "ISSUED",
  "resultCode": 1,
  "resultMessage": "SUCCESS",
  "importDeclarationNumber": null,
  "commStartDate": null,
  "commEndDate": null,
  "issueOption": {
    "issueType": "정발행",
    "taxType": "TAX",
    "chargeDirection": "정과금",
    "kwon": 1,
    "ho": 1,
    "contractorType": "BUSINESS",
    "forceIssue": false,
    "writeSpecification": true,
    "closeDownStatus": "ACTIVE",
    "closeDownDate": ""
  },
  "modificationReason": "공급가액 변동"
}

POST /api/public-docs/tax-invoices/cancel-issue

세금계산서를 취소발행합니다. 원본 승인번호를 기준으로 음수 금액의 수정세금계산서를 발행하는 방식입니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 같은 취소발행 payload를 재시도할 때만 같은 값을 재사용하고, 취소 대상 승인번호나 금액이 바뀌면 새 값을 생성하세요.

`modificationOption.originalApprovalNumber`에는 취소 대상 원본 승인번호를 넣어야 합니다.

`supplier`와 `contractor`에는 정발행과 동일하게 `registrationNumber`, `companyName`, 대표자명(`ceoName`)이 필요합니다.

`modificationOption.modificationReason`은 현재 Public API에서 `착오에 의한 이중발급` 또는 `계약의 해제`만 허용합니다.

취소발행은 현재 그랜터에서 발행된 세금계산서만 가능합니다.

취소발행은 `totalAmount`, `supplyValue`, 그리고 각 `tradeItems` 금액 필드가 음수인 정수(integer)여야 합니다.

`tradeItems[].taxItemName`은 발행된 취소 세금계산서의 품목란에 그대로 표시됩니다. 내부 추적용 문구는 `memo`를 사용하세요.

modificationOption.modificationReasonenumrequired

취소 사유

▶허용 값

착오에 의한 이중발급·착오에 의한 이중발급

계약의 해제·계약의 해제

modificationOption.originalApprovalNumberstringrequired

원본 승인번호

reportingDateYYYY-MM-DDrequired

취소발행 작성일자

supplyValueintegerrequired

음수 공급가액

taxAmountintegerrequired

음수 세액

totalAmountintegerrequired

음수 합계금액

tradeItems[]arrayrequired

음수 금액 기준 품목 목록

Response Fields

idnumberrequired

세금계산서 ID

issueUuidstringoptional

발행 요청 UUID

▶accountTicketAssetrequiredexpandable

발행에 사용된 홈택스 자산

idnumberrequired

자산 ID

workspaceIdnumberrequired

워크스페이스 ID

namestringrequired

자산명

nicknamestringrequired

자산 별칭

organizationstringrequired

기관 코드

organizationNamestringrequired

기관명

isActivebooleanrequired

활성 여부

isPossibleDormantbooleanrequired

휴면 가능 여부

isDormantbooleanrequired

휴면 여부

numberstringrequired

자산 번호

▶ownersUserResponse[]requiredexpandable

소유자 목록

idnumberrequired

유저 ID

namestringrequired

유저 이름

emailstringrequired

유저 이메일

isDeletedbooleanrequired

삭제 여부

clientType"PERSONAL" | "CORPORATE" | "ALL"required

고객 유형

businessTypestringrequired

업종 코드

businessTypeNamestringrequired

업종명

userAutoAssignEnabledbooleanoptional

유저 자동 할당 여부

expirationYearstringoptional

카드 만료 연도

expirationMonthstringoptional

카드 만료 월

limitAmountnumberoptional

카드 한도 금액

usedAmountnumberoptional

카드 사용 금액

remainLimitnumberoptional

카드 잔여 한도

isAutoApprovalbooleanoptional

자동 승인 여부

previousCardNumberstringoptional

이전 카드번호

accountBalancenumberoptional

계좌 잔액

originalBalancenumberoptional

원본 잔액

currencyCodestringoptional

통화 코드

startDatestringoptional

조회 시작일

endDatestring | nulloptional

조회 종료일

accountTypestringoptional

계좌 유형

isTransactionVisiblebooleanoptional

거래내역 보유 여부

totalAmountnumberoptional

증권 총액

depositAmountnumberoptional

증권 예수금

foreignDepositAmountobject[]optional

외화예수금 상세 목록

foreignDepositsnumberoptional

외화예수금 합계

totalValuationAmountnumberoptional

총 평가금액

accountNumberstringoptional

계좌 번호

productsProduct[]optional

증권 보유 상품 목록

registrationNumberstringoptional

사업자등록번호

establishNumberstringoptional

개업일자 코드

companyNamestringoptional

회사명

ceoNamestringoptional

대표자명

addressstringoptional

주소

contactNamestringoptional

담당자명

emailstringoptional

담당자 이메일

telstringoptional

연락처

businessTypesstringoptional

업태

businessItemsstringoptional

종목

categorystringoptional

홈택스 카테고리

createdAtstringoptional

생성 시각

updatedAtstringoptional

수정 시각

readCertificateobjectoptional

조회 인증서 정보

issueCertificateobjectoptional

발행 인증서 정보

▶supplierTaxInvoiceUserrequiredexpandable

공급자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶contractorTaxInvoiceUserrequiredexpandable

공급받는자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

▶trusteeTaxInvoiceUser | nulloptionalexpandable

수탁자

registrationNumberstringrequired

사업자등록번호

companyNamestringrequired

회사명

ceoNamestringoptional

대표자명

businessTypesstringrequired

업태

businessItemsstringrequired

종목

businessPlacestringrequired

사업장 주소

emailstringrequired

이메일

email2stringoptional

보조 이메일

establishNumberstringoptional

개업일자 코드

userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional

당사자 유형

taxInvoiceTaxInvoiceoptional

관련 세금계산서

phonestringoptional

휴대전화

telstringoptional

전화번호

approvalNumberstringrequired

승인번호

contentTypestringrequired

내용 타입

transactionTypestringrequired

거래 타입

taxtransactionTypestringrequired

세금계산서 거래 타입

etaxtransactionTypestringrequired

전자세금계산서 거래 타입

issueNamestringrequired

발행명

reportingDatestringrequired

작성일자

sendDatestring | nulloptional

전송일자

issueDatestring | nulloptional

발행일자

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

totalAmountnumberrequired

합계금액

totalCountnumber | nulloptional

총 건수

cashnumberrequired

현금 금액

checknumberrequired

수표 금액

bankBillnumberrequired

어음 금액

accountReceivablenumber | nulloptional

외상미수금 금액

purposeTypestringrequired

영수/청구 구분

representationItemsstringrequired

대표 품목

▶tradeItemsTradeItem[]requiredexpandable

품목 목록

purchaseExpiryDatestringrequired

공급일자

taxItemNamestringrequired

품목명

standardsstringrequired

규격

quantitynumberrequired

수량

unitPricenumberrequired

단가

supplyValuenumberrequired

공급가액

taxAmountnumberrequired

세액

notestringrequired

비고

isIncludedVatbooleanoptional

부가세 포함 여부

notestringrequired

비고

statusstringrequired

발행 상태

resultCodenumberoptional

발행 결과 코드

resultMessagestringoptional

발행 결과 메시지

importDeclarationNumberstring | nulloptional

수입신고번호

commStartDatestring | nulloptional

통신 시작일

commEndDatestring | nulloptional

통신 종료일

▶issueOptionIssueOptionoptionalexpandable

발행 옵션

issueTypestringrequired

발행 타입

taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required

과세 유형

chargeDirectionstringrequired

청구 방향

kwonnumberrequired

권

honumberrequired

호

contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required

공급받는자 유형

forceIssuebooleanrequired

강제 발행 여부

writeSpecificationbooleanrequired

명세 작성 여부

closeDownStatusstringrequired

휴폐업 상태

closeDownDatestringrequired

휴폐업 일자

modificationReasonstring | nulloptional

수정사유

호출

API KEY

REQUEST EXAMPLE (JSON)

{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-09",
  "purposeType": "CHARGE",
  "supplyValue": -100000,
  "taxAmount": -10000,
  "totalAmount": -110000,
  "cash": -110000,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 0,
  "note": "이중발급 취소",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "modificationOption": {
    "modificationReason": "착오에 의한 이중발급",
    "originalApprovalNumber": "20260409-000001"
  },
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": -100000,
      "supplyValue": -100000,
      "taxAmount": -10000,
      "note": ""
    }
  ],
  "memo": "이중발급 취소"
}

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/tax-invoices/cancel-issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "issueType": "정발행",
  "taxType": "TAX",
  "chargeDirection": "정과금",
  "reportingDate": "2026-04-09",
  "purposeType": "CHARGE",
  "supplyValue": -100000,
  "taxAmount": -10000,
  "totalAmount": -110000,
  "cash": -110000,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 0,
  "note": "이중발급 취소",
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "contractorType": "BUSINESS",
  "forceIssue": false,
  "writeSpecification": true,
  "modificationOption": {
    "modificationReason": "착오에 의한 이중발급",
    "originalApprovalNumber": "20260409-000001"
  },
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": -100000,
      "supplyValue": -100000,
      "taxAmount": -10000,
      "note": ""
    }
  ],
  "memo": "이중발급 취소"
}'

POST /api/public-docs/tax-invoices/cancel-issue

Tax Invoice Cancel Issue Response Example

{
  "id": 503,
  "issueUuid": "a20d9192-1234-4f5c-a911-eaa10252f123",
  "account": {
    "id": 41,
    "workspaceId": 1,
    "name": "세금계산서 홈택스",
    "nickname": "발행용 홈택스",
    "organization": "HOME_TAX",
    "organizationName": "홈택스",
    "isActive": true,
    "isPossibleDormant": false,
    "isDormant": false,
    "number": "1234567890",
    "owners": [
      {
        "id": 73,
        "name": "소유자 A",
        "email": "owner-a@example.com",
        "isDeleted": false
      }
    ],
    "clientType": "CORPORATE",
    "businessType": "HTX",
    "businessTypeName": "홈택스",
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "address": "서울특별시 강남구 테헤란로 1",
    "contactName": "재무담당자",
    "email": "billing@supplier.example",
    "tel": "0212345678",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "category": "TAX_INVOICE"
  },
  "supplier": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "ceoName": "대표자 A",
    "businessTypes": "서비스업",
    "businessItems": "소프트웨어 개발",
    "businessPlace": "서울특별시 강남구 테헤란로 1",
    "email": "billing@supplier.example",
    "email2": "",
    "tel": "0212345678"
  },
  "contractor": {
    "registrationNumber": "0987654321",
    "companyName": "샘플 거래처",
    "ceoName": "대표자 B",
    "businessTypes": "도매업",
    "businessItems": "소프트웨어 유통",
    "businessPlace": "서울특별시 서초구 서초대로 10",
    "email": "ap@buyer.example",
    "email2": "",
    "tel": "01012345678"
  },
  "trustee": null,
  "approvalNumber": "20260409-000002",
  "contentType": "SUMMARY",
  "transactionType": "SELL",
  "taxtransactionType": "SELL",
  "etaxtransactionType": "SELL",
  "issueName": "취소발행",
  "reportingDate": "2026-04-09",
  "sendDate": "2026-04-09T08:32:00.000Z",
  "issueDate": "2026-04-09T08:32:02.000Z",
  "supplyValue": -100000,
  "taxAmount": -10000,
  "totalAmount": -110000,
  "totalCount": 1,
  "cash": -110000,
  "check": 0,
  "bankBill": 0,
  "accountReceivable": 0,
  "purposeType": "CHARGE",
  "representationItems": "개발 용역",
  "tradeItems": [
    {
      "purchaseExpiryDate": "2026-04-09",
      "taxItemName": "개발 용역",
      "standards": "건",
      "quantity": 1,
      "unitPrice": -100000,
      "supplyValue": -100000,
      "taxAmount": -10000,
      "note": ""
    }
  ],
  "note": "이중발급 취소",
  "status": "ISSUED",
  "resultCode": 1,
  "resultMessage": "SUCCESS",
  "importDeclarationNumber": null,
  "commStartDate": null,
  "commEndDate": null,
  "issueOption": {
    "issueType": "정발행",
    "taxType": "TAX",
    "chargeDirection": "정과금",
    "kwon": 1,
    "ho": 1,
    "contractorType": "BUSINESS",
    "forceIssue": false,
    "writeSpecification": true,
    "closeDownStatus": "ACTIVE",
    "closeDownDate": ""
  },
  "modificationReason": "착오에 의한 이중발급"
}

POST /api/public-docs/cash-receipts/issue

현금영수증을 발행합니다.

Request Fields

`Idempotency-Key`는 실제 발행 요청을 보내는 순간 생성하고, 같은 payload 재시도에만 같은 값을 재사용하세요. 화면 진입, 세션, 임시저장, 구매자 선택 같은 긴 수명에 묶어 재사용하지 마세요.

payload의 금액, 구매자, 거래 일시, 발행 용도, 과세 형태가 바뀌었거나 사용자가 새 현금영수증을 발행하는 경우에는 이전 `Idempotency-Key`를 재사용하지 말고 새 값을 생성하세요.

이미 사용한 `Idempotency-Key`로 다른 payload를 보내면 새 현금영수증이 발행되지 않고 기존 요청의 승인번호/결과가 반환될 수 있으므로, 외부 시스템에서는 payload fingerprint와 키를 함께 관리하는 것을 권장합니다.

`homeTaxAccountId`는 `assets` API에서 `assetType=HOME_TAX_ACCOUNT`로 조회한 활성 홈택스 자산 ID를 사용합니다.

`totalAmount`, `supplyValue`, `vat`, `serviceFee`는 모두 정수(integer)로 전달하세요.

homeTaxAccountIdintegerrequired

발행에 사용할 홈택스 자산 ID

transactAtISO-8601 stringrequired

거래 일시

contentstringrequired

거래 내용

usageenumrequired

발행 용도

▶허용 값

TAX_DEDUCTION·소득공제

EXPENSE_PROOF·지출증빙

taxationTypeenumrequired

과세 형태

▶허용 값

TAXABLE·과세

NON_TAXABLE·면세

totalAmountintegerrequired

총금액

supplyValueintegerrequired

공급가액

vatintegerrequired

부가세

serviceFeeintegerrequired

봉사료

issuer.registrationNumberstringrequired

발행자 사업자등록번호

issuer.companyNamestringrequired

발행자 회사명

buyer.identityNumberstringrequired

구매자 식별번호

buyer.userNamestringoptional

구매자명

Response Fields

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/cash-receipts/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "homeTaxAccountId": 41,
  "transactAt": "2026-04-09T09:30:00+09:00",
  "content": "오프라인 판매",
  "usage": "EXPENSE_PROOF",
  "taxationType": "TAXABLE",
  "totalAmount": 110000,
  "supplyValue": 100000,
  "vat": 10000,
  "serviceFee": 0,
  "issuer": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자"
  },
  "buyer": {
    "identityNumber": "01012345678",
    "userName": "홍길동"
  }
}'

POST /api/public-docs/cash-receipts/issue

Cash Receipt Issue Response Example

{
  "id": 901,
  "workspaceId": 1,
  "receiptType": "SALES",
  "transactAt": "2026-04-09T09:30:00+09:00",
  "transactDate": "2026-04-09",
  "transactionType": "APPROVAL",
  "taxationType": "TAXABLE",
  "deductionStatus": "공제",
  "usage": "EXPENSE_PROOF",
  "issueType": "SELF",
  "issueStatus": "ISSUED",
  "approvalNumber": "CR-20260409-0001",
  "totalAmount": 110000,
  "supplyValue": 100000,
  "vat": 10000,
  "serviceFee": 0,
  "content": "오프라인 판매",
  "ntsResultCode": "SUCCESS",
  "issuer": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "userId": 101
  },
  "buyer": {
    "identityNumber": "01012345678",
    "userName": "홍길동"
  }
}

POST /api/public-docs/cash-receipts/cancel-issue

현금영수증을 취소발행합니다. 기존 현금영수증 ID를 기준으로 전체취소 또는 부분취소를 처리합니다.

Request Fields

`Idempotency-Key` header는 optional입니다. 같은 취소발행 payload를 재시도할 때만 같은 값을 재사용하고, 취소 대상 현금영수증 ID·취소 사유·부분취소 금액이 바뀌면 새 값을 생성하세요.

`cashReceiptId`에는 취소 대상 현금영수증 ID를 넣습니다. 보통 `tickets` API에서 `ticketType=CASH_RECEIPT_TICKET` 응답의 `cashReceipt.id` 값을 사용합니다.

취소발행은 현재 그랜터에서 발행된 현금영수증만 가능합니다.

`isPartialCancel=true`이면 `totalAmount`, `supplyValue`, `vat`, `serviceFee`를 모두 전달해야 합니다.

취소 금액 필드(`totalAmount`, `supplyValue`, `vat`, `serviceFee`)는 모두 정수(integer)로 전달하세요.

cashReceiptIdintegerrequired

취소 대상 현금영수증 ID

transactAtISO-8601 stringrequired

취소 거래 일시

cancelReasonenumrequired

취소 사유

▶허용 값

TRANSACTION_CANCELED·거래취소

ERROR_ISSUE_CANCELED·오발급 취소

OTHER·기타

contentstringrequired

메모 또는 취소 내용

isPartialCancelbooleanrequired

부분취소 여부

totalAmountintegeroptional

부분취소 총금액

supplyValueintegeroptional

부분취소 공급가액

vatintegeroptional

부분취소 부가세

serviceFeeintegeroptional

부분취소 봉사료

emailsstring[]required

수신 이메일 목록

Response Fields

idnumberrequired

현금영수증 ID

workspaceIdnumberrequired

워크스페이스 ID

receiptType"SALES" | "PURCHASE"required

영수증 구분

transactAtstringrequired

거래 일시

transactDatestringrequired

국세청 승인일자

transactionType"APPROVAL" | "CANCEL"required

거래구분

taxationType"TAXABLE" | "NON_TAXABLE"optional

과세형태

deductionStatusstringoptional

공제여부

usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required

용도구분

issueTypestringoptional

발행구분

issueStatusstringrequired

발행 상태

approvalNumberstringrequired

승인번호

totalAmountnumberrequired

총금액

supplyValuenumberrequired

공급가액

vatnumberrequired

부가세

serviceFeenumberrequired

봉사료

contentstringrequired

거래 내용

ntsResultCodestringoptional

국세청 결과 코드

▶issuerCashReceiptCounterPartyrequiredexpandable

발행자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶buyerCashReceiptCounterPartyrequiredexpandable

구매자

registrationNumberstringoptional

사업자번호

companyNamestringoptional

상호

userIdnumberoptional

유저 ID

identityNumberstringoptional

식별번호

userNamestringoptional

사용자명

emailsstring[]optional

이메일 목록

▶cancelOptionobjectoptionalexpandable

취소 정보

cancelReasonstringrequired

취소 사유

originalApprovalNumberstringrequired

원본 승인번호

originalTransactDatestringrequired

원본 승인일자

originalCashReceiptIdnumberrequired

원본 현금영수증 ID

호출

API KEY

REQUEST EXAMPLE (JSON)

호출 예시

cURL

curl -X POST https://app.granter.biz/api/public-docs/cash-receipts/cancel-issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic <BASE64(API_KEY:)>" \
  -d '{
  "cashReceiptId": 901,
  "transactAt": "2026-04-10T11:15:00+09:00",
  "cancelReason": "TRANSACTION_CANCELED",
  "content": "고객 환불",
  "isPartialCancel": false,
  "emails": ["accounting@example.com"]
}'

POST /api/public-docs/cash-receipts/cancel-issue

Cash Receipt Cancel Issue Response Example

{
  "id": 902,
  "workspaceId": 1,
  "receiptType": "SALES",
  "transactAt": "2026-04-10T11:15:00+09:00",
  "transactDate": "2026-04-10",
  "transactionType": "CANCEL",
  "taxationType": "TAXABLE",
  "deductionStatus": "공제",
  "usage": "EXPENSE_PROOF",
  "issueType": "SELF",
  "issueStatus": "ISSUED",
  "approvalNumber": "CR-20260410-0002",
  "totalAmount": 110000,
  "supplyValue": 100000,
  "vat": 10000,
  "serviceFee": 0,
  "content": "고객 환불",
  "ntsResultCode": "SUCCESS",
  "issuer": {
    "registrationNumber": "1234567890",
    "companyName": "샘플 공급자",
    "userId": 101
  },
  "buyer": {
    "identityNumber": "01012345678",
    "userName": "홍길동"
  },
  "cancelOption": {
    "cancelReason": "TRANSACTION_CANCELED",
    "originalApprovalNumber": "CR-20260409-0001",
    "originalTransactDate": "2026-04-09",
    "originalCashReceiptId": 901
  }
}

Error Responses

401 Unauthorized

Basic Authorization 헤더가 없거나, API key가 유효하지 않은 경우

응답 `code`는 `UNAUTHORIZED`입니다.

400 Bad Request

요청 body 형식/값이 잘못된 경우

티켓 API 유효성 규칙: `ticketType`, `startDate`, `endDate` 필수, 날짜는 `YYYY-MM-DD` 형식, `startDate <= endDate`, ID 필드는 양의 정수

티켓 수정 API 유효성 규칙: `ticketType` 필수, `items`는 1개 이상, `items[].ticketId`는 양의 정수, `updateFields`에 따라 `expenseCategoryId`/`tagId`/`tagDetailId`/`description`/`userIds`가 각각 필요

발행 API 유효성 규칙: 세금계산서 정발행은 양수 금액, 세금계산서 취소발행은 음수 금액, 현금영수증 부분취소는 취소 금액 필수

잔액 API 유효성 규칙: `startDate/endDate`는 함께 전달, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`

자금일보 API 유효성 규칙: `startDate/endDate` 필수, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`, 조회 기간은 최대 31일

급여 API 유효성 규칙: `startDate/endDate` 필수, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`, `employeeId`는 양의 정수

403 Forbidden

API key가 활성화되어 있지만 해당 쓰기 기능을 사용할 권한 또는 플랜 범위가 없는 경우

거래처 생성·수정·삭제, 전자결재 생성, 티켓 수정, 증빙 발행 같은 쓰기 API는 워크스페이스/API 권한에 따라 제한될 수 있습니다.

409 Conflict

현재 리소스 상태와 요청이 충돌하는 경우

수기관리 전표 삭제에서는 연결된 티켓에 `MANUAL_TRANSACTION_CONNECTED`, 여러 티켓이 같은 수기거래를 가리키면 `DUPLICATE_MANUAL_TRANSACTION` code를 반환합니다.

429 Too Many Requests

클라이언트 IP 기준 분당 120 작업 단위 제한을 초과했거나 upstream 인증 확인 요청이 속도 제한에 도달한 경우

`Retry-After` 응답 헤더의 초 단위 대기시간 이후 재시도하세요.

응답 `code`는 `RATE_LIMITED`입니다.

503 Service Unavailable

API key 인증 서버가 일시적으로 응답하지 않거나 연결할 수 없는 경우

잘못된 API key를 의미하는 401과 구분하여 지수 백오프로 재시도하세요.

응답 `code`는 `UPSTREAM_UNAVAILABLE`입니다.

Aggregation Tips

1) 집계 설계의 기본 원칙

- 집계용 리포트를 만들 때는 `tickets`를 원천 이벤트, `balances`를 잔액 시계열로 나눠 보는 편이 가장 안전합니다. 거래 합계와 분류는 `tickets`, 시작/종료 잔액은 `balances` 기준으로 해석하세요.

- 기간 버킷은 보통 `daily`, `monthly`, `quarterly`, `total` 중 하나로 먼저 정하고, 그다음 `category`, `tag`, `user`, `contact`, `asset` 같은 집계 축을 선택해 표를 구성합니다.

- 실무에서는 보통 `기간 -> 자산/티켓 타입 -> isIncluded=true -> 중복 거래 제외 -> 태그/계정과목/거래처` 순서로 필터를 적용한 뒤 집계를 시작하면 결과가 안정적입니다.

- 금액은 `amount` 하나만 보지 말고 `transactionType`, `inAmount`, `outAmount`를 함께 해석하세요. 특히 지출표와 입출금표를 같은 규칙으로 합치려면 방향값을 분리해 두는 편이 좋습니다.

{
  "period": "monthly",
  "filters": {
    "ticketTypes": ["EXPENSE_TICKET", "BANK_TRANSACTION_TICKET"],
    "startDate": "2026-02-01",
    "endDate": "2026-02-28",
    "isIncluded": true
  },
  "groupBy": "expenseCategoryId"
}

2) 예시: 월별 계정과목별 지출내역

- 월별 지출표는 보통 `tickets`와 `categories`를 같이 씁니다. 먼저 카드/계좌/수기 등 보고 싶은 티켓 타입을 모으고, `transactionType=OUT`, `isIncluded=true`인 건만 남깁니다.

- 그다음 `transactAt -> YYYY-MM`으로 월 버킷을 만들고, `expenseCategory.id` 기준으로 묶습니다. 표시명과 고정비/변동비 구분이 필요하면 `categories.id`로 조인해 `name`, `costType`을 붙입니다.

- 비용 리포트는 이렇게 만든 계정과목별 월 금액을 다시 합쳐 `총 소비`, `고정비`, `변동비`, `기타` 같은 상위 지표를 만듭니다. 즉, `월-계정과목` 1차 집계 테이블을 먼저 만들고 그 위에 상위 지표를 2차 계산하는 구조입니다.

- 손익계산서처럼 더 높은 단계의 리포트가 필요하면 `categories.subInfo`를 이용해 `매출`, `매출원가`, `판매관리비`, `영업외수익`, `영업외비용`으로 다시 묶어 `매출총이익`, `영업이익`, `세전이익`을 계산하면 됩니다.

[
  {
    "period": "2026-02",
    "categoryId": 101,
    "categoryName": "식비",
    "costType": "VARIABLE",
    "outAmount": -158000,
    "displayAmount": 158000,
    "count": 9
  },
  {
    "period": "2026-02",
    "categoryId": 205,
    "categoryName": "급여",
    "costType": "FIXED",
    "outAmount": -4200000,
    "displayAmount": 4200000,
    "count": 4
  }
]

3) 예시: 자금일보 구성

- 자금일보는 `잔액 요약`과 `거래 상세`를 분리해서 만드는 편이 안정적입니다. 상단 잔액 표는 `balances`로 전일 잔액과 현재 잔액을 잡고, 같은 기간 `tickets`를 합산해 입금/출금 합계를 붙입니다.

- 화면 구성은 보통 상단에 자산별 `이전잔액 + 입출금 합계 + 현재잔액`을 두고, 하단에는 `계좌 입출금`, `카드 사용`, `세금계산서`, `현금영수증`, `수기관리` 같은 상세 테이블을 분리하는 방식이 읽기 쉽습니다.

- 체크카드 승인과 계좌 출금처럼 중복 가능성이 있는 건은 연결된 계좌 내역을 제외하는 규칙을 함께 두는 편이 좋습니다. 이렇게 해야 대표 거래만 남고 자금 흐름이 과대 집계되지 않습니다.

- 핵심은 `잔액은 balances`, `흐름과 분류는 tickets`로 역할을 나누는 것입니다. 티켓만으로 순유입을 계산할 수는 있지만, 그 값이 자금일보의 기초/기말 잔액과 항상 같지는 않습니다.

{
  "date": "2026-03-08",
  "balances": [
    {
      "assetId": 11,
      "assetName": "국민은행",
      "openingBalance": 12500000,
      "inAmount": 3200000,
      "outAmount": -1850000,
      "closingBalance": 13850000
    }
  ],
  "sections": {
    "bankTransactions": [{ "ticketId": 1, "content": "거래처 입금", "amount": 3200000 }],
    "cardExpenses": [{ "ticketId": 2, "content": "점심 식대", "amount": 12000 }],
    "taxInvoices": [],
    "cashReceipts": [],
    "manualTransactions": []
  }
}

4) 같은 방식으로 확장할 수 있는 집계

- 태그별 분석은 `tagId`, `tagDetailId` 기준으로 같은 집계 패턴을 반복하면 됩니다. 계정과목 집계와 구조는 같고, 그룹 축만 바뀝니다.

- 거래처별 분석은 `contactId`, 담당자별 분석은 `user_ids`를 기준으로 묶습니다. 여러 사용자가 함께 사용한 건은 `amount / user_count`처럼 균등 배분 규칙을 미리 정해 두면 인원별 집계가 흔들리지 않습니다.

- 외부 대시보드는 `원천 티켓 보관 -> 1차 집계 테이블 생성 -> 리포트별 2차 계산` 흐름으로 설계하면 월별 지출표, 자금일보, 태그 리포트 같은 화면을 일관된 규칙으로 확장하기 쉽습니다.