granter API
그랜터 Public Docs API는 자산 연동 현황, 기관 연동 상태, 거래·증빙 데이터, 분류 기준, 잔액 흐름을 외부 시스템과 AI가 함께 이해할 수 있도록 구조화해 제공하는 연동 문서입니다. 발급된 API key와 Basic 인증만으로 권한 범위의 데이터를 안전하게 조회하고, 로그인 기반 기관 연동·재연동을 요청하고, 티켓 데이터 갱신을 요청하고, 티켓의 계정과목·태그·설명·사용 직원과 계좌 거래처를 수정하고, 티켓에 증빙 파일을 첨부하고, 티켓 간 연결내역을 조회하거나 연결을 생성·해제하고, 수기 카드·계좌와 해당 수기 거래, 수기 세금계산서·현금영수증을 입력하고, 인원 초대, 거래처·전자결재·급여 내역 생성, 거래처 담당자 추가·수정·삭제와 세금계산서·현금영수증의 발행, 취소발행, 수정발행, 계약 조회와 계약 입금내역 연결·완료 처리·발급 문서 재전달 같은 작업까지 자동화할 수 있습니다. 터미널 연동이 필요하면 공식 granter CLI로 같은 API key를 설정해 바로 호출할 수 있습니다.
문서 이해를 위한 빠른 가이드
API 활용 팁
[
{ "startDate": "2026-01-01", "endDate": "2026-01-31" },
{ "startDate": "2026-02-01", "endDate": "2026-02-28" },
{ "startDate": "2026-03-01", "endDate": "2026-03-31" }
]granter CLI · Claude Code MCP 연동
그랜터 데이터 구조와 활용 관점
{
"id": 101,
"assetType": "CARD",
"workspaceId": 123,
"organizationName": "신한카드",
"isActive": true
}{
"id": 98765,
"ticketType": "EXPENSE_TICKET",
"workspaceId": 123,
"amount": 12000,
"transactionType": "OUT",
"transactAt": "2026-02-23T10:15:00.000Z",
"content": "점심 식대",
"isIncluded": true
}API 변경 로그
현재 계약 리비전은 2026-10-23.1입니다. 인증 API 응답의 Granter-API-Revision, Granter-API-Changes, Link 헤더에서도 확인할 수 있습니다.
하위호환성 정책: Breaking change 허용
그랜터 Public API는 현재 별도 버전 경로를 운영하지 않으며, 필요한 API 계약 변경에는 breaking change를 허용합니다.
사용자에게 영향을 주는 계약 변경은 이 changelog와 응답의 Granter-API-Revision·Granter-API-Changes 헤더에 기록합니다. 연동 클라이언트는 리비전 변경과 breaking 항목의 migration 안내를 확인해 반영해야 합니다.
2026-10-23.1
2026-10-23tickets-attachments-create-added티켓 첨부 업로드 API(`POST /api/public-docs/tickets/attachments`, `multipart/form-data`)를 추가합니다. `ticketId`·`ticketType`과 파일 1개(4MB까지)를 보내면 티켓에 첨부하고 새 첨부 ID를 돌려줍니다. 같은 이름·같은 내용(SHA-256)의 첨부가 이미 있으면 다시 올리지 않고 기존 첨부를 `duplicate: true`로 돌려줍니다.
적용일 2026-10-23 · 대상 tickets-attachments-create
2026-10-20.1
2026-10-20tax-invoices-modify-issue-return-reason세금계산서 수정발행(`POST /api/public-docs/tax-invoices/modify-issue`)의 `modificationOption.modificationReason`에 `환입`(반품)을 허용합니다. 반품된 금액만큼만 음수로 1장 발행하며, `supplyValue`·`totalAmount`가 음수이고 `tradeItems`에 음수 금액 항목이 있어야 합니다(아니면 400). 기존 사유(`기재사항 착오정정`·`공급가액 변동`)의 동작은 그대로입니다.
적용일 2026-10-20 · 대상 tax-invoices-modify-issue
2026-10-19.1
2026-10-19contracts-create-beta-added[베타] 계약 생성·발급 API(`POST /api/public-docs/contracts/create`)를 추가합니다. 계약과 품목을 만들고 견적서·청구서·거래명세서를 발급한 뒤 지정한 이메일·알림톡으로 전달합니다. 베타 참여 회사에만 열리며(그 밖에는 403 `CONTRACT_CREATE_BETA_NOT_ENABLED`), `Idempotency-Key` header가 필수입니다. 계약서(전자서명)는 아직 만들 수 없습니다.
적용일 2026-10-19 · 대상 contracts-create
contracts-tax-invoices-link-added계약 세금계산서 연결·해제 API(`/api/public-docs/contracts/tax-invoices` POST·DELETE)를 추가합니다. `tax-invoices-issue` 응답의 `id`(원본 세금계산서 ID)로 연결하며, 티켓이 아직 없으면 대기(`pending`)로 받아 두었다가 자동 연결합니다.
적용일 2026-10-19 · 대상 contracts-tax-invoices-link, contracts-tax-invoices-unlink
2026-10-15.1
2026-10-15purchase-usage-fee-included-shinhan`EXPENSE_TICKET` 응답의 `purchaseUsage.isFeeAmountIncluded`를 문서화하고, 신한카드 매입내역을 삼성카드와 같이 `true`로 제공합니다. 신한카드 해외 매입 금액은 카드사가 해외 이용수수료를 이미 합산해 내려주지만 수수료를 분리해 주지 않아 `feeAmount`가 0이고 플래그가 `false`로 나가 "수수료 미포함"으로 읽혔습니다. `isFeeAmountIncluded=true`면 `amount`가 수수료를 포함한 최종 금액이니 `feeAmount`를 다시 더하지 마세요.
적용일 2026-10-15 · 대상 tickets
2026-10-14.1
2026-10-14contact-managers-api-added거래처 담당자 추가·수정·삭제 API(`/api/public-docs/contacts/managers` POST·PUT·DELETE)를 추가합니다. 추가는 거래처를 다시 조회해 새 담당자 ID(`contactManagerId`)를 돌려주고, 하나로 특정하지 못하면 추측하지 않고 `idConfirmed=false`로 알립니다. 수정은 전달한 필드만 바꾸며, 수정·삭제는 다시 조회한 결과(`verified`)를 함께 돌려줍니다.
적용일 2026-10-14 · 대상 contacts-managers-create, contacts-managers-update, contacts-managers-delete
contact-create-managers-added거래처 생성에 선택 필드 `managers`(최대 10명)를 추가합니다. 거래처를 만든 뒤 담당자를 순서대로 추가하고, 응답에 담당자별 결과 `managerResults`와 `managerSummary`를 더합니다. 담당자 추가가 실패해도 거래처 생성은 유지됩니다. `managers`를 보내지 않으면 응답은 기존과 같습니다.
적용일 2026-10-14 · 대상 contacts-create
2026-10-13.1
2026-10-13tax-invoice-issue-negative-amount-allowed세금계산서 정발행이 음수 금액(`supplyValue`·`taxAmount`·`totalAmount`, 결제수단 금액, `tradeItems[]`의 수량·단가·공급가액·세액)을 받습니다. 이전에는 0 미만 값을 400(Invalid request body)으로 거절해 마이너스 세금계산서를 발행할 수 없었습니다.
적용일 2026-10-13 · 대상 tax-invoices-issue
2026-10-06.1
2026-10-06ticket-inclusion-update-added티켓 수정에 `IS_INCLUDED`+`items[].isIncluded`(포함 여부)를 추가합니다. 이중계상·부가세 납부처럼 집계에서 빼야 하는 티켓을 `isIncluded=false`로 제외하고 `true`로 다시 포함할 수 있습니다.
적용일 2026-10-06 · 대상 tickets-update
ticket-status-filters-added티켓 조회에 `isIncluded`(포함 여부)·`isClassified`(계정과목 지정 여부) 조건을 추가합니다. `isClassified=false`로 미분류 티켓만 받을 수 있습니다.
적용일 2026-10-06 · 대상 tickets
ticket-update-source-exposed티켓 응답에 `expenseCategoryUpdateSource`·`isIncludedUpdateSource`(값을 정한 주체)를 내보냅니다. `USER`는 사람이 확정한 값이고 그 밖은 자동 분류입니다.
적용일 2026-10-06 · 대상 tickets, tickets-detail
asset-scrap-history-exposed자산 응답에 `scrapHistory`(`lastRequestedAt`·`lastCompletedAt`·`lastFailedAt`)를 추가해 자산별 마지막 수집 요청·성공·실패 시각을 확인할 수 있게 합니다. 수집 이력이 없으면 `null`입니다.
적용일 2026-10-06 · 대상 assets
2026-10-04.1
2026-10-04ticket-tags-api-added태그(다중 태그, v2) 조회·생성·수정과 태그 그룹 조회 API를 추가합니다. 2026-10-01부터 그랜터는 한 티켓에 태그를 여러 개 붙이는 다중 태그만 사용하며, 단계(1차·2차·…)는 태그 이름의 `/`로 표현합니다(예전 1차/2차 태그는 `1차/2차` 이름으로 이관).
적용일 2026-10-04 · 대상 ticket-tags, ticket-tags-create, ticket-tags-update, ticket-tag-groups
ticket-tags-assignment-added티켓 조회·단건 조회 응답의 `ticketTags`(id·name·ticketTagGroup)를 공개 계약으로 문서화하고, 티켓 조회에 `ticketTagIds` 조건, 티켓 수정에 `TICKET_TAGS`+`ticketTagIds`(태그 전체 교체, 빈 배열은 모두 해제), 수기거래 생성에 `ticketTagIds`를 추가합니다.
적용일 2026-10-04 · 대상 tickets, tickets-detail, tickets-update, manual-transactions-create
legacy-tag-assignment-rejected1차/2차 태그 지정 — 티켓 수정의 `TAG`·`TAG_DETAIL`(`tagId`·`tagDetailId`), 수기거래 생성의 `tagId`·`tagDetailId` — 은 2026-10-03부터 거절됩니다(400). 같은 요청의 다른 변경도 함께 반영되지 않습니다.
적용일 2026-10-03 · 대상 tickets-update, manual-transactions-create
Migration: `ticket-tags` API로 태그 ID를 조회한 뒤, 티켓 수정은 `updateFields`에 `TICKET_TAGS`와 `items[].ticketTagIds`를, 수기거래 생성은 `manualTransactions[].ticketTagIds`를 보내세요. 예전 1차/2차 태그는 `1차/2차` 이름의 태그로 이관돼 있어 이름으로 찾을 수 있습니다.
legacy-tag-api-deprecated1차/2차 태그 API(`tags`, `tags-create`, `tags-update`, `tag-details`, `tag-details-create`, `tag-details-update`)와 티켓의 `tag`·`tagId`·`tagDetail`·`tagDetailId` 필드·조건을 deprecated 로 지정합니다. 이 태그는 2026-10-01 이후 앱에 보이지 않고 갱신되지 않으며, 곧 삭제될 예정입니다.
적용일 2026-10-04 · 대상 tags, tags-create, tags-update, tag-details, tag-details-create, tag-details-update, tickets
Migration: 태그 기준 데이터는 `ticket-tags`·`ticket-tag-groups`로, 티켓의 태그는 `ticketTags`로 읽고, 조건은 `ticketTagIds`를 쓰세요.
2026-10-02.1
2026-10-02ticket-list-overview-all-workspaces티켓 조회 API의 목록 응답이 모든 워크스페이스에서 요약 기반(목록 V2)으로 바뀝니다. 2026-09-30부터 워크스페이스별로 순차 전환하던 것을 전체로 넓힌 것으로, 기존(V1) 목록 계약은 더 이상 반환하지 않습니다. 응답 원소에는 messages·attachments 원문이 없고 commentCount(댓글 수)·attachmentCount(첨부 수)·ticketReferences(연결내역)가 있으며, isConnected·connectionCount는 결재·계약 연결을 세지 않습니다.
적용일 2026-10-02 · 대상 tickets
Migration: 댓글·변경 기록·첨부 원문이 필요하면 목록 원소의 id·ticketType으로 티켓 단건 조회 API(POST /api/public-docs/tickets/detail)를 호출하세요. 개수만 필요하면 commentCount·attachmentCount를, 결재·계약을 포함한 연결 대상은 ticketReferences를 쓰세요.
2026-10-01.1
2026-10-01contracts-api-added업무 > 계약의 계약 목록·상세 조회, 계약 입금내역 연결·해제, 완료 처리·되돌리기, 발급 문서 재전달 API를 추가합니다. 완료 처리는 앱과 같이 계약 결제 상태를 결제 완료로 기록하고, 재전달은 Idempotency-Key header가 필수입니다.
적용일 2026-10-01 · 대상 contracts, contracts-detail, contracts-payment-proofs-link, contracts-payment-proofs-unlink, contracts-complete, contracts-uncomplete, contracts-documents-resend
2026-09-30.1
2026-09-30ticket-detail-added티켓 한 건의 댓글·변경 기록(messages), 첨부파일(attachments) 원문과 연결내역(ticketReferences)을 함께 반환하는 티켓 단건 조회 API(POST /api/public-docs/tickets/detail)를 추가합니다.
적용일 2026-09-30 · 대상 tickets-detail
ticket-list-overview-rollout티켓 조회 API의 목록 응답을 요약 기반(목록 V2)으로 워크스페이스별 순차 전환합니다. 전환된 응답에는 messages·attachments 원문이 없고 commentCount(댓글 수)와 ticketReferences(연결내역)가 추가됩니다. messageCount는 commentCount와 같은 값이고 attachmentCount는 그대로 제공합니다. isConnected·connectionCount는 결재·계약 연결을 세지 않습니다. 전환 여부는 응답 원소에 ticketReferences 필드가 있는지로 구분할 수 있습니다.
적용일 2026-09-30 · 대상 tickets
Migration: 댓글·변경 기록·첨부 원문이 필요하면 목록 원소의 id·ticketType으로 티켓 단건 조회 API(POST /api/public-docs/tickets/detail)를 호출하세요. 개수만 필요하면 commentCount·attachmentCount를, 결재·계약을 포함한 연결 대상은 ticketReferences를 쓰세요.
ticket-list-v1-contract-deprecated티켓 조회 API의 기존(V1) 목록 계약 — 목록 원소의 messages·attachments 원문, 결재·계약 연결을 포함하던 isConnected·connectionCount 기준 — 을 deprecated 로 지정합니다. 모든 워크스페이스가 목록 V2로 전환되면 곧 삭제될 예정입니다.
적용일 2026-09-30 · 대상 tickets
Migration: 지금 V1 목록을 받고 있어도 미리 옮기세요: 개수는 commentCount·attachmentCount, 연결 대상은 ticketReferences를 쓰고, 댓글·변경 기록·첨부 원문은 티켓 단건 조회 API(POST /api/public-docs/tickets/detail)로 받으세요.
2026-09-16.1
2026-09-16woori-personal-withdraw-account-credential-added우리은행(WOORI_BANK) 개인(PERSONAL) ID/PW 연동·재연동에 출금계좌번호(withdrawAccountNo)와 출금계좌 비밀번호(withdrawAccountPassword)를 추가합니다. 우리은행 개인 사이트 개편으로 두 값이 없으면 스크래핑이 실패하며, 해당 요청에서는 두 필드가 모두 필수입니다.
적용일 2026-09-16 · 대상 organizations-login-connect, organizations-login-reconnect
Migration: 우리은행 개인 연동·재연동 요청에 withdrawAccountNo·withdrawAccountPassword를 함께 보내세요. 은행 사이트 계좌인증 목록에 있는 계좌만 사용할 수 있습니다. 다른 기관·우리은행 법인 요청에는 두 필드를 보내지 마세요(400).
2026-08-14.1
2026-08-14bank-ticket-contact-assignment-added계좌 티켓의 거래처를 지정하거나 재지정할 수 있도록 bulk-update-individual에 CONTACT와 contactId를 추가합니다.
적용일 2026-08-14 · 대상 tickets-update
settled-without-reference-added세금계산서 티켓 응답에 실제 티켓 연결 없이 완료 처리된 상태를 나타내는 settledWithoutReference를 추가합니다.
적용일 2026-08-14 · 대상 tickets
2026-08-05.1
2026-08-05ticket-date-window-expandedtickets 조회가 31일 초과 범위를 월 단위로 안전하게 분할·병합하며, 한 요청에서 최대 366일까지 지원합니다.
적용일 2026-08-05 · 대상 tickets
ticket-references-bulk-create-added한 요청에서 최대 25개의 티켓 연결을 생성하고 항목별 성공·실패 결과를 반환하는 bulk API를 추가합니다.
적용일 2026-08-05 · 대상 ticket-references-create-bulk
tax-invoice-complete-without-reference-added미연결 세금계산서를 일괄 완료 처리하거나 완료 전 상태로 되돌리는 API를 추가합니다. 연결된 티켓은 안전하게 거부합니다.
적용일 2026-08-05 · 대상 tickets-complete-without-reference, tickets-uncomplete-without-reference
validation-error-details-preservedbackend가 제공한 details, errors, fieldErrors 검증 상세를 Public API 오류 응답의 details로 보존합니다.
적용일 2026-08-05 · 대상 모든 Public API
2026-07-29.1
2026-07-29contract-change-notices-added모든 인증 Public API 응답에 현재 계약 리비전, 관련 변경 ID, 변경 로그 링크를 응답 헤더로 제공합니다.
적용일 2026-07-29 · 대상 모든 Public API
rate-limit-status-correctedPublic API 앞단 또는 인증 확인 단계의 속도 제한을 401이 아닌 429로 분류하고 Retry-After를 제공합니다.
적용일 2026-07-29 · 대상 모든 Public API
Migration: 401은 API key 오류로만 처리하고, 429는 Retry-After 이후 동일 요청을 재시도하도록 클라이언트 분기를 수정하세요.
auth-outage-status-correctedAPI key 인증 서버의 일시적 장애를 잘못된 key와 구분하여 401이 아닌 503으로 응답합니다.
적용일 2026-07-29 · 대상 모든 Public API
Migration: 401은 API key를 점검하고, 503은 일시적 장애로 분류하여 지수 백오프로 재시도하세요.
nickname-canonicalized응답에 함께 존재하던 nickName과 nickname을 표준 필드 nickname 하나로 통일합니다.
적용일 2026-07-29 · 대상 모든 Public API
Migration: 응답 모델과 필드 접근을 nickname으로 통일하세요.
ticket-connection-summary-added티켓 응답에 isConnected와 connectionCount 연결 요약을 제공합니다.
적용일 2026-07-29 · 대상 tickets
manual-transactions-create-added거래처 ID를 포함한 수기관리 전표 다건 생성 API와 안정적인 처리 확인 응답을 추가합니다. upstream이 생성 티켓을 반환하지 않으면 ticketIds와 tickets는 빈 배열입니다.
적용일 2026-07-29 · 대상 manual-transactions-create
Migration: 생성 성공 여부는 ok와 requestedCount로 확인하고, ticketIds가 항상 채워진다고 가정하지 마세요.
manual-transactions-delete-added수기관리 티켓 ID를 내부 수기거래 ID로 안전하게 변환하고 연결 상태를 확인한 뒤 삭제하는 API를 추가합니다.
적용일 2026-07-29 · 대상 manual-transactions-delete
POST /api/public-docs/tickets
카드, 계좌, 세금계산서, 현금영수증 등 실제 거래·증빙 데이터를 조회합니다.
Request Fields
tickets 기간 조회는 한 요청에서 최대 366일까지 지원합니다. 31일 초과 범위는 서버가 달력월 단위로 나눠 조회하고 티켓 타입과 ID 기준으로 중복 제거해 합칩니다. 조회 기간과 관계없이 결과는 거래일시 내림차순으로 정렬합니다.
목록 응답은 모든 워크스페이스에서 요약 기반(목록 V2)입니다(2026-10-02~). 각 원소에는 `ticketReferences`(연결내역)와 `commentCount`(댓글 수)·`attachmentCount`(첨부 수)가 있고, `messages`·`attachments` 원문은 없습니다. 원문이 필요하면 티켓 단건 조회 API(`POST /api/public-docs/tickets/detail`)를 쓰세요. `isConnected`·`connectionCount`는 결재·계약 연결을 세지 않습니다.
태그는 각 원소의 `ticketTags`(다중 태그 — `id`·`name`·`ticketTagGroup`)로 읽습니다. 한 티켓에 여러 개 붙을 수 있고, 특정 태그가 붙은 티켓만 받으려면 `ticketTagIds`를 보내세요. 레거시 `tag`·`tagId`·`tagDetail`·`tagDetailId`는 2026-10-01 이후 갱신되지 않는 deprecated 필드로 곧 삭제될 예정입니다.
`MERCHANT_CARD_TRANSACTION_TICKET`은 포스기 카드 승인·매출전표 단위 조회용입니다. 승인번호, 카드사, 거래금액 같은 원거래 정보를 확인할 때 사용하세요.
`MERCHANT_CARD_SETTLEMENT_DETAIL_TICKET`은 포스기/CREFIA 정산 항목 단위 조회용입니다. `POS-매입금액`, `POS-가맹점수수료`, `POS-포인트수수료`, `POS-기타수수료`처럼 수수료를 포함한 정산 구성 항목을 확인할 때 사용하세요.
`EXPENSE_TICKET`의 `purchaseUsage`(매입내역) 금액은 카드사에 따라 해외 이용수수료가 이미 합산되어 내려옵니다. `purchaseUsage.isFeeAmountIncluded`가 `true`(삼성·신한카드)면 `amount`가 수수료를 포함한 최종 금액이고 `feeAmount`는 0이므로 수수료를 다시 더하지 마세요. `false`면 `amount`에 `feeAmount`를 더한 값이 실제 청구 금액입니다. `cardUsage`(승인내역) 금액에는 수수료가 포함되지 않습니다.
조회 대상 티켓 타입. 아래 TicketType 상세 목록을 참고하세요.
▶TicketType 상세(기본 접힘)
조회 시작일
조회 종료일
거래처 ID
거래처 검색 옵션
계정과목 ID
계정과목 검색 옵션
태그 ID 목록(`ticket-tags` API 의 id). 이 태그 중 하나라도 붙은 티켓만 반환합니다. 최대 100개
(deprecated) 2차 태그 ID — 2026-10-01 이후 갱신되지 않는 값으로 거릅니다. `ticketTagIds`를 쓰세요
(deprecated) 2차 태그 검색 옵션
(deprecated) 1차 태그 ID — 2026-10-01 이후 갱신되지 않는 값으로 거릅니다. `ticketTagIds`를 쓰세요
자산 ID
포함 여부 조건. `false`면 지출 제외된 티켓만, `true`면 포함된 티켓만 반환합니다
분류 상태 조건. `false`면 계정과목이 없는(미분류) 티켓만, `true`면 계정과목이 지정된 티켓만 반환합니다
Response Fields
▶[]TicketrequiredexpandableBE `/tickets` 원본 응답 배열의 각 원소
티켓 ID
워크스페이스 ID
거래/증빙 내용
거래 금액
입출금 방향
거래 일시
수정 거래 일시
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
이상치 상태
티켓 상태
▶ticketTagsTicketTag[]optionalexpandable티켓에 붙은 태그(다중 태그) 목록. 목록 V2·단건 조회 응답에 있습니다
태그 ID (`ticket-tags` 의 id)
태그 이름
▶ticketTagGroupTicketTagGroup | nullrequiredexpandable태그 그룹. 그룹이 없으면 null
태그 그룹 ID
태그 그룹 이름
(deprecated) 1차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 1차 태그 ID
거래처명
거래처 ID
(deprecated) 2차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 2차 태그 ID
포함 여부
계정과목을 지정한 주체. `USER`는 사람이 확정한 값, 그 밖(`AI_INFERENCE`·`LLM_INFERENCE`·`PATTERN_CLASSIFICATION`·`CACHE_INFERENCE`·`PAYMENT_PROOF` 등)은 자동 분류입니다
포함 여부를 정한 주체. 값의 의미는 `expenseCategoryUpdateSource`와 같습니다
▶usersUserResponse[]requiredexpandable연결 유저 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesMessage[]optionalexpandable댓글·변경 기록 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답(ticketReferences가 있는 응답)에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
메시지 ID
티켓 ID
▶userUserResponserequiredexpandable작성자
유저 ID
유저 이름
유저 이메일
삭제 여부
작성자 ID
작성자 이름
메시지 내용
메시지 타입
생성 시각
삭제 시각
댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서는 commentCount와 같은 값입니다.
▶attachmentsAttachment[]optionalexpandable첨부파일 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
첨부파일 ID
티켓 ID
파일명
업로드 URL
MIME 타입
첨부파일 수
삭제되지 않은 댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
은행거래 ID
워크스페이스 ID
거래 방향
설명
거래 후 잔액
원본 거래 후 잔액
거래 금액
원본 거래 금액
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
거래 상대방
설명 분류
내용
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶issuerobjectrequiredexpandable발행자
이메일
유저 ID
삭제 여부
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
영수/청구 구분
대표 품목
비고
상태
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
수정사유
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
결제 상태
다른 거래·증빙과 연결되어 있는지 여부. 목록 V2 응답과 티켓 단건 조회 API는 결재·계약 연결을 세지 않습니다.
연결된 거래·증빙 수. isConnected와 같은 기준으로 셉니다.
▶ticketReferencesTicketReference[]optionalexpandable연결내역(결재·계약 연결 포함). 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
연결 상대 ID
연결 상대 타입(TicketType 또는 WORKFLOW·CONTRACT·PG_SETTLEMENT 같은 연결 대상 타입)
연결 목적(예: TAX_INVOICE_PAYMENT_MANAGEMENT, DEDUPLICATE_CHECK_CARD_USAGE)
세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부
생성 시각
부모 티켓 ID
분할 티켓 여부
매입 상태
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
할부개월
거래구분
거래일시
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
거래일시
매입일
매입 금액
총 수수료
가맹점 수수료
포인트 수수료
기타 수수료
지급 금액
지급 예정일
▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable포스기/CREFIA 정산 상세
정산 상세 ID
정산 ID
포스기/CREFIA 자산 ID
항목명
금액
입출금 방향
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
수기거래 ID
통화 코드
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
품목명
수량
세액
단가
공급가액
단가의 부가세 포함 여부
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
자산 ID
조직 (COUPANG, NAVER 등)
별칭
정산 ID
정산일
정산 비율
항목명
금액
정산 상세 타입
입출금 방향
추천 티켓 여부
과세 유형
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"
}'[
{
"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,
"ticketTags": [
{
"id": 31,
"name": "프로젝트 A/외주",
"ticketTagGroup": { "id": 4, "name": "프로젝트" }
}
],
"messageCount": 1,
"commentCount": 1,
"attachmentCount": 1,
"isConnected": true,
"connectionCount": 1,
"ticketReferences": [
{
"targetId": 118823,
"targetType": "BANK_TRANSACTION_TICKET",
"purpose": "DEDUPLICATE_CHECK_CARD_USAGE"
},
{
"targetId": 5521,
"targetType": "WORKFLOW",
"purpose": "WORKFLOW_PAYMENT_MANAGEMENT"
}
],
"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,
"isFeeAmountIncluded": false
},
"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/detail
티켓 한 건의 상세를 조회합니다. 댓글·변경 기록(messages), 첨부파일(attachments) 원문과 연결내역(ticketReferences)을 함께 반환합니다.
Request Fields
티켓 조회 API(`tickets`)로 받은 티켓의 `id`와 `ticketType`을 그대로 넣어 호출하세요.
목록 V2 응답에는 `messages`·`attachments` 원문이 없습니다. 원문이 필요한 티켓만 이 API로 받으세요. 개수만 필요하면 목록의 `commentCount`·`attachmentCount`를 쓰세요.
`isConnected`·`connectionCount`는 결재·계약 연결을 세지 않습니다. 결재·계약을 포함한 전체 연결 대상은 `ticketReferences`에서 확인하세요.
API key가 연결된 워크스페이스의 티켓이 아니면 404를 반환합니다.
응답의 `contactId`는 티켓에 지정된 거래처 ID입니다. 거래처 정보와 담당자(`managers[]`)는 이 ID로 `contacts` 응답에서 찾으세요. 거래처가 지정되지 않은 티켓은 `contactId`가 비어 있습니다.
조회할 티켓 ID(목록 응답의 id)
조회할 티켓 타입. 티켓 조회 API와 같은 TicketType을 씁니다.
Response Fields
티켓 ID
워크스페이스 ID
거래/증빙 내용
거래 금액
입출금 방향
거래 일시
수정 거래 일시
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
이상치 상태
티켓 상태
▶ticketTagsTicketTag[]optionalexpandable티켓에 붙은 태그(다중 태그) 목록. 목록 V2·단건 조회 응답에 있습니다
태그 ID (`ticket-tags` 의 id)
태그 이름
▶ticketTagGroupTicketTagGroup | nullrequiredexpandable태그 그룹. 그룹이 없으면 null
태그 그룹 ID
태그 그룹 이름
(deprecated) 1차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 1차 태그 ID
거래처명
거래처 ID
(deprecated) 2차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 2차 태그 ID
포함 여부
계정과목을 지정한 주체. `USER`는 사람이 확정한 값, 그 밖(`AI_INFERENCE`·`LLM_INFERENCE`·`PATTERN_CLASSIFICATION`·`CACHE_INFERENCE`·`PAYMENT_PROOF` 등)은 자동 분류입니다
포함 여부를 정한 주체. 값의 의미는 `expenseCategoryUpdateSource`와 같습니다
▶usersUserResponse[]requiredexpandable연결 유저 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesMessage[]optionalexpandable댓글·변경 기록 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답(ticketReferences가 있는 응답)에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
메시지 ID
티켓 ID
▶userUserResponserequiredexpandable작성자
유저 ID
유저 이름
유저 이메일
삭제 여부
작성자 ID
작성자 이름
메시지 내용
메시지 타입
생성 시각
삭제 시각
댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서는 commentCount와 같은 값입니다.
▶attachmentsAttachment[]optionalexpandable첨부파일 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
첨부파일 ID
티켓 ID
파일명
업로드 URL
MIME 타입
첨부파일 수
삭제되지 않은 댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
은행거래 ID
워크스페이스 ID
거래 방향
설명
거래 후 잔액
원본 거래 후 잔액
거래 금액
원본 거래 금액
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
거래 상대방
설명 분류
내용
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶issuerobjectrequiredexpandable발행자
이메일
유저 ID
삭제 여부
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
영수/청구 구분
대표 품목
비고
상태
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
수정사유
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
결제 상태
다른 거래·증빙과 연결되어 있는지 여부. 목록 V2 응답과 티켓 단건 조회 API는 결재·계약 연결을 세지 않습니다.
연결된 거래·증빙 수. isConnected와 같은 기준으로 셉니다.
▶ticketReferencesTicketReference[]optionalexpandable연결내역(결재·계약 연결 포함). 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
연결 상대 ID
연결 상대 타입(TicketType 또는 WORKFLOW·CONTRACT·PG_SETTLEMENT 같은 연결 대상 타입)
연결 목적(예: TAX_INVOICE_PAYMENT_MANAGEMENT, DEDUPLICATE_CHECK_CARD_USAGE)
세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부
생성 시각
부모 티켓 ID
분할 티켓 여부
매입 상태
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
할부개월
거래구분
거래일시
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
거래일시
매입일
매입 금액
총 수수료
가맹점 수수료
포인트 수수료
기타 수수료
지급 금액
지급 예정일
▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable포스기/CREFIA 정산 상세
정산 상세 ID
정산 ID
포스기/CREFIA 자산 ID
항목명
금액
입출금 방향
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
수기거래 ID
통화 코드
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
품목명
수량
세액
단가
공급가액
단가의 부가세 포함 여부
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
자산 ID
조직 (COUPANG, NAVER 등)
별칭
정산 ID
정산일
정산 비율
항목명
금액
정산 상세 타입
입출금 방향
추천 티켓 여부
과세 유형
curl -X POST https://app.granter.biz/api/public-docs/tickets/detail \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"ticketId": 49176,
"ticketType": "EXPENSE_TICKET"
}'{
"id": 49176,
"ticketType": "EXPENSE_TICKET",
"workspaceId": 1,
"description": "",
"content": "GLOBAL SOFTWARE INC.",
"amount": 14493,
"transactionType": "OUT",
"transactAt": "2026-02-28T17:04:34",
"status": "CONFIRMED",
"isIncluded": true,
"users": [
{
"id": 73,
"name": "담당자 A",
"email": "user-a@example.com",
"isDeleted": false
}
],
"messages": [
{
"id": 16100,
"ticketId": 49176,
"user": {
"id": 4,
"name": "운영자 A",
"email": "operator@example.com",
"isDeleted": false
},
"userId": 4,
"userName": "운영자 A",
"content": "출장 숙박비 영수증을 첨부했습니다.",
"type": "COMMON_MESSAGE",
"createdAt": "2026-03-01T21:55:02.113201",
"deletedAt": null,
"isDeleted": false
},
{
"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,
"commentCount": 1,
"attachments": [
{
"id": 8812,
"ticketId": 49176,
"name": "receipt.jpg",
"uploadedUrl": "https://files.example.com/receipt.jpg",
"contentType": "image/jpeg"
}
],
"attachmentCount": 1,
"isConnected": true,
"connectionCount": 1,
"ticketReferences": [
{
"targetId": 118823,
"targetType": "BANK_TRANSACTION_TICKET",
"purpose": "DEDUPLICATE_CHECK_CARD_USAGE"
},
{
"targetId": 5521,
"targetType": "WORKFLOW",
"purpose": "WORKFLOW_PAYMENT_MANAGEMENT"
}
],
"createdAt": "2026-02-28T19:50:38.773108"
}POST /api/public-docs/tickets/bulk-update-individual
티켓의 계정과목, 태그(다중 태그), 설명, 사용 직원과 계좌 티켓의 거래처를 단건 또는 묶음으로 수정합니다.
Request Fields
`ticketType`이 같은 티켓만 한 요청에 묶어 보내세요. 단건 수정도 `items` 배열에 1개만 넣으면 됩니다.
계정과목/태그 ID는 먼저 `categories`, `ticket-tags` API로 조회한 뒤 사용하세요.
`TICKET_TAGS`는 티켓의 태그를 `ticketTagIds` 전체로 교체합니다. 보내지 않은 기존 태그는 떼어지고, 빈 배열이면 모든 태그를 해제합니다. 태그를 하나만 더하려면 티켓 조회 응답의 `ticketTags[].id`에 새 ID를 더해 보내세요.
사용 직원 ID는 먼저 `people` 또는 `user-profiles` API로 조회하세요.
계좌 티켓의 거래처를 지정하거나 재지정하려면 `ticketType=BANK_TRANSACTION_TICKET`, `updateFields=["CONTACT"]`, `contactId`를 전달하세요. 거래처 ID는 먼저 `contacts` API로 조회하세요.
`updateFields`에는 현재 `EXPENSE_CATEGORY`, `TICKET_TAGS`, `DESCRIPTION`, `USERS`, `CONTACT`, `IS_INCLUDED`를 사용할 수 있습니다. `CONTACT`는 계좌 티켓에만 지원합니다. `TAG`·`TAG_DETAIL`은 deprecated 로, 보내면 400(`TICKET_TAGS`로 옮기라는 안내)을 돌려줍니다.
`DESCRIPTION`는 기존 설명을 새 문자열로 전체 교체합니다.
`USERS`는 기존 사용 직원 목록을 `userIds` 전체로 교체합니다. 모든 사용 직원 배정을 해제하려면 `userIds`에 `null`을 전달하세요.
수정 대상 티켓 타입
▶허용 값
수정할 티켓 목록
수정 대상 티켓 ID
이번 요청에서 적용할 변경 필드 목록
▶허용 값
`updateFields`에 `EXPENSE_CATEGORY`가 포함되면 필수인 계정과목 ID
`updateFields`에 `IS_INCLUDED`가 포함되면 필수인 포함 여부. `false`면 지출에서 제외, `true`면 다시 포함
`updateFields`에 `TICKET_TAGS`가 포함되면 필수인 태그 ID 목록(`ticket-tags` API 의 id). 티켓의 태그를 전체 교체하며 빈 배열이면 모두 해제. 최대 100개
(deprecated) 1차 태그 ID — 지원하지 않습니다. `ticketTagIds`를 쓰세요
(deprecated) 2차 태그 ID — 지원하지 않습니다. `ticketTagIds`를 쓰세요
`updateFields`에 `DESCRIPTION`이 포함되면 필수인 새 설명
`updateFields`에 `USERS`가 포함되면 필수인 사용 직원 ID 목록. 기존 목록을 전체 교체하며 `null`이면 모두 해제
`BANK_TRANSACTION_TICKET`의 `updateFields`에 `CONTACT`가 포함되면 필수인 거래처 ID
Response Fields
수정 요청 처리 성공 여부
이번 요청에 적용된 티켓 타입
요청한 티켓 수정 건수
이번 요청에서 적용한 변경 필드 목록
수정 요청에 포함된 티켓 ID 목록
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"]
}
]
}'{
"ok": true,
"ticketType": "BANK_TRANSACTION_TICKET",
"requestedCount": 1,
"updatedFields": ["CONTACT"],
"ticketIds": [18222986]
}POST /api/public-docs/tickets/attachments
티켓 한 건에 증빙 파일 1개를 첨부로 올립니다. 같은 이름·같은 내용의 첨부가 이미 있으면 올리지 않고 기존 첨부를 돌려주며, 올린 뒤 첨부 목록을 다시 읽어 새 첨부 ID를 확인합니다.
Request Fields
요청은 `multipart/form-data`입니다. `ticketId`·`ticketType` 텍스트 필드와 `file` 파일 필드 1개를 보내세요. 여러 파일은 파일마다 한 번씩 호출하세요.
`ticketId`·`ticketType`은 티켓 조회 API(`tickets`)로 받은 티켓의 `id`와 `ticketType`을 그대로 쓰세요. API key가 연결된 워크스페이스의 티켓이 아니면 404를 반환합니다.
파일 하나는 4MB까지 올릴 수 있습니다. 넘으면 413(`FILE_TOO_LARGE`)을 반환하니 그랜터 웹의 내역 상세 화면에서 올려 주세요. 요청 전체가 4.5MB를 넘으면 함수에 닿기 전에 413으로 거절됩니다.
허용 형식: pdf, jpg, jpeg, png, gif, webp, heic, heif, xls, xlsx, csv, doc, docx, ppt, pptx, hwp, hwpx, txt. 그 밖의 형식은 415(`UNSUPPORTED_FILE_TYPE`)입니다.
같은 이름의 첨부가 이미 있으면 그 파일을 내려받아 내용(SHA-256)을 비교합니다. 같으면 새로 올리지 않고 `duplicate: true`와 기존 첨부를 200으로 돌려줍니다. 이름이 같아도 내용이 다르면 새로 올립니다. 내용을 비교하지 못하면 올리지 않고 502(`DUPLICATE_CHECK_FAILED`)를 반환합니다. 중복이어도 올려야 하면 `allowDuplicate=true`를 함께 보내세요.
새로 올리면 201과 새 첨부(`attachment.id`)를 돌려줍니다. 업로드는 접수됐지만 첨부 목록에서 아직 확인하지 못했으면 202와 `verified: false`를 돌려줍니다. 이때는 티켓 단건 조회(`tickets-detail`)로 확인하세요. 같은 파일을 다시 보내도 중복으로 올라가지 않습니다.
티켓 하나에는 첨부를 10개까지 올릴 수 있습니다. 넘으면 409(`ATTACHMENT_LIMIT_REACHED`)입니다.
문서의 테스트 패널은 JSON 본문만 보내므로 이 API를 시험할 수 없습니다. cURL 예시처럼 `-F`로 보내세요. test key로 호출하면 실제로 올리지 않고 응답 예시를 돌려줍니다.
첨부를 올릴 티켓 ID(티켓 조회 응답의 id)
첨부를 올릴 티켓 타입
▶허용 값
올릴 파일 1개(4MB까지). 파일 이름이 첨부 이름이 됩니다.
true 이면 같은 이름·같은 내용의 첨부가 있어도 새로 올립니다. 기본값 false.
Response Fields
첨부를 올린 티켓 ID
첨부를 올린 티켓 타입
true 이면 같은 이름·같은 내용의 첨부가 이미 있어 새로 올리지 않고 기존 첨부를 돌려준 것입니다(응답 200).
첨부 목록을 다시 읽어 attachment 를 확인했는지 여부. false 이면 업로드는 접수됐지만 아직 확인하지 못한 것입니다(응답 202).
보낸 파일 내용의 SHA-256(16진수). 중복 판정에 쓴 지문입니다.
▶attachmentAttachment | nullrequiredexpandable올린 첨부(또는 중복으로 판정한 기존 첨부). verified=false 이면 null 입니다.
첨부 ID
첨부가 붙은 티켓 ID
파일 이름
파일을 내려받는 서명 주소(유효기간이 짧습니다)
파일 형식(MIME)
확인 시점의 티켓 첨부 개수
verified=false 일 때만 — 확인 방법 안내
curl -X POST https://app.granter.biz/api/public-docs/tickets/attachments \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{}'{
"ticketId": 118823,
"ticketType": "BANK_TRANSACTION_TICKET",
"fileSha256": "9f2c4d1e6b8a7f3c2d1e0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e",
"duplicate": false,
"verified": true,
"attachment": {
"id": 90121,
"ticketId": 118823,
"name": "remittance-2026-10.pdf",
"uploadedUrl": "https://files.example.com/remittance-2026-10.pdf",
"contentType": "application/pdf"
},
"attachmentCount": 2
}POST /api/public-docs/tickets/refresh
워크스페이스에 연결된 카드, 계좌, 홈택스 등 거래·증빙 데이터 갱신을 요청합니다. 요청은 비동기로 접수되며 새 데이터가 즉시 조회되지는 않습니다.
Request Fields
요청 body를 생략하거나 `{}`를 보내면 API key가 연결된 워크스페이스의 지원 자산 전체를 갱신합니다.
특정 자산 종류만 갱신하려면 `assetTypes` 배열을 전달하세요. `requestGroupId`는 서버가 생성하므로 요청에 넣지 않습니다.
응답은 갱신 작업 접수 ACK입니다. 새 데이터 반영까지 약 30분 정도 걸릴 수 있으므로 이후 `tickets`, `balances`, `assets` API를 다시 조회하세요.
중복 수집과 금융기관 중복 로그인을 피하려면 자동화 호출 간격을 30분 이상으로 두세요. 갱신 잠금 시간(30분) 안에 다시 호출하면 새 갱신을 시작하지 않고 `429 Too Many Requests`와 `Retry-After` 헤더(남은 초)를 반환합니다. 응답 본문의 `retryAfterSeconds`에도 같은 값이 들어 있으니 그 시간 뒤에 다시 호출하세요.
선택 갱신 대상. 생략/빈 배열이면 지원 자산 전체 갱신
Response Fields
갱신 요청 접수 여부
백엔드 갱신 작업 추적용 요청 그룹 ID
갱신 요청 접수 상태
새 데이터 반영까지 예상되는 대기 시간(분)
갱신 요청 처리 안내 메시지
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"]
}'{
"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`으로 다시 조회하세요.
연결이 없는 티켓은 빈 배열(`[]`)을 반환합니다.
연결내역을 조회할 기준 티켓 또는 전자결재 문서 ID
기준 티켓 타입. `Total`은 사용할 수 없습니다.
▶주요 허용 값
Response Fields
▶[]TicketReferencerequiredexpandable기준 티켓에 직접 연결된 상대 티켓 목록
연결 관계 자체의 ID
연결된 상대 티켓 ID
연결된 상대 티켓의 거래/증빙 내용
연결된 상대 티켓 금액
연결된 상대 티켓 거래 일시
연결된 상대 티켓 타입
연결 목적
연결 타입
연결된 상대 티켓의 입출금 방향
▶assetTicketReferenceAssetoptionalexpandable연결된 상대 티켓의 자산 정보
연결된 상대 티켓의 자산 기관명
연결된 상대 티켓의 자산명
연결된 상대 티켓의 자산 별칭
연결된 상대 티켓의 자산 번호
연결된 상대 티켓의 거래처명
curl -X GET https://app.granter.biz/api/public-docs/ticket-references?referenceableId=90101&referenceableType=TAX_INVOICE_TICKET \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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입니다. 같은 연결을 재시도할 수 있으면 클라이언트가 직접 고정 값을 넣으세요.
연결 대상 티켓의 참조 정보도 함께 갱신할지 여부. 기본 true
연결할 두 티켓
티켓 ID
티켓 타입. `Total`은 사용할 수 없습니다.
▶주요 허용 값
Response Fields
티켓 연결 요청 처리 성공 여부
연결 대상 티켓의 거래처/상태 등을 함께 갱신하도록 요청했는지 여부
연결 요청에 포함된 두 티켓
연결 요청에 포함된 티켓 ID 목록
연결 요청에 포함된 티켓 타입 목록
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"
}
]
}'{
"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에는 새 키를 사용하세요.
생성할 티켓 연결 목록(1~25개)
연결 대상 티켓의 참조 정보도 함께 갱신할지 여부. 기본 true
연결할 서로 다른 두 티켓
티켓 ID
티켓 타입. `Total`은 사용할 수 없습니다.
Response Fields
모든 티켓 연결 생성 성공 여부
요청한 티켓 연결 수
성공한 티켓 연결 수
실패한 티켓 연결 수
▶resultsTicketReferenceBulkCreateResult[]requiredexpandable요청 순서와 동일한 항목별 처리 결과
요청 references 배열의 0부터 시작하는 항목 위치
해당 티켓 연결 생성 성공 여부
연결 대상 티켓의 참조 정보도 함께 갱신하도록 요청했는지 여부
해당 항목에서 연결을 요청한 두 티켓
실패한 항목의 upstream HTTP 상태
실패한 항목의 오류 메시지
실패한 항목의 오류 코드
backend가 제공한 구조화 오류 상세
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" }
]
}
]
}'{
"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입니다. 같은 해제 요청을 재시도할 수 있으면 클라이언트가 직접 고정 값을 넣으세요.
해제할 연결 관계 ID 목록(1~100개). `ticket-references` 조회 응답의 `ticketReferenceId` 값
Response Fields
티켓 연결 해제 요청 처리 성공 여부
해제된 연결 관계 ID 목록
해제된 연결 관계 수
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]
}'{
"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입니다. 네트워크 오류로 같은 요청을 재시도할 수 있으면 고정 값을 직접 넣으세요.
현재 지원하는 대상 티켓 타입
연결없이 완료 처리할 미연결 세금계산서 티켓 ID 목록(1~25개)
Response Fields
모든 상태변경 성공 여부
처리 대상 티켓 타입
적용한 결제 상태
요청한 세금계산서 티켓 수
성공 또는 기존 상태 유지로 처리된 수
이미 목표 상태여서 변경하지 않은 수
상태변경에 실패한 수
▶resultsTicketPaymentStatusBatchResult[]requiredexpandable요청 순서와 동일한 티켓별 처리 결과
처리 대상 세금계산서 티켓 ID
해당 티켓의 상태변경 성공 여부
이미 목표 상태여서 변경하지 않았는지 여부
실패한 항목의 upstream HTTP 상태
실패한 항목의 오류 메시지
실패한 항목의 오류 코드
backend가 제공한 구조화 오류 상세
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]
}'{
"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입니다. 네트워크 오류로 같은 요청을 재시도할 수 있으면 고정 값을 직접 넣으세요.
현재 지원하는 대상 티켓 타입
연결없이 완료 상태를 되돌릴 미연결 세금계산서 티켓 ID 목록(1~25개)
Response Fields
모든 상태변경 성공 여부
처리 대상 티켓 타입
적용한 결제 상태
요청한 세금계산서 티켓 수
성공 또는 기존 상태 유지로 처리된 수
이미 목표 상태여서 변경하지 않은 수
상태변경에 실패한 수
▶resultsTicketPaymentStatusBatchResult[]requiredexpandable요청 순서와 동일한 티켓별 처리 결과
처리 대상 세금계산서 티켓 ID
해당 티켓의 상태변경 성공 여부
이미 목표 상태여서 변경하지 않았는지 여부
실패한 항목의 upstream HTTP 상태
실패한 항목의 오류 메시지
실패한 항목의 오류 코드
backend가 제공한 구조화 오류 상세
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]
}'{
"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 연동 대상에서 제외하고, 앱 안의 기관 연동 화면에서 처리하세요.
기관 enum. 예: KUKMIN_BANK, KB, HOME_TAX
개인/기업 구분
BK, CD, ST, NT 등 기관 업무 구분
현재 연동된 로그인 방식
true면 연동된 기관만, false면 미연동 기관만 조회
Response Fields
▶[]Organizationrequiredexpandable기관 연동 상태 배열
기관 enum
기관명
업무 구분
업무 구분명
개인/기업 구분
연동 여부
연동 만료 여부
연동 시각
기관 홈페이지 URL
현재 연동 방식
지원 연동 방식 목록
▶supportScrapingDurationSupportScrapableDuration[]optionalexpandable지원 조회 기간
지원 clientType
지원 조회 기간
curl -X GET https://app.granter.biz/api/public-docs/organizations \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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 형식을 사용하세요.
연동할 기관 enum. organizations 대신 단건으로 전달할 때 사용
연동할 기관 enum 배열. 예: [KUKMIN_BANK, KB]
개인/기업 구분. 기본 CORPORATE
인증서 파일 원문 또는 base64 문자열
개인키 파일 원문 또는 base64 문자열
인증서 fingerprint
인증서 비밀번호
인증서 소유자/만료일/발급기관 정보
HOME_TAX 신규 연동 시 필요한 사업자등록번호
선택 추적 ID. 생략 시 서버에서 UUID 생성
Response Fields
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": "금융결제원"
}
}'[
{
"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를 사용자에게 노출하고, 기관 사이트에서 인증서 등록 상태를 확인하도록 안내하세요.
재연동할 기관 enum. organizations 대신 단건으로 전달할 때 사용
재연동할 기관 enum 배열
개인/기업 구분. 기본 CORPORATE
인증서 파일 원문 또는 base64 문자열
개인키 파일 원문 또는 base64 문자열
인증서 fingerprint
인증서 비밀번호
인증서 소유자/만료일/발급기관 정보
HOME_TAX 재연동에서는 보통 생략
선택 추적 ID. 생략 시 서버에서 UUID 생성
Response Fields
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"
}'[
{
"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 형식을 사용하세요.
우리은행(WOORI_BANK) 개인(PERSONAL) 연동은 `withdrawAccountNo`(출금계좌번호)와 `withdrawAccountPassword`(출금계좌 비밀번호)를 모두 보내야 합니다. 은행 사이트 계좌인증 목록에 있는 계좌만 사용할 수 있으며, 다른 기관·우리은행 법인 요청에 두 필드를 보내면 400으로 거부됩니다.
연동할 기관 enum
개인/기업 구분. 기본 CORPORATE
기관 로그인 ID. loginId 별칭 가능
기관 로그인 비밀번호. loginPassword 별칭 가능
필요 기관용 생년월일. 예: 19900101
우리은행 개인 전용 출금계좌번호('-' 없이). WOORI_BANK + PERSONAL 이면 필수, 그 외 기관은 생략. 최대 255자
우리은행 개인 전용 출금계좌 비밀번호. WOORI_BANK + PERSONAL 이면 필수, 그 외 기관은 생략. 최대 255자
선택 추적 ID. 생략 시 서버에서 UUID 생성
Response Fields
▶[]ConnectResultrequiredexpandable기관별 연동/재연동 처리 결과
기관 enum
연동 성공 여부
처리 메시지
처리 코드
개인/기업 구분
실패 사유
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"
}'[
{
"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 형식을 사용하세요.
성공 후 최신 거래 반영까지 기관별 스크래핑 시간이 추가로 걸릴 수 있습니다.
우리은행(WOORI_BANK) 개인(PERSONAL) 재연동은 `withdrawAccountNo`(출금계좌번호)와 `withdrawAccountPassword`(출금계좌 비밀번호)를 다시 모두 보내야 합니다. 다른 기관·우리은행 법인 요청에는 두 필드를 보내지 마세요.
재연동할 기관 enum
개인/기업 구분. 기본 CORPORATE
기관 로그인 ID. loginId 별칭 가능
기관 로그인 비밀번호. loginPassword 별칭 가능
필요 기관용 생년월일. 예: 19900101
우리은행 개인 전용 출금계좌번호('-' 없이). WOORI_BANK + PERSONAL 이면 필수, 그 외 기관은 생략. 최대 255자
우리은행 개인 전용 출금계좌 비밀번호. WOORI_BANK + PERSONAL 이면 필수, 그 외 기관은 생략. 최대 255자
선택 추적 ID. 생략 시 서버에서 UUID 생성
Response Fields
▶[]ConnectResultrequiredexpandable기관별 연동/재연동 처리 결과
기관 enum
연동 성공 여부
처리 메시지
처리 코드
개인/기업 구분
실패 사유
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"
}'[
{
"organization": "KUKMIN_BANK",
"success": true,
"message": "기관 재연동이 완료되었습니다.",
"code": "SUCCESS",
"clientType": "CORPORATE"
}
]POST /api/public-docs/assets
거래가 수집되는 자산과 연동 대상을 조회합니다.
Request Fields
HOME_TAX_ACCOUNT 자산 응답은 홈택스 연결 상태와 사업자 기본 정보를 보여주지만, 발행용 인증서(`issueCertificate`)는 포함하지 않습니다.
`scrapHistory`는 자산별 마지막 수집 요청(`lastRequestedAt`)·성공(`lastCompletedAt`)·실패(`lastFailedAt`) 시각입니다. `lastFailedAt`이 `lastCompletedAt`보다 늦으면 최근 수집이 실패한 상태이므로, 카드처럼 실패 시 거래가 누락되는 자산은 재연결·재수집 여부를 확인하세요. 수집 이력이 없으면 `null`입니다.
CARD, BANK_ACCOUNT, HOME_TAX_ACCOUNT, SOCIAL_INSURANCE_ACCOUNT, CUSTOM, MERCHANT_GROUP, SECURITIES_ACCOUNT, ECOMMERCE, PG, MANUAL
Response Fields
▶[]AssetrequiredexpandableBE `/assets` 원본 응답 배열의 각 원소
자산 ID
자산 타입
자산 번호
워크스페이스 ID
자산명
별칭
금융기관 코드
금융기관명
업종
업종명
숨김 여부
활성 여부
휴면 여부
휴면 가능 여부
무료 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
자동 할당 여부
▶scrapHistoryScrapHistory | nullrequiredexpandable자산별 마지막 수집 이력. 수집 이력이 없으면 null
마지막 수집 요청 시각
마지막 수집 성공 시각
마지막 수집 실패 시각
▶cardAssetCardInfooptionalexpandable카드 자산 정보
만료 연도
만료 월
한도 금액
사용 금액
잔여 한도
이전 카드 번호
▶bankAccountAssetBankAccountInfooptionalexpandable계좌 자산 정보
계좌 잔액
원본 계좌 잔액
통화 코드
조회 시작일
조회 종료일
계좌 번호
계좌명
별칭
계좌 유형
거래내역 보유 여부
▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable홈택스 자산 정보
홈택스 자산 카테고리
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
연락처
업태
종목
▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable증권 자산 정보
총액(원화)
예수금(원화)
외화예수금(원화)
▶foreignDepositsForeignDeposit[]requiredexpandable외화예수금 보유 목록
외화예수금 ID
통화 코드
금액
생성 시각
보유 주식 평가액 합계(원화)
계좌번호
▶productsProduct[]requiredexpandable보유 투자상품
상품 ID
상품 유형 코드
상품 유형명
상품명
상품 코드
수량
통화 코드
현재 금액(원화)
현재 금액
평가 금액(원화)
평가 금액
평가 손익(원화)
평가 손익
수익률
생성 시각
▶customAssetAssetCustomInfooptionalexpandable커스텀 자산 정보
커스텀 자산 유형
자산 번호
금액
▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable이커머스 스토어 계정 정보
스토어 사용자명
OTP 인증 여부
생성 시각
수정 시각
비밀번호 보유 여부
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"
}'[
{
"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를 우선 사용하거나, 직접 집계한다면 대출 계좌를 별도 부채/대출 합계로 분리하세요.
조회 시작일 (전달 시 endDate와 함께 전달 필수)
조회 종료일 (전달 시 startDate와 함께 전달 필수)
Response Fields
▶[]AssetBalancerequiredexpandableBE `/bank-accounts/daily-balances` 응답을 계좌 기준으로 가공한 배열의 각 원소
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
▶balancesBalanceByDate[]requiredexpandable기간별 잔액 목록
잔액 기준일
계좌 잔액 (원화)
원본 통화 기준 잔액
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"
}'[
{
"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`에 별도로 표시됩니다. 대출 실행금이 입금 계좌에 들어온 경우에도 대출 잔액을 일반 잔액에 더하지 마세요.
조회 시작일
조회 종료일
외화 잔액을 현재 환율 기준으로 통일할지 여부. 기본값은 false입니다.
Response Fields
요청 시작일
요청 종료일
실제 계산 종료일. 미래 종료일은 오늘로 보정됩니다.
이전 잔액 기준일
▶assetsDailyFinancialReportAssetBalance[]requiredexpandable자산별 후처리 잔액 목록. 대출 계좌는 isLoan=true로 표시됩니다.
자산 ID
자산 유형
자금일보 표시 자산명
마스킹된 계좌번호
기관명
통화 코드. 대출 집계 행은 currencyTotals에서 LOAN으로 분리됩니다.
계좌 유형. BANK_ACCOUNT의 LOAN은 대출 계좌입니다.
대출 계좌 여부
이전 기준일 표시 잔액. 외화는 이전 기준일 환율로 원화 환산됩니다.
이전 기준일 원통화 잔액
조회 종료 기준일 표시 잔액. 외화는 종료 기준일 환율로 원화 환산됩니다.
조회 종료 기준일 원통화 잔액
표시 잔액 기준 이전 대비 증감
원통화 기준 이전 대비 증감
조회 기간 입금 합계
조회 기간 출금 합계. 출금은 음수로 표시됩니다.
▶balancesBalanceByDate[]requiredexpandable조회 기간을 빠짐없이 채운 날짜별 잔액 목록. 원천에 없는 날짜는 0으로 채웁니다.
잔액 기준일
계좌 잔액 (원화)
원본 통화 기준 잔액
▶totalobjectrequiredexpandable자금일보 합계. 일반 잔액 합계와 대출 잔액을 분리합니다.
대출 제외 이전 잔액 합계
대출 제외 현재 잔액 합계
대출 제외 잔액 증감
대출 제외 입금 합계
대출 제외 출금 합계
대출 계좌 현재 잔액 합계. 일반 잔액에 더하지 마세요.
currentBalance - loanBalance
▶currencyTotalsobject[]requiredexpandable통화별 합계. 대출 계좌는 LOAN 그룹으로 분리됩니다.
통화 코드 또는 LOAN
이전 잔액 합계
현재 잔액 합계
잔액 증감 합계
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
}'{
"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`는 선택값이며, 미입력 시 백엔드 기본 기준일을 사용합니다.
환율 기준일
Response Fields
▶[]ExchangeRaterequiredexpandable통화별 환율 배열
통화 코드
통화 이름
기준 외화 금액
원화 금액
기준 날짜
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"
}'[
{
"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/ticket-tag-groups
태그를 묶어 보는 태그 그룹 목록을 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
그룹은 태그를 묶어 보기 위한 선택 값이며, 한 태그는 그룹 하나에만 속합니다. 태그 생성·수정의 `ticketTagGroupId`에 그룹 ID를 씁니다.
Response Fields
▶[]TicketTagGrouprequiredexpandableBE `/ticket-tag-groups` 응답 배열의 각 원소(이름순)
태그 그룹 ID
태그 그룹 이름
설명. 없으면 빈 문자열
생성 시각
수정 시각
curl -X GET https://app.granter.biz/api/public-docs/ticket-tag-groups \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"id": 4,
"name": "프로젝트",
"description": "프로젝트별 비용 묶음",
"createdAt": "2026-10-01T09:00:00",
"modifiedAt": "2026-10-01T09:00:00"
}
]GET /api/public-docs/tag-details
1차 태그 아래의 세부 분류 기준 데이터를 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
Response Fields
▶[]TagrequiredexpandableBE `/tag-details` 원본 응답 배열의 각 원소
1차/2차 태그 ID
1차/2차 태그명
설명
생성 시각
수정 시각
태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)
워크스페이스 ID
상위 1차 태그 ID (2차 태그에 해당)
코드
지출 집계 금액
입금 집계 금액
숨김 여부
curl -X GET https://app.granter.biz/api/public-docs/tag-details \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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` 헤더를 고정값으로 전달하세요.
상위 1차 태그 ID
2차 태그 이름
2차 태그 설명
Response Fields
1차/2차 태그 ID
1차/2차 태그명
설명
생성 시각
수정 시각
태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)
워크스페이스 ID
상위 1차 태그 ID (2차 태그에 해당)
코드
지출 집계 금액
입금 집계 금액
숨김 여부
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의 마케팅 비용 세부 태그"
}'{
"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차 태그 연결을 함께 지정할 때만 전달하세요.
수정할 2차 태그 ID
상위 1차 태그 ID
수정할 2차 태그 이름
수정할 2차 태그 설명
Response Fields
수정 요청 처리 성공 여부
수정한 2차 태그 ID
이번 요청에서 수정한 필드 목록
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 광고·콘텐츠 집행 비용"
}'{
"ok": true,
"tagDetailId": 6,
"updatedFields": ["tagId", "name", "description"]
}GET /api/public-docs/categories
회계 처리와 분석에 사용하는 계정과목 기준 데이터를 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
Response Fields
▶[]ExpenseCategoryrequiredexpandableBE `/expense-categories` 원본 응답 배열의 각 원소
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
curl -X GET https://app.granter.biz/api/public-docs/categories \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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` 중 하나입니다.
계정과목 이름
계정과목 설명
상위 분류. 예: 판매비와관리비, 영업외비용
비용 유형
계정과목 코드 번호
아이콘 이미지 URL
기본 과세 유형
Response Fields
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
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"
}'{
"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`을 모두 전달해야 합니다.
수정할 계정과목 ID
수정할 계정과목 이름
수정할 계정과목 설명
수정할 상위 분류
수정할 비용 유형
계정과목 코드 번호
아이콘 이미지 URL
기본 과세 유형
Response Fields
수정 요청 처리 성공 여부
수정한 계정과목 ID
이번 요청에서 수정한 필드 목록
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"
}'{
"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
워크스페이스 ID
워크스페이스/회사 이름
워크스페이스 아이콘 이미지 URL
사업자등록번호
가입 시 선택한 사용 인원 규모
회사 유형
사업 설명
산업 분류 정보
워크스페이스 생성 시각
회계사 워크스페이스 여부
curl -X GET https://app.granter.biz/api/public-docs/workspace-profile \ -H "Authorization: Basic <BASE64(API_KEY:)>"
{
"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워크스페이스 구성원 프로필 배열
유저 ID
이름
워크스페이스 표시 이름
이메일
전화번호
사용자 프로필 이미지 URL
워크스페이스 ID
워크스페이스명
팀 ID
팀명
▶roleWorkspaceRole | nulloptionalexpandable워크스페이스 역할
역할 ID
역할명
오너 여부
기본 역할 여부
curl -X GET https://app.granter.biz/api/public-docs/user-profiles \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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
구독 ID
워크스페이스 ID
구독 상태
무료 플랜 여부
요금 산정 대상 활성 자산 수
보유 리워드 잔액
예상 청구 금액
예상 결제 금액
다음 결제 예정일
구독 종료 시각
무료 플랜 종료 시각
▶subscriptionPlanSubscriptionPlan | nulloptionalexpandable현재 요금제 정보
요금제 이름
요금제 설명
요금제 섹션 설명
▶discountSubscriptionDiscount | nulloptionalexpandable적용 중인 할인 정보
할인율
할인 종료일
curl -X GET https://app.granter.biz/api/public-docs/subscription \ -H "Authorization: Basic <BASE64(API_KEY:)>"
{
"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
▶[]UserrequiredexpandableBE `/workspaces` 응답의 `users` 배열 원본
유저 ID
이름
이메일
워크스페이스 ID
워크스페이스명
팀 ID
팀명
전화번호
▶roleWorkspaceRolerequiredexpandable워크스페이스 역할
역할 ID
역할명
오너 여부
기본 역할 여부
curl -X GET https://app.granter.biz/api/public-docs/people \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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` 배열로 반환됩니다.
초대 대상 목록
초대 대상 이메일
초대 대상 이름
프로필 이미지 URL
전화번호
Slack 초대 토큰. 일반 이메일 초대에서는 생략합니다.
Response Fields
▶[]InviteUserResponserequiredexpandableBE `/workspaces/bulk-invitation` 원본 응답 배열의 각 원소
초대 성공 여부
초대 처리 메시지
초대 대상 이메일
초대 대상 이름
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"
}
]
}'[
{
"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
▶[]TeamrequiredexpandableBE `/teams` 원본 응답 배열의 각 원소
팀 ID
팀명
curl -X GET https://app.granter.biz/api/public-docs/teams \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"id": 6,
"name": "인사팀"
}
]GET /api/public-docs/contacts
거래처, 고객사, 공급사처럼 상대방 기준으로 관리하는 거래처 데이터를 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
현재 응답은 최신 거래처 목록 기준으로 최대 100건을 조회합니다.
각 거래처의 `managers[]`에 거래처 담당자가 포함됩니다. 담당자 수정·삭제에는 `managers[].id`를 `contactManagerId`로 사용하세요.
Response Fields
▶[]ContactrequiredexpandableBE `/contacts` 원본 응답 배열의 각 원소
거래처 ID
워크스페이스 ID
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
휴대전화
전화번호
최근 발행 시각
거래처 지역 구분
숨김 여부
▶managersContactManager[]optionalexpandable거래처 담당자 목록
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
국가
계좌번호
은행명
예금주명
메모
즐겨찾기 여부
curl -X GET https://app.granter.biz/api/public-docs/contacts \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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": [
{
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": "0212345678",
"faxNumber": null,
"email": "manager@example.com",
"memo": ""
}
],
"region": "DOMESTIC",
"nation": "",
"isHidden": false,
"memo": "",
"isFavorite": false
}
]POST /api/public-docs/contacts
외부 CRM, ERP, 영업관리 시스템에서 관리하는 거래처를 그랜터 거래처 마스터에 생성합니다.
Request Fields
쓰기 요청입니다. 재시도 안전성이 필요하면 `Idempotency-Key` 헤더를 고정 값으로 전달하세요.
거래처 생성 권한이 없는 API key 또는 플랜에서는 403 응답이 반환될 수 있습니다.
백엔드는 `registrationNumber`를 필수·고유 값으로 처리합니다. 빈 문자열은 기존 미등록 거래처와 중복될 수 있으므로 실제 식별 값을 전달하세요.
`managers`로 거래처 담당자를 최대 10명까지 함께 보낼 수 있습니다. 거래처를 먼저 만든 뒤 담당자를 순서대로 추가하며, 각 담당자 값의 규칙은 `contacts-managers-create`와 같습니다.
담당자 추가가 일부 또는 전부 실패해도 거래처 생성은 성공으로 유지되고 되돌리지 않습니다. 응답의 `managerResults[]`(요청 순서별 `ok`·`contactManagerId`·`error`)와 `managerSummary`로 담당자별 결과를 확인하고, 실패한 담당자만 `contacts-managers-create`로 다시 추가하세요.
`managers`를 보내면 응답의 `managers`는 담당자 추가 후 다시 조회한 목록입니다. `managers`를 보내지 않으면 응답은 기존과 같습니다.
`managers` 형식이 잘못되면 거래처도 생성하지 않고 400과 필드별 오류(`details.fieldErrors`)를 반환합니다.
거래처 삭제 API는 아직 Public API로 제공하지 않습니다.
거래처 상호명/회사명
고유 사업자/거래처 식별번호 (`-` 없이 10자리 권장)
대표자명
업태
종목
사업장 주소
대표 이메일
보조 이메일
휴대전화
유선 전화번호
거래처 지역 구분. 기본값은 DOMESTIC
메모/비고
입금 계좌번호
입금 은행명
예금주명
거래처 생성 직후 함께 추가할 담당자 목록(최대 10명). 각 원소의 필드는 아래 `managers[].*`와 같습니다.
담당자 이름 (최대 255자)
담당자 휴대전화. 하이픈을 빼고 숫자 11자리 (하이픈·공백은 서버가 지웁니다)
담당자 전화번호. 하이픈을 빼고 숫자 9~12자리
담당자 팩스번호 (최대 255자)
담당자 이메일
담당자 메모 (최대 32,600자). 생략하면 빈 문자열로 저장합니다.
Response Fields
거래처 ID
워크스페이스 ID
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
휴대전화
전화번호
최근 발행 시각
거래처 지역 구분
숨김 여부
▶managersContactManager[]optionalexpandable거래처 담당자 목록
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
국가
계좌번호
은행명
예금주명
메모
즐겨찾기 여부
▶managerResultsContactManagerCreateResult[]optionalexpandable요청에 `managers`를 보냈을 때만 포함. 담당자별 추가 결과(요청 순서)
요청 `managers[]`에서의 순서(0부터)
이 담당자 추가 성공 여부
성공 시 새 담당자 ID. 재조회로 하나로 특정하지 못하면 null
성공 시 재조회로 새 담당자 ID를 확인했는지 여부
▶managerContactManager | nulloptionalexpandable성공 시 재조회한 새 담당자
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
▶newManagersContactManager[]optionalexpandable성공 시 이번 추가 전후 재조회에서 새로 나타난 담당자 목록(확인용)
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
ID를 확인하지 못했을 때의 안내
실패 시 요청한 담당자 이름
실패 시 HTTP 상태 코드
실패 시 오류 메시지
실패 시 오류 코드(예: CONTACT_ID_UNCONFIRMED)
실패 시 backend 검증 상세
▶managerSummaryobjectoptionalexpandable요청에 `managers`를 보냈을 때만 포함. 담당자 추가 결과 요약
요청한 담당자 수
추가에 성공한 담당자 수
추가에 실패한 담당자 수
새 담당자 ID까지 확인한 수
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에서 동기화",
"managers": [
{
"name": "담당자 B",
"phoneNumber": "010-1234-5678",
"email": "manager@example.com"
}
]
}'{
"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": [
{
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": null,
"faxNumber": null,
"email": "manager@example.com",
"memo": ""
}
],
"region": "DOMESTIC",
"nation": "",
"isHidden": false,
"memo": "외부 ERP에서 동기화",
"isFavorite": false,
"managerResults": [
{
"index": 0,
"ok": true,
"contactManagerId": 5012,
"idConfirmed": true,
"manager": {
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": null,
"faxNumber": null,
"email": "manager@example.com",
"memo": ""
},
"newManagers": [
{
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": null,
"faxNumber": null,
"email": "manager@example.com",
"memo": ""
}
]
}
],
"managerSummary": {
"requestedCount": 1,
"succeededCount": 1,
"failedCount": 0,
"idConfirmedCount": 1
}
}PUT /api/public-docs/contacts
기존 거래처의 기본 정보, 연락처, 계좌 정보, 메모를 부분 수정합니다.
Request Fields
쓰기 요청입니다. `contactId`와 수정할 필드를 1개 이상 전달해야 합니다.
전달하지 않은 필드는 변경하지 않습니다.
거래처 수정 권한이 없는 API key 또는 플랜에서는 403 응답이 반환될 수 있습니다.
이 API는 거래처 담당자(`managers`)를 바꾸지 않습니다. 본문에 `managers`를 넣어도 무시되므로, 담당자는 `contacts-managers-create`, `contacts-managers-update`, `contacts-managers-delete`로 관리하세요.
거래처 삭제 API는 아직 Public API로 제공하지 않습니다.
수정 대상 거래처 ID
거래처 상호명/회사명
사업자등록번호 (`-` 없이 10자리 권장)
대표자명
업태
종목
사업장 주소
대표 이메일
보조 이메일
휴대전화
유선 전화번호
메모/비고
입금 계좌번호
입금 은행명
예금주명
Response Fields
수정 요청 처리 성공 여부
수정한 거래처 ID
이번 요청에서 수정한 거래처 필드 목록
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": "담당 이메일 변경"
}'{
"ok": true,
"contactId": 928,
"updatedFields": ["email", "memo"]
}POST /api/public-docs/contacts/managers
기존 거래처에 담당자(이름·휴대전화·전화·팩스·이메일·메모)를 1명 추가하고, 추가 후 거래처를 다시 조회해 새 담당자 ID를 돌려줍니다.
Request Fields
쓰기 요청입니다. 재시도 안전성이 필요하면 `Idempotency-Key` 헤더를 고정 값으로 전달하세요.
`contactId`는 `contacts` 조회 응답의 거래처 `id`입니다. API key가 연결된 워크스페이스의 거래처가 아니면 404(`CONTACT_NOT_FOUND`)를 반환합니다.
`name`은 필수입니다. `phoneNumber`는 숫자 11자리, `telNumber`는 숫자 9~12자리여야 하며 하이픈·공백·괄호는 서버가 지운 뒤 검사합니다. `+82` 같은 국가번호는 0으로 시작하는 국내 번호로 바꿔 보내세요.
`memo`를 생략하면 빈 문자열로 저장합니다. 선택 필드에 빈 문자열이나 `null`을 보내면 값 없이 저장합니다.
백엔드 담당자 추가 API는 새 ID를 돌려주지 않습니다. 그래서 추가 전후 담당자 목록을 비교해 새 담당자를 찾습니다. 하나로 특정하지 못하면(같은 이름의 담당자가 동시에 추가된 경우, 같은 `Idempotency-Key`로 재시도해 새 담당자가 생기지 않은 경우, 재조회 실패) 추측하지 않고 `idConfirmed=false`, `contactManagerId=null`과 `newManagers`·`message`를 돌려줍니다. 이때도 추가 요청 자체는 성공한 것이므로 다시 추가하기 전에 `contacts`로 담당자 목록을 확인하세요.
담당자는 거래처 단위로 관리됩니다. 세금계산서 한 장에 담당자를 따로 지정하는 기능은 없습니다.
담당자를 추가할 거래처 ID
담당자 이름 (최대 255자)
휴대전화. 하이픈을 빼고 숫자 11자리
전화번호. 하이픈을 빼고 숫자 9~12자리
팩스번호 (최대 255자)
이메일
메모 (최대 32,600자). 생략하면 빈 문자열로 저장합니다.
Response Fields
담당자 추가 요청 처리 성공 여부
담당자를 추가한 거래처 ID
새 담당자 ID. 재조회로 하나로 특정하지 못하면 null(`idConfirmed=false`)
추가 후 거래처를 다시 조회해 새 담당자 ID를 하나로 확인했는지 여부
▶managerContactManager | nullrequiredexpandable재조회한 새 담당자. `idConfirmed=false`이면 null
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
▶newManagersContactManager[]requiredexpandable추가 전후 재조회에서 새로 나타난 담당자 목록(확인용)
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
`idConfirmed=false`일 때 확인 방법 안내
curl -X POST https://app.granter.biz/api/public-docs/contacts/managers \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": "0212345678",
"email": "manager@example.com",
"memo": "세금계산서 수신 담당"
}'{
"ok": true,
"contactId": 928,
"contactManagerId": 5012,
"idConfirmed": true,
"manager": {
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": "0212345678",
"faxNumber": null,
"email": "manager@example.com",
"memo": "세금계산서 수신 담당"
},
"newManagers": [
{
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": "0212345678",
"faxNumber": null,
"email": "manager@example.com",
"memo": "세금계산서 수신 담당"
}
]
}PUT /api/public-docs/contacts/managers
거래처 담당자의 이름·연락처·메모를 수정합니다. 전달한 필드만 바꾸고 나머지는 기존 값을 유지하며, 수정 후 다시 조회한 담당자를 돌려줍니다.
Request Fields
쓰기 요청입니다. `contactId`, `contactManagerId`와 수정할 필드를 1개 이상 전달해야 합니다.
`contactManagerId`는 `contacts` 조회 응답의 `managers[].id`입니다. 해당 거래처의 담당자가 아니면 404(`CONTACT_MANAGER_NOT_FOUND`)를 반환합니다.
전달하지 않은 필드는 기존 값을 유지합니다. 선택 필드(`phoneNumber`, `telNumber`, `faxNumber`, `email`)에 `null`이나 빈 문자열을 보내면 값을 지웁니다. `name`은 지울 수 없습니다.
백엔드 담당자 수정은 전체 교체 방식이라, 서버가 기존 담당자 값을 읽어 전달한 필드만 바꾼 전체 값을 보냅니다. 같은 담당자를 동시에 수정하면 나중 요청이 앞 요청의 변경을 덮을 수 있습니다.
필드 형식 규칙은 `contacts-managers-create`와 같습니다.
응답의 `verified`는 수정 후 다시 조회한 값이 요청한 값과 같은지입니다. `false`이면 `manager`와 `message`를 확인하세요.
담당자가 속한 거래처 ID
수정할 담당자 ID (`managers[].id`)
담당자 이름 (최대 255자)
휴대전화. 숫자 11자리, `null`이면 삭제
전화번호. 숫자 9~12자리, `null`이면 삭제
팩스번호 (최대 255자), `null`이면 삭제
이메일, `null`이면 삭제
메모 (최대 32,600자). 빈 문자열이면 메모를 비웁니다.
Response Fields
담당자 수정 요청 처리 성공 여부
거래처 ID
수정한 담당자 ID
이번 요청에서 전달한 담당자 필드 목록
수정 후 다시 조회한 담당자 값이 요청한 값과 같은지 여부
▶managerContactManager | nullrequiredexpandable수정 후 다시 조회한 담당자. 재조회하지 못하면 null
거래처 담당자 ID
거래처 ID
담당자 이름
휴대전화
전화번호
팩스번호
이메일
메모
`verified=false`일 때 안내
curl -X PUT https://app.granter.biz/api/public-docs/contacts/managers \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contactId": 928,
"contactManagerId": 5012,
"email": "new-manager@example.com",
"telNumber": null
}'{
"ok": true,
"contactId": 928,
"contactManagerId": 5012,
"updatedFields": ["telNumber", "email"],
"verified": true,
"manager": {
"id": 5012,
"contactId": 928,
"name": "담당자 B",
"phoneNumber": "01012345678",
"telNumber": null,
"faxNumber": null,
"email": "new-manager@example.com",
"memo": "세금계산서 수신 담당"
}
}DELETE /api/public-docs/contacts/managers
거래처 담당자 1명을 삭제합니다. 거래처 연락처 정보 관리용이며 거래처·티켓·발행된 증빙은 지우지 않습니다.
Request Fields
쓰기 요청입니다. `contactId`와 `contactManagerId`를 body로 전달합니다.
`contactManagerId`는 `contacts` 조회 응답의 `managers[].id`입니다. 해당 거래처의 담당자가 아니거나 이미 삭제됐으면 404(`CONTACT_MANAGER_NOT_FOUND`)를 반환합니다. 재시도 후 404가 오면 `contacts`로 삭제 여부를 확인하세요.
삭제는 되돌릴 수 없습니다. 같은 정보가 다시 필요하면 `contacts-managers-create`로 새로 추가하세요(새 ID가 부여됩니다).
이미 발행된 세금계산서에 적힌 연락처는 바뀌지 않습니다.
응답의 `verified`는 삭제 후 다시 조회한 거래처에서 담당자가 사라진 것을 확인했는지입니다.
담당자가 속한 거래처 ID
삭제할 담당자 ID (`managers[].id`)
Response Fields
담당자 삭제 요청 처리 성공 여부
거래처 ID
삭제한 담당자 ID
삭제 후 다시 조회한 거래처에서 담당자가 사라진 것을 확인했는지 여부
`verified=false`일 때 안내
curl -X DELETE https://app.granter.biz/api/public-docs/contacts/managers \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contactId": 928,
"contactManagerId": 5012
}'{
"ok": true,
"contactId": 928,
"deletedContactManagerId": 5012,
"verified": true
}GET /api/public-docs/workflows
기안 문서, 결재 상태, 결재선 정보를 포함한 전자결재 데이터를 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
직접 호출 시 `status`, `draftedByMe`, `limit`, `offset` query string을 사용할 수 있습니다.
테스트 패널은 기본 목록 조회를 수행합니다.
결재 상태 필터
내가 올린 결재만 조회할지 여부
조회 건수 제한. 지정하지 않으면 최대 100건까지 조회합니다.
페이지 오프셋
Response Fields
▶[]WorkflowrequiredexpandableBE `/workflows` 원본 응답 배열의 각 원소
전자결재 ID
워크스페이스 ID
결재안 제목
결재 내용
결재 금액
원본 결재 금액
이체 요청일
결재 상태
통화 코드
결재 요청 시각
최종 수정 시각
현재 결재 차수
연결된 태그명
연결된 태그 ID
▶userUserrequiredexpandable기안자 정보
기안자 ID
기안자 이름
기안자 이메일
삭제 여부
▶refundAccountRefundAccountoptionalexpandable환급 계좌 정보
예금주명
계좌번호
은행명
▶stepsWorkflowStep[]requiredexpandable결재 단계 목록
결재 단계 ID
결재 차수
결재 단계 상태
생성 시각
수정 시각
▶approverApproverrequiredexpandable결재자 정보
결재자 ID
결재자 이름
결재자 이메일
삭제 여부
▶reviewersReviewer[]requiredexpandable검토자 목록
검토자 연결 ID
▶reviewerUserResponserequiredexpandable검토자 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesWorkflowMessage[]optionalexpandable결재 메시지 목록
메시지 ID
메시지 내용
메시지 타입
생성 시각
삭제 시각
▶userUserResponserequiredexpandable작성자 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
▶attachmentsWorkflowAttachment[]optionalexpandable첨부파일 목록
첨부파일 ID
파일명
업로드 URL
MIME 타입
curl -X GET https://app.granter.biz/api/public-docs/workflows \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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 응답이 반환될 수 있습니다.
결재 제목
결재 내용. HTML 문자열도 전달할 수 있습니다.
결재 금액. `150,000원` 같은 문자열도 허용합니다.
결재자 ID 배열. 배열 순서대로 1차, 2차 결재자가 됩니다.
검토자/참조자 ID 배열
지급예정일. 생략 시 요청 처리일 기준 날짜
통화 코드. 기본값은 KRW
환불/이체 계좌 정보. 제공 시 accountHolder, accountNumber, organizationName이 모두 필요합니다.
예금주
계좌번호
은행명/기관명
Response Fields
전자결재 ID
워크스페이스 ID
결재안 제목
결재 내용
결재 금액
원본 결재 금액
이체 요청일
결재 상태
통화 코드
결재 요청 시각
최종 수정 시각
현재 결재 차수
연결된 태그명
연결된 태그 ID
▶userUserrequiredexpandable기안자 정보
기안자 ID
기안자 이름
기안자 이메일
삭제 여부
▶refundAccountRefundAccountoptionalexpandable환급 계좌 정보
예금주명
계좌번호
은행명
▶stepsWorkflowStep[]requiredexpandable결재 단계 목록
결재 단계 ID
결재 차수
결재 단계 상태
생성 시각
수정 시각
▶approverApproverrequiredexpandable결재자 정보
결재자 ID
결재자 이름
결재자 이메일
삭제 여부
▶reviewersReviewer[]requiredexpandable검토자 목록
검토자 연결 ID
▶reviewerUserResponserequiredexpandable검토자 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesWorkflowMessage[]optionalexpandable결재 메시지 목록
메시지 ID
메시지 내용
메시지 타입
생성 시각
삭제 시각
▶userUserResponserequiredexpandable작성자 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
▶attachmentsWorkflowAttachment[]optionalexpandable첨부파일 목록
첨부파일 ID
파일명
업로드 URL
MIME 타입
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": "국민은행"
}
}'{
"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`는 선택 필터입니다.
조회 시작일
조회 종료일
고용 형태 필터. 단일 값 또는 배열을 전달할 수 있습니다.
급여 지급 상태 필터. 단일 값 또는 배열을 전달할 수 있습니다.
직원 ID 필터
직원명 또는 설명 키워드 검색
Response Fields
▶[]SalaryHistoryrequiredexpandableBE `/salary-histories` 원본 응답 배열의 각 원소
급여 이력 ID
워크스페이스 ID
▶employeeUserResponseoptionalexpandable직원 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
직원 ID
직원명
직원 이메일
고용 형태
총급여
실질인정금액
지급일
비과세 식대
상여금
수당 합계
국민연금
건강보험
고용보험
장기요양보험
은행명
은행 계좌번호
실지급액
설명
고용 할인 유형
소득세
지방소득세
급여 지급 상태
명세서 email 발송 여부
email 발송 시각
메시지 개수
당월 근무 시간
미달 근무 시간
무급휴가 시간
근무 인정 시간
적용 비율 타입
적용 비율
▶taxExemptionsTitleAmount[]optionalexpandable비과세급 상세
항목명
금액
▶incentivesTitleAmount[]optionalexpandable인센티브 상세
항목명
금액
▶allowancesTitleAmount[]optionalexpandable수당 상세
항목명
금액
▶deductionsTitleAmount[]optionalexpandable공제 상세
항목명
금액
생성 시각
수정 시각
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"
}'[
{
"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": 224,
"shortfallHours": 0,
"unpaidLeaveHours": 0,
"recognizedWorkHours": 224,
"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에 전달합니다. 외부 급여 시스템의 확정값이 있으면 직접 전달하세요.
직원 ID. 기존 구성원 급여 생성 시 권장
직원명. 비회원 또는 수동 급여 생성 시 사용
직원 이메일
고용 형태
기본 급여 또는 총 급여 기준 금액
지급일
비과세 식대. 생략 시 0
상여금. 생략 시 0
수당 합계. 생략 시 allowances 합계 또는 0
국민연금. 생략 시 0
건강보험. 생략 시 0
고용보험. 생략 시 0
장기요양보험. 생략 시 0
급여 입금 은행명
급여 입금 계좌번호
급여 내역 메모
실질인정금액. 생략 시 totalAmount + mealAmount
실지급액. 생략 시 지급/공제 항목으로 계산
고용 할인 유형. 생략 시 NONE
소득세. 생략 시 0
지방소득세. 생략 시 0
급여 지급 상태. 생략 시 PENDING
당월 소정근로시간(시간 단위). 생략 시 지급월 일수 × 8
미달 근무시간(시간 단위). 생략 시 0
무급휴가(시간 단위). 생략 시 0
근무 인정시간(시간 단위). 생략 시 scheduledWorkHours - shortfallHours - unpaidLeaveHours
적용 비율 타입. 생략 시 빈 문자열
적용 비율. 생략 시 1
비과세급 상세. 생략 시 빈 배열
인센티브 상세. 생략 시 빈 배열
수당 상세. 생략 시 빈 배열
공제 상세. 생략 시 빈 배열
Response Fields
급여 이력 ID
워크스페이스 ID
▶employeeUserResponseoptionalexpandable직원 정보
유저 ID
유저 이름
유저 이메일
삭제 여부
직원 ID
직원명
직원 이메일
고용 형태
총급여
실질인정금액
지급일
비과세 식대
상여금
수당 합계
국민연금
건강보험
고용보험
장기요양보험
은행명
은행 계좌번호
실지급액
설명
고용 할인 유형
소득세
지방소득세
급여 지급 상태
명세서 email 발송 여부
email 발송 시각
메시지 개수
당월 근무 시간
미달 근무 시간
무급휴가 시간
근무 인정 시간
적용 비율 타입
적용 비율
▶taxExemptionsTitleAmount[]optionalexpandable비과세급 상세
항목명
금액
▶incentivesTitleAmount[]optionalexpandable인센티브 상세
항목명
금액
▶allowancesTitleAmount[]optionalexpandable수당 상세
항목명
금액
▶deductionsTitleAmount[]optionalexpandable공제 상세
항목명
금액
생성 시각
수정 시각
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 }]
}'{
"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": 240,
"shortfallHours": 0,
"unpaidLeaveHours": 0,
"recognizedWorkHours": 240,
"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/contracts
업무 > 계약의 계약 목록을 상태·청구서 현황·문서 종류·생성일·거래처·검색어로 조회합니다. 계약마다 거래처, 품목 요약, 견적서·청구서·거래명세서의 발급·납부 현황, 연결된 세금계산서와 계약서(전자서명) 서명 상태를 함께 돌려줍니다.
Request Fields
모든 조건은 query string으로 전달합니다. 여러 값을 받는 필드는 `statuses=PENDING,COMPLETED`처럼 쉼표로 잇거나 같은 이름을 반복해 보냅니다.
계약 ID 내림차순 커서 페이지입니다. 응답의 `lastSeenId`를 다음 요청의 `lastSeenId`로 보내면 이어서 조회하고, `null`이면 마지막 페이지입니다.
`paymentDisplayStatuses`는 앱 계약 목록의 '현황' 값입니다. 연체·납부대기·확인불가는 대기(PENDING) 계약의 청구서 현황이므로 보통 `statuses=PENDING`과 함께 씁니다.
`createdDateFrom`·`createdDateTo`는 계약을 만든 날짜 조건입니다. 발급일·납부기한·입금일 조건이 아닙니다.
앱의 '초안' 탭은 브라우저에 임시 저장된 작성 중 계약이라 이 API에 나오지 않습니다. `DRAFT`는 서버에 저장된 초안만 뜻합니다.
문서에 없는 query parameter를 보내면 조건 오타로 전체 목록을 받는 일을 막기 위해 400으로 거부합니다.
계약 API는 워크스페이스 소유자 권한의 API key로 호출되며, 계약 관리 권한이 없는 워크스페이스는 403을 반환합니다.
계약 상태 목록
▶허용 값
청구서 현황. 넣으면 발급된 청구서가 있거나 대기·완료인 계약만 남습니다.
▶허용 값
보유 문서 종류. 발급 전 초안 문서도 포함해 판단합니다.
▶허용 값
계약 생성일 시작(포함)
계약 생성일 종료(포함)
거래처명·문서번호·계약 품목명에 포함된 문자열 (100자 이하, 대소문자 무시)
거래처 ID (`contacts` 조회 결과)
이전 응답의 `lastSeenId` 커서
한 페이지 건수 (1~200, 기본 100)
`true`면 상태 조건을 뺀 같은 조건의 상태별 건수(`statusCounts`)를 함께 돌려줍니다.
Response Fields
▶contractsContractListItem[]requiredexpandable계약 목록 (ID 내림차순)
▶contractContractrequiredexpandable계약 요약
계약 ID
계약 상태. PENDING=대기(진행 중), COMPLETED=완료(거래 종료), CANCELED=취소, DRAFT=서버 초안
마지막 상태 변경 주체. INVOICE_PAYMENT는 결제 상태에 따른 자동 완료·재개
현재 거래처 ID
계약 총액
계약 통화 (예: KRW)
기본 발급자 프로필 ID
취소 사유
취소 상세 사유
마지막 상태 변경 시각
계약 결제 상태. PAID가 되면 대기 계약이 자동으로 완료됩니다
결제 확인 방식. MANUAL=입금내역 연결 없이 완료, BANK_TRANSACTION=연결된 입금내역 근거
결제 확인 시각
결제를 확인한 구성원 ID. 자동 연결이면 null
거래처명
거래처 담당자 이름 목록
계약 담당 구성원 ID
화면 '현황' 값. OVERDUE=연체중, PENDING=납부대기, VERIFICATION_SKIPPED=확인불가, COMPLETED=지급완료
최신 청구서 결제 상태
최신 청구서 납부기한
연체 여부
▶documentsContractListDocument[]optionalexpandable계약 문서 요약
계약 문서 ID
문서 종류 (견적서·청구서·거래명세서)
문서번호 (발급 후 부여)
최신 발급본 ID. null이면 미발급
청구서 결제 상태 (청구서만)
발급일
발급 처리 시각
결제 확인 시각
납부기한 (청구서만)
연체 여부
▶itemSummaryItemSummary | nulloptionalexpandable대표 품목명과 품목 수
대표 품목명
품목 수
▶taxInvoicesContractTaxInvoice[]optionalexpandable계약에 연결된 세금계산서 요약
세금계산서 ID
세금계산서 상태
작성일
합계 금액
▶agreementsContractAgreement[]optionalexpandable계약에 연결된 계약서(전자서명) 요약
계약서 ID
최신 발급본 ID
계약서 번호
발급일
서명 진행 상태
다음 페이지 커서. null이면 마지막 페이지
▶statusCountsContractStatusCountsoptionalexpandableincludeCounts=true일 때만 포함되는 상태별 건수
상태 조건을 뺀 전체 건수
서버 초안 건수 (화면 '초안' 탭은 브라우저 임시 저장본이라 다를 수 있음)
대기 건수
완료 건수
취소 건수
curl -X GET https://app.granter.biz/api/public-docs/contracts?statuses=PENDING&limit=20&includeCounts=true \ -H "Authorization: Basic <BASE64(API_KEY:)>"
{
"contracts": [
{
"contract": {
"id": 1201,
"status": "PENDING",
"statusChangeSource": "USER",
"contactId": 3301,
"totalAmount": 3300000,
"currency": "KRW",
"defaultIssuerProfileId": 12,
"cancellationReason": null,
"cancellationReasonDetail": null,
"statusChangedAt": "2026-09-01T10:12:00",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"paymentConfirmedAt": null,
"paymentConfirmedByUserId": null
},
"contactName": "주식회사 샘플",
"contactManagerNames": ["김담당"],
"managerUserId": 77,
"paymentDisplayStatus": "OVERDUE",
"latestInvoicePaymentStatus": "UNPAID",
"latestInvoiceDueDate": "2026-09-20",
"overdue": true,
"documents": [
{
"id": 9001,
"type": "INVOICE",
"documentNumber": "I260900001",
"latestIssuedRevisionId": 15001,
"paymentStatus": "UNPAID",
"issueDate": "2026-09-01",
"issuedAt": "2026-09-01T10:12:00",
"paymentConfirmedAt": null,
"dueDate": "2026-09-20",
"overdue": true
}
],
"itemSummary": { "representativeItemName": "홈페이지 유지보수", "itemCount": 2 },
"taxInvoices": [],
"agreements": []
}
],
"lastSeenId": null,
"statusCounts": { "total": 42, "draft": 0, "pending": 25, "completed": 12, "canceled": 5 }
}GET /api/public-docs/contracts/detail
계약 한 건의 상세를 조회합니다. 계약·결제 상태, 담당자, 품목, 문서별 발급본(품목·금액·입금 계좌·전달 수신자), 연결된 입금내역, 변경 이력과 함께 계약서(전자서명) 서명 상태와 연결된 세금계산서를 돌려줍니다.
Request Fields
`contractId`를 query string으로 전달합니다. 계약 ID는 `contracts` 조회 응답의 `contract.id`입니다.
`documents[].revisions`에는 발급본 전체(정정 발급 이력 포함)와 현재 초안만 담깁니다.
결제 상태(`contract.paymentStatus`)와 입금내역(`paymentProofs`)은 계약 단위입니다. 청구서 문서의 `paymentStatus`는 같은 값을 호환용으로 보여 줍니다.
`paymentProofs[].updateSource`가 `SYSTEM`이면 그랜터가 금액·입금 계좌·입금자명이 정확히 맞는 입금을 자동으로 연결한 것입니다.
변경 이력(`changeLogs`)의 스냅샷에는 해당 변경과 관련된 필드만 채워집니다.
조회할 계약 ID
Response Fields
▶contractContractrequiredexpandable계약
계약 ID
계약 상태. PENDING=대기(진행 중), COMPLETED=완료(거래 종료), CANCELED=취소, DRAFT=서버 초안
마지막 상태 변경 주체. INVOICE_PAYMENT는 결제 상태에 따른 자동 완료·재개
현재 거래처 ID
계약 총액
계약 통화 (예: KRW)
기본 발급자 프로필 ID
취소 사유
취소 상세 사유
마지막 상태 변경 시각
계약 결제 상태. PAID가 되면 대기 계약이 자동으로 완료됩니다
결제 확인 방식. MANUAL=입금내역 연결 없이 완료, BANK_TRANSACTION=연결된 입금내역 근거
결제 확인 시각
결제를 확인한 구성원 ID. 자동 연결이면 null
거래처명
▶participantsParticipant[]requiredexpandable계약 담당자·참조자
구성원 ID
담당자 또는 참조자
▶itemsContractItem[]requiredexpandable계약 품목
품목 ID
품목명
수량
공급가액
세액
통화
▶documentsContractDocumentDetail[]requiredexpandable견적서·청구서·거래명세서 (종류별 최대 1개)
▶documentContractDocumentrequiredexpandable계약 문서
계약 문서 ID
문서 종류
문서번호
현재 초안 리비전 ID
최신 발급본 ID
청구서 입출금 방향
청구서 결제 상태 (계약 결제 상태와 동기화)
▶revisionsContractRevision[]requiredexpandable발급본 전체와 현재 초안 (삭제된 초안 제외)
리비전 ID
리비전 번호 (정정 발급마다 증가)
초안 또는 발급본
문서에 표시된 거래처명
문서에 표시된 발급자명
▶paymentAccountPaymentAccount | nulloptionalexpandable문서에 표시된 입금 계좌 스냅샷
은행명
계좌번호
예금주
문서 통화
발급일
납부기한 (청구서)
적용된 할인액
문서 메모
발급 처리 시각
▶itemsRevisionItem[]requiredexpandable발급 당시 품목 스냅샷
품목명
단위
수량
공급가액 (수량이 반영된 행 금액)
세액
▶recipientsRecipient[]requiredexpandable이메일 전달 수신자 (재전달 대상)
수신 이메일
수신자 이름
알림톡 전달 수신 번호
연체 여부 (청구서)
▶paymentProofsPaymentProof[]optionalexpandable계약에 연결된 입금내역
연결 관계 ID
연결된 계좌 거래 티켓 ID
입출금 방향
통화
거래 금액
거래 내용(적요)
거래 일시
연결 주체. SYSTEM은 그랜터 자동 연결
연결된 계좌 거래 티켓 ID 목록
▶changeLogsContractChangeLog[]requiredexpandable변경 이력 (오래된 순)
변경 이력 ID
변경 유형 (CREATED, STARTED, COMPLETED, CANCELED, RESUMED, DOCUMENT_ISSUED, DOCUMENT_REVISED, PAYMENT_STATUS_CHANGED, PAYMENT_PROOF_LINKED, PAYMENT_PROOF_UNLINKED, TAX_INVOICE_LINKED, TAX_INVOICE_UNLINKED, NOTIFICATION_SENT 등)
변경한 구성원 ID. 자동 처리면 null
변경 전 값 (변경과 관련된 필드만 채워짐)
변경 후 값 (변경과 관련된 필드만 채워짐)
기록 시각
▶agreementsContractAgreementSummary[]requiredexpandable계약에 연결된 계약서(전자서명)와 서명 상태 (최대 50건)
계약서 ID
계약서 번호
발급일
최신 발급본 ID. null이면 초안
목록에 표시되는 리비전 상태
발급본의 서명 진행 상태
서명 기한
▶linkedTaxInvoicesLinkedTaxInvoice[]requiredexpandable계약에 연결된 세금계산서
연결 관계 ID
세금계산서 티켓 ID
세금계산서 ID
금액
작성일시
거래처명
내용
연결 요청됐지만 아직 반영되지 않은 세금계산서 ID
curl -X GET https://app.granter.biz/api/public-docs/contracts/detail?contractId=1201 \ -H "Authorization: Basic <BASE64(API_KEY:)>"
{
"contract": {
"id": 1201,
"status": "PENDING",
"statusChangeSource": "USER",
"contactId": 3301,
"totalAmount": 3300000,
"currency": "KRW",
"defaultIssuerProfileId": 12,
"cancellationReason": null,
"cancellationReasonDetail": null,
"statusChangedAt": "2026-09-01T10:12:00",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"paymentConfirmedAt": null,
"paymentConfirmedByUserId": null
},
"contactName": "주식회사 샘플",
"participants": [{ "userId": 77, "role": "MANAGER" }],
"items": [
{
"id": 501,
"name": "홈페이지 유지보수",
"unit": "월",
"quantity": 1,
"supplyAmount": 3000000,
"taxAmount": 300000,
"currency": "KRW",
"sortOrder": 0
}
],
"documents": [
{
"document": {
"id": 9001,
"type": "INVOICE",
"documentNumber": "I260900001",
"draftRevisionId": null,
"latestIssuedRevisionId": 15001,
"transactionType": "IN",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"paymentConfirmedAt": null,
"paymentConfirmationBankTransactionIds": []
},
"revisions": [
{
"id": 15001,
"revisionNo": 1,
"status": "ISSUED",
"contactDisplayName": "주식회사 샘플",
"issuerDisplayName": "그랜터 주식회사",
"paymentAccount": { "bankName": "하나은행", "accountNumber": "123-456789-01001", "accountHolder": "그랜터 주식회사" },
"currency": "KRW",
"issueDate": "2026-09-01",
"dueDate": "2026-09-20",
"resolvedDiscountAmount": 0,
"memo": null,
"issuedAt": "2026-09-01T10:12:00",
"items": [
{ "id": 7001, "contractItemId": 501, "name": "홈페이지 유지보수", "unit": "월", "quantity": 1, "supplyAmount": 3000000, "taxAmount": 300000, "sortOrder": 0 }
],
"recipients": [{ "email": "billing@example.com", "name": "김담당", "sortOrder": 0 }],
"alimtalkRecipients": []
}
],
"paymentProofs": [],
"overdue": true
}
],
"paymentProofs": [],
"changeLogs": [
{
"id": 88010,
"changeType": "DOCUMENT_ISSUED",
"actorUserId": 77,
"beforeSnapshot": {},
"afterSnapshot": { "contractDocumentId": 9001, "documentType": "INVOICE", "documentNumber": "I260900001", "documentRevisionNo": 1 },
"createdAt": "2026-09-01T10:12:00"
}
],
"linkedBankTransactionTicketIds": [],
"agreements": [],
"linkedTaxInvoices": [],
"pendingTaxInvoiceIds": []
}POST /api/public-docs/contracts/payment-proofs
계좌 입금 거래를 계약의 입금내역으로 연결합니다. 연결만 하고 결제 상태는 바꾸지 않으므로, 입금 확인까지 하려면 `contracts-complete`를 사용하세요.
Request Fields
대기(PENDING) 또는 완료(COMPLETED) 상태의 계약에만 연결할 수 있습니다.
변경 전에 모든 거래를 먼저 확인합니다. 계좌 거래 티켓이 아니거나, 계약 청구서의 입출금 방향(청구서가 없으면 입금 IN)과 다르거나, 다른 계약에 이미 입금내역으로 연결된 거래가 하나라도 있으면 요청 전체를 거부합니다.
한 입금을 여러 계약에 나눠 반영하는 경우에만 `allowLinkedToOtherContract: true`로 다른 계약 연결 검사를 건너뜁니다.
이미 이 계약에 연결된 거래는 `unchangedBankTransactionTicketIds`로 돌려주고 다시 연결하지 않으므로, 같은 요청을 재시도해도 안전합니다.
한 번에 최대 20개까지 보낼 수 있습니다. 문서에 없는 필드는 400으로 거부합니다.
입금내역을 연결할 계약 ID
연결할 계좌 거래 티켓 ID 목록 (1~20개, `tickets` 조회의 BANK_TRANSACTION_TICKET ID)
`true`면 다른 계약에 이미 연결된 입금도 연결합니다. 기본값 false
Response Fields
요청한 입금내역이 모두 연결됐는지 여부
계약 ID
이번 요청으로 새로 연결한 계좌 거래 ID
이미 연결돼 있던 계좌 거래 ID
처리 후 계약에 연결된 전체 계좌 거래 ID
처리 후 계약 상태
처리 후 계약 결제 상태
처리 후 결제 확인 방식
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/payment-proofs \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"bankTransactionTicketIds": [5501]
}'{
"ok": true,
"contractId": 1201,
"newlyLinkedBankTransactionTicketIds": [5501],
"unchangedBankTransactionTicketIds": [],
"linkedBankTransactionTicketIds": [5501],
"contractStatus": "PENDING",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"verification": { "status": "verified" }
}DELETE /api/public-docs/contracts/payment-proofs
계약에 연결된 입금내역 연결을 해제합니다. 계좌 거래 원본은 삭제하지 않습니다.
Request Fields
연결돼 있지 않은 ID는 건너뛰고 `notLinkedBankTransactionTicketIds`로 돌려줍니다.
입금내역을 근거(BANK_TRANSACTION)로 결제 확인된 계약에서 연결을 해제하면 결제 상태가 미납(UNPAID)으로 돌아가고, 입금 확인으로 자동 완료됐던 계약은 대기로 돌아갑니다. 이때 `paymentStatusReverted`가 true입니다.
해제한 거래는 그랜터 자동 연결이 같은 계약에 다시 연결하지 않습니다.
한 번에 최대 20개까지 보낼 수 있습니다. 문서에 없는 필드는 400으로 거부합니다.
연결을 해제할 계약 ID
연결을 해제할 계좌 거래 티켓 ID 목록 (1~20개)
Response Fields
요청한 연결이 모두 해제됐는지 여부
계약 ID
연결을 해제한 계좌 거래 ID
처음부터 연결돼 있지 않아 건너뛴 ID
처리 후 남은 연결 계좌 거래 ID
입금내역 근거로 확인된 결제가 해제로 미납으로 돌아갔는지 여부
처리 후 계약 상태
처리 후 계약 결제 상태
처리 후 결제 확인 방식
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X DELETE https://app.granter.biz/api/public-docs/contracts/payment-proofs \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"bankTransactionTicketIds": [5501]
}'{
"ok": true,
"contractId": 1201,
"unlinkedBankTransactionTicketIds": [5501],
"notLinkedBankTransactionTicketIds": [],
"linkedBankTransactionTicketIds": [],
"paymentStatusReverted": true,
"contractStatus": "PENDING",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"verification": { "status": "verified" }
}POST /api/public-docs/contracts/complete
계약을 완료 처리합니다. 앱의 '완료 처리'와 같이 계약 결제 상태를 결제 완료(PAID)로 기록하며, 대기 계약은 자동으로 완료(COMPLETED)됩니다.
Request Fields
`bankTransactionTicketIds`를 보내면 그 입금내역을 먼저 연결한 뒤 입금내역 근거(BANK_TRANSACTION)로 결제 완료를 기록합니다. 보내지 않으면 앱의 '연결없이 완료처리'와 같이 수동 확인(MANUAL)으로 기록합니다.
입금내역 확인 규칙은 `contracts-payment-proofs-link`와 같습니다.
대기(PENDING) 계약만 완료할 수 있습니다. 이미 완료·결제 완료된 계약은 `unchanged=true`로 돌려주고 다시 바꾸지 않으며, 취소·초안 계약은 409로 거부합니다.
단, 이미 완료된 계약에 아직 연결되지 않은 `bankTransactionTicketIds`를 보내면 입금 근거 보강으로 보고 그 입금내역을 연결한 뒤, 기존에 연결된 입금내역과 합쳐 입금내역 근거(BANK_TRANSACTION)로 다시 기록합니다(수동 확인으로 완료된 계약도 BANK_TRANSACTION으로 바뀝니다).
견적서·청구서·거래명세서를 발급하지 않고 계약서(전자서명)만 있는 계약은 모든 서명이 끝나기 전까지 409(`AGREEMENT_SIGNATURE_PENDING`)로 거부합니다.
확인불가(입금 확인 생략) 청구서가 있는 계약도 같은 방식으로 완료합니다.
처리 결과는 변경 뒤 원본을 다시 조회해 확인하고 `ok`와 `verification.status`로 돌려줍니다. 입금내역 연결 뒤 결제 상태 변경이 실패하면 오류 응답의 `details.newlyLinkedBankTransactionTicketIds`에 이미 반영된 연결이 담깁니다.
완료 처리할 계약 ID
입금 근거로 연결할 계좌 거래 티켓 ID 목록 (최대 20개). 생략하면 수동 확인으로 완료
`true`면 다른 계약에 이미 연결된 입금도 근거로 연결합니다. 기본값 false
Response Fields
계약이 완료(COMPLETED)·결제 완료(PAID) 상태가 됐는지 여부
계약 ID
이미 완료된 계약이라 변경하지 않았는지 여부
처리 후 계약 상태
처리 후 계약 결제 상태
처리 후 결제 확인 방식
완료 처리 전에 새로 연결한 계좌 거래 ID
처리 후 연결된 전체 계좌 거래 ID
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/complete \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"bankTransactionTicketIds": [5501]
}'{
"ok": true,
"contractId": 1201,
"unchanged": false,
"contractStatus": "COMPLETED",
"paymentStatus": "PAID",
"paymentConfirmationMethod": "BANK_TRANSACTION",
"newlyLinkedBankTransactionTicketIds": [5501],
"linkedBankTransactionTicketIds": [5501],
"verification": { "status": "verified" }
}POST /api/public-docs/contracts/uncomplete
완료 처리한 계약을 대기(PENDING)·미결제(UNPAID) 상태로 되돌립니다. 앱에서 완료 처리 직후 누르는 '되돌리기'와 같습니다.
Request Fields
결제 상태를 미결제(UNPAID)로 바꾸고, 계약이 그래도 완료 상태로 남아 있으면 대기로 재개합니다.
연결된 입금내역은 유지됩니다. 연결도 끊으려면 `contracts-payment-proofs-unlink`를 사용하세요.
확인불가(입금 확인 생략)였던 청구서도 미결제로 돌아갑니다.
이미 대기·미결제 상태면 `unchanged=true`로 돌려줍니다. 취소·초안 계약은 409로 거부합니다.
완료를 되돌릴 계약 ID
Response Fields
계약이 대기(PENDING)·미결제 상태로 돌아갔는지 여부
계약 ID
이미 대기·미결제 상태라 변경하지 않았는지 여부
처리 후 계약 상태
처리 후 계약 결제 상태
처리 후 결제 확인 방식
연결된 계좌 거래 ID (되돌려도 연결은 유지)
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/uncomplete \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201
}'{
"ok": true,
"contractId": 1201,
"unchanged": false,
"contractStatus": "PENDING",
"paymentStatus": "UNPAID",
"paymentConfirmationMethod": null,
"linkedBankTransactionTicketIds": [5501],
"verification": { "status": "verified" }
}POST /api/public-docs/contracts/documents/resend
발급된 견적서·청구서·거래명세서의 최신 발급본을 기존 전달 수신자에게 다시 전달합니다. 거래처에 실제 이메일(선택 시 카카오 알림톡)이 발송됩니다.
Request Fields
`Idempotency-Key` header가 필수입니다. 네트워크 오류로 재시도할 때는 같은 값을 보내세요. 같은 키의 재요청은 10분 동안 한 번만 처리됩니다.
수신자는 바꿀 수 없습니다. 최신 발급본을 이메일로 전달했던 주소로만 다시 보냅니다. 처음 전달하거나 수신자를 바꾸려면 앱의 계약 화면에서 진행하세요. 정정 발급한 문서는 새 발급본을 한 번 전달하기 전까지 다시 전달할 수 없습니다.
이메일은 항상 포함됩니다. `sendAlimtalk: true`는 그 발급본을 알림톡으로도 전달했던 경우에만 쓸 수 있습니다.
발급된 문서가 여러 개면 `documentType` 또는 `documentId`로 다시 전달할 문서를 지정해야 합니다. 취소된 계약의 문서는 다시 전달하지 않습니다.
일부 수신자에게 발송이 실패해도 요청은 성공으로 끝납니다. 실제 발송 건수는 계약 변경 이력으로 확인해 `email.sentCount`·`alimtalk.sentCount`로 돌려주며, 발송 기록을 확인하지 못하면 `ok=false`, `verification.status=not_observed`입니다(같은 Idempotency-Key 재시도도 여기에 해당합니다).
test key 요청은 실제로 발송하지 않고 예시 응답만 돌려줍니다.
문서를 다시 전달할 계약 ID
다시 전달할 문서 종류. 발급된 문서가 여러 개면 documentType 또는 documentId가 필요합니다.
▶허용 값
다시 전달할 계약 문서 ID (`contracts-detail`의 `documents[].document.id`)
`true`면 기존 알림톡 수신 번호로도 다시 전달합니다. 기본값 false
Response Fields
이메일 발송 성공 기록을 확인했는지 여부
계약 ID
다시 전달한 계약 문서 ID
문서 종류
문서번호
다시 전달한 최신 발급본 ID
발급본 리비전 번호
이메일 수신자 (기존 전달 수신자)
▶emailChannelResultrequiredexpandable이메일 발송 결과
발송 성공 건수 (변경 이력 기준)
▶alimtalkChannelResultoptionalexpandablesendAlimtalk=true일 때만 포함되는 알림톡 발송 결과
기존 알림톡 수신 번호 수
발송 성공 건수 (변경 이력 기준)
▶verificationVerificationrequiredexpandable발송 기록 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/documents/resend \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"documentType": "INVOICE"
}'{
"ok": true,
"contractId": 1201,
"documentId": 9001,
"documentType": "INVOICE",
"documentNumber": "I260900001",
"revisionId": 15001,
"revisionNo": 1,
"emailRecipients": ["billing@example.com"],
"email": { "sentCount": 1 },
"verification": { "status": "verified" }
}POST /api/public-docs/contracts/create
[베타] 계약을 만들고 견적서·청구서·거래명세서를 발급합니다. 앱의 계약 작성 화면과 같은 순서로 계약 → 품목 → 문서별 발급 → (선택) 이메일·알림톡 전달까지 한 번에 처리합니다. 외부 ERP에서 확정한 계약을 그랜터로 넘겨 발급·입금 확인·세금계산서 연결을 이어서 할 때 사용합니다.
Request Fields
베타 API입니다. 베타 참여 회사에만 열려 있으며, 그 밖의 회사는 403 `CONTRACT_CREATE_BETA_NOT_ENABLED`를 받습니다. 참여는 그랜터 담당자에게 요청하세요.
`Idempotency-Key` header가 필수입니다. 같은 키는 24시간 동안 한 번만 처리하며, 다시 보내면 409 `IDEMPOTENCY_KEY_REUSED`입니다. 네트워크 오류로 결과를 모르면 `contracts` 조회로 계약이 생겼는지 먼저 확인하세요.
`issue`를 빼면 문서 없이 초안(DRAFT) 계약만 만듭니다. `issue.documentTypes`를 보내면 계약을 대기(PENDING)로 올리고 견적서 → 청구서 → 거래명세서 순으로 발급합니다.
문서의 발급자(우리 회사) 표기는 앱에 저장된 발급자 정보를 씁니다. 발급자 정보가 없으면 계약을 만들기 전에 409 `ISSUER_PROFILE_REQUIRED`로 멈춥니다.
`delivery`를 보내면 발급한 문서마다 지정한 이메일(필수)과 휴대폰 번호(선택, 카카오 알림톡)로 전달합니다. 전달이 실패해도 발급은 유지되며 `documents[].delivery.status=failed`로 알려 줍니다. 다시 보낼 때는 `contracts-documents-resend`를 쓰세요.
문서를 하나도 발급하기 전에 실패하면 만든 계약을 정리하고 오류를 돌려줍니다(`details.cleanup`). 이때는 새 Idempotency-Key로 다시 요청하세요. 일부 문서만 발급된 뒤 실패하면 발급본은 바꿀 수 없어 계약을 남기고 `CONTRACT_PARTIALLY_ISSUED`와 함께 발급된 문서·남은 문서 종류를 알려 줍니다.
계약서(전자서명)는 아직 이 API로 만들 수 없습니다. 세금계산서를 함께 처리하려면 `tax-invoices-issue`로 발행한 뒤 응답의 `id`를 `contracts-tax-invoices-link`로 이 계약에 연결하세요.
test key 요청은 아무것도 만들지 않고 예시 응답만 돌려줍니다.
거래처 ID (`contacts` 조회 결과)
통화 코드 (기본 KRW)
계약 담당자 사용자 ID (최대 10명). 첫 번째가 담당자, 나머지는 참조자입니다. `people` 조회의 사용자 ID를 쓰세요.
계약 품목 (1~100개). 문서에 같은 순서로 실립니다.
품목명 (200자 이하)
단위 (예: 월, 개)
수량 (0보다 큰 수)
공급가액 (원 단위 정수)
세액 (원 단위 정수, 면세면 0)
할인. `type`=AMOUNT(금액) 또는 RATE(비율, 0~100), `value`=할인 값
문서 비고 (1000자 이하)
문서 언어. 기본 KO
▶허용 값
발급 설정. 빼면 초안 계약만 만듭니다.
발급할 문서 종류 (1개 이상)
▶허용 값
발급일 (기본 오늘, 한국 시간)
납부기한. 청구서(INVOICE)를 발급할 때만 보낼 수 있습니다.
문서에 표기할 입금 계좌 `{ bankName, accountNumber, accountHolder? }`
`true`면 입금 확인이 필요 없는 청구서로 발급합니다. 청구서 전용이며 `paymentAccount`와 함께 보낼 수 없습니다.
문서에 표기할 종사업장번호 (32자 이하)
전달 이메일 (delivery를 보내면 1~20개 필수)
카카오 알림톡을 받을 휴대폰 번호 (최대 20개, 01로 시작하는 10~11자리)
Response Fields
계약 상태와 발급본을 원본 재조회로 확인했는지 여부
만든 계약 ID
처리 후 계약 상태 (문서를 발급하면 PENDING, 아니면 DRAFT)
계약 총액 (품목 공급가액+세액 합계에서 할인 차감)
통화 코드
만든 계약 품목 ID (요청 items 순서)
▶documentsIssuedContractDocument[]requiredexpandable발급한 문서 (견적서 → 청구서 → 거래명세서 순)
계약 문서 ID
문서 종류
문서번호
발급본 ID
▶deliveryDeliveryResultrequiredexpandable전달 결과
전달 결과. delivery를 보내지 않았으면 skipped, 전달 요청이 접수되면 requested
requested일 때 전달한 이메일
requested일 때 알림톡을 보낸 휴대폰 번호
failed일 때 오류 코드
failed일 때 오류 메시지 (발급은 유지됨)
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/create \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contactId": 3301,
"managerUserIds": [77],
"items": [
{ "name": "홈페이지 유지보수", "unit": "월", "quantity": 1, "supplyAmount": 3000000, "taxAmount": 300000 }
],
"issue": {
"documentTypes": ["INVOICE"],
"issueDate": "2026-10-20",
"dueDate": "2026-10-31",
"paymentAccount": { "bankName": "하나은행", "accountNumber": "123-456789-01001", "accountHolder": "그랜터 주식회사" },
"delivery": { "emailRecipients": ["billing@example.com"] }
}
}'{
"ok": true,
"contractId": 1201,
"contractStatus": "PENDING",
"totalAmount": 3300000,
"currency": "KRW",
"contractItemIds": [501],
"documents": [
{
"documentId": 9001,
"documentType": "INVOICE",
"documentNumber": "I261000001",
"revisionId": 15001,
"delivery": {
"status": "requested",
"emailRecipients": ["billing@example.com"],
"alimtalkRecipients": []
}
}
],
"verification": { "status": "verified" }
}POST /api/public-docs/contracts/tax-invoices
세금계산서를 계약에 연결합니다. `tax-invoices-issue`로 발행한 세금계산서를 계약과 묶어 계약 상세에서 함께 보이게 할 때 사용합니다.
Request Fields
`taxInvoiceIds`는 원본 세금계산서 ID입니다. `tax-invoices-issue` 응답의 `id`를 그대로 넣으세요(계약 상세 `linkedTaxInvoices[].taxInvoiceId`와 같은 값).
발행 직후처럼 그랜터에 세금계산서 티켓이 아직 없으면 연결 요청만 받아 두었다가 티켓이 생기면 자동으로 연결합니다. 이 경우 `taxInvoices[].status`가 `pending`입니다.
한 번에 최대 100개까지 보낼 수 있습니다. 연결 후 다시 조회해 세금계산서별로 `linked`(연결 완료)·`pending`(대기)·`not_observed`(확인 안 됨)를 돌려줍니다.
test key 요청은 실제로 연결하지 않고 예시 응답만 돌려줍니다.
세금계산서를 연결할 계약 ID
연결할 원본 세금계산서 ID (1~100개)
Response Fields
보낸 세금계산서가 모두 연결 완료 또는 대기로 확인됐는지 여부
계약 ID
▶taxInvoicesTaxInvoiceLinkResult[]requiredexpandable보낸 세금계산서별 결과
원본 세금계산서 ID
linked=연결 완료, pending=티켓 생성 대기(생기면 자동 연결), not_observed=재조회에서 확인 안 됨
▶linkedTaxInvoicesLinkedTaxInvoice[]requiredexpandable처리 후 계약에 연결된 세금계산서 전체
연결 관계 ID
세금계산서 티켓 ID
세금계산서 ID
금액
작성일시
거래처명
내용
처리 후 연결 대기 중인 세금계산서 ID 전체
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X POST https://app.granter.biz/api/public-docs/contracts/tax-invoices \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"taxInvoiceIds": [501]
}'{
"ok": true,
"contractId": 1201,
"taxInvoices": [{ "taxInvoiceId": 501, "status": "pending" }],
"linkedTaxInvoices": [],
"pendingTaxInvoiceIds": [501],
"verification": { "status": "verified" }
}DELETE /api/public-docs/contracts/tax-invoices
계약에 연결된 세금계산서를 해제합니다. 연결이 끝난 관계와 대기 중인 연결 요청을 함께 지우며, 계약 변경 이력에 남습니다.
Request Fields
`taxInvoiceIds`는 원본 세금계산서 ID입니다(`contracts-tax-invoices-link`에 보낸 값과 같습니다).
해제 후 다시 조회해 아직 남아 있는 ID를 `remainingTaxInvoiceIds`로 알려 줍니다.
test key 요청은 실제로 해제하지 않고 예시 응답만 돌려줍니다.
세금계산서 연결을 해제할 계약 ID
해제할 원본 세금계산서 ID (1~100개)
Response Fields
보낸 세금계산서가 모두 해제됐는지 여부
계약 ID
해제를 확인한 세금계산서 ID
해제 후에도 연결 또는 대기로 남아 있는 세금계산서 ID
▶linkedTaxInvoicesLinkedTaxInvoice[]requiredexpandable처리 후 계약에 연결된 세금계산서 전체
연결 관계 ID
세금계산서 티켓 ID
세금계산서 ID
금액
작성일시
거래처명
내용
처리 후 연결 대기 중인 세금계산서 ID 전체
▶verificationVerificationrequiredexpandable반영 확인 결과
변경 뒤 원본 재조회로 반영을 확인한 결과
curl -X DELETE https://app.granter.biz/api/public-docs/contracts/tax-invoices \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"contractId": 1201,
"taxInvoiceIds": [501]
}'{
"ok": true,
"contractId": 1201,
"unlinkedTaxInvoiceIds": [501],
"remainingTaxInvoiceIds": [],
"linkedTaxInvoices": [],
"pendingTaxInvoiceIds": [],
"verification": { "status": "verified" }
}GET /api/public-docs/inventory-products
품목명, 단가, 통화, 추가 속성으로 구성된 품목 마스터를 조회합니다.
Request Fields
요청 body는 사용하지 않습니다.
직접 호출 시 `limit`, `lastSeenId` query string을 사용할 수 있습니다.
조회 건수 제한
페이지네이션 기준 ID
Response Fields
▶[]InventoryProductrequiredexpandableBE `/inventory-products` 원본 응답 배열의 각 원소
품목 ID
품목명
단가
통화 코드
▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable추가 속성 목록
추가 속성 ID
속성명
속성값
curl -X GET https://app.granter.biz/api/public-docs/inventory-products \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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을 사용할 수 있습니다.
조회 건수 제한
페이지네이션 기준 ID
Response Fields
▶[]InventoryStockrequiredexpandableBE `/inventories` 원본 응답 배열의 각 원소
재고 엔트리 ID
품목 ID
품목명
단가
현재 재고 수량
통화 코드
생성 시각
수정 시각
메시지 개수
▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable추가 속성 목록
추가 속성 ID
속성명
속성값
curl -X GET https://app.granter.biz/api/public-docs/inventories \ -H "Authorization: Basic <BASE64(API_KEY:)>"
[
{
"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`으로 근무/휴가를 구분할 수 있습니다.
조회 시작일
조회 종료일
조회 대상 유저 ID 목록
기록 타입 필터. WORK: 근무만, LEAVE: 휴가만, 미입력 시 전체
Response Fields
▶[]TimeCardRecordrequiredexpandable근무/휴가 기록 배열
▶timeCardTimeCardrequiredexpandable타임카드 정보
워크스페이스 ID
유저 ID
기준일
시작 일시
종료 일시
생성 일시
수정 일시
▶workRecordWorkRecord | nulloptionalexpandable근무 기록 (휴가인 경우 null)
근무 기록 ID
▶clockInLocationClockLocationrequiredexpandable출근 위치
IP 주소
주소
상세 주소
위도
경도
허용 반경 (m)
▶clockOutLocationClockLocation | nulloptionalexpandable퇴근 위치
IP 주소
주소
상세 주소
위도
경도
허용 반경 (m)
원격 근무 여부
기본 휴게 시작 일시
기본 휴게 종료 일시
▶additionalBreakTimesWorkBreakTime[]requiredexpandable추가 휴게시간 목록
추가 휴게 시작 일시
추가 휴게 종료 일시
▶leaveRecordLeaveRecord | nulloptionalexpandable휴가 기록 (근무인 경우 null)
휴가 기록 ID
결재자 유저 ID
휴가 사유
승인 상태
승인 일시
반려 일시
반려 사유
생성 일시
수정 일시
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"
}'[
{
"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`는 선택값이며, 미입력 시 백엔드 기본 기준일로 계산합니다.
잔여 연차를 계산할 기준일
Response Fields
▶[]LeaveBalancerequiredexpandable구성원별 잔여 연차 배열
워크스페이스 유저 ID
유저 ID
무제한 연차 여부. true이면 나머지 일수 필드는 null일 수 있습니다.
정책과 입사일 기준으로 계산한 이론적 발생 연차 일수
수동 조정, 사용, 소멸을 반영한 가감 일수 합계
입사일. 휴가 정책 승인자가 아니거나 급여 정보가 없으면 null입니다.
퇴사일. 휴가 정책 승인자가 아니거나 급여 정보가 없으면 null입니다.
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"
}'[
{
"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일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.
휴가 사용, 사용 취소, 소멸, 수동 조정 내역이 함께 반환됩니다.
조회 시작일
조회 종료일
Response Fields
▶[]LeaveHistoryrequiredexpandable연차 변경 이력 배열
연차 변경 이력 ID
대상 유저 ID
변경을 요청한 유저 ID
변경 일수
연차 변경 유형
변경 발생일
소멸 예정일
연관 타임카드 ID
메모
생성 일시
수정 일시
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"
}'[
{
"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`는 필수입니다.
`startDate`, `endDate`는 2000-01-01 ~ 2099-12-31 안의 실제 날짜여야 하며, 조회 기간은 시작 월과 종료 월을 포함해 최대 60개월입니다. 벗어나면 400으로 응답합니다.
공공데이터포털 또는 대체 공휴일 소스에서 공휴일을 조회하며, 소스 장애 시 `enabled=false`로 응답합니다.
조회 시작일
조회 종료일
Response Fields
공휴일 조회 가능 여부
조회 실패 사유
공휴일 날짜 목록
▶holidaysHoliday[]requiredexpandable공휴일 상세 목록
공휴일 날짜
공휴일 이름
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"
}'{
"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 정수 정밀도 손실을 막기 위해 숫자만 포함한 문자열로 전달하세요.
카드 별칭/이름
카드사 enum. 수기 카드는 CUSTOM_CARD 권장
카드번호. 숫자만 포함한 문자열로 전달
Response Fields
▶[]AssetrequiredexpandableBE `/assets` 원본 응답 배열의 각 원소
자산 ID
자산 타입
자산 번호
워크스페이스 ID
자산명
별칭
금융기관 코드
금융기관명
업종
업종명
숨김 여부
활성 여부
휴면 여부
휴면 가능 여부
무료 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
자동 할당 여부
▶scrapHistoryScrapHistory | nullrequiredexpandable자산별 마지막 수집 이력. 수집 이력이 없으면 null
마지막 수집 요청 시각
마지막 수집 성공 시각
마지막 수집 실패 시각
▶cardAssetCardInfooptionalexpandable카드 자산 정보
만료 연도
만료 월
한도 금액
사용 금액
잔여 한도
이전 카드 번호
▶bankAccountAssetBankAccountInfooptionalexpandable계좌 자산 정보
계좌 잔액
원본 계좌 잔액
통화 코드
조회 시작일
조회 종료일
계좌 번호
계좌명
별칭
계좌 유형
거래내역 보유 여부
▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable홈택스 자산 정보
홈택스 자산 카테고리
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
연락처
업태
종목
▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable증권 자산 정보
총액(원화)
예수금(원화)
외화예수금(원화)
▶foreignDepositsForeignDeposit[]requiredexpandable외화예수금 보유 목록
외화예수금 ID
통화 코드
금액
생성 시각
보유 주식 평가액 합계(원화)
계좌번호
▶productsProduct[]requiredexpandable보유 투자상품
상품 ID
상품 유형 코드
상품 유형명
상품명
상품 코드
수량
통화 코드
현재 금액(원화)
현재 금액
평가 금액(원화)
평가 금액
평가 손익(원화)
평가 손익
수익률
생성 시각
▶customAssetAssetCustomInfooptionalexpandable커스텀 자산 정보
커스텀 자산 유형
자산 번호
금액
▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable이커머스 스토어 계정 정보
스토어 사용자명
OTP 인증 여부
생성 시각
수정 시각
비밀번호 보유 여부
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"
}'{
"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)로 처리됩니다.
은행 enum. 수기 계좌는 CUSTOM_BANK_ACCOUNT 권장
계좌명
계좌 별칭
계좌번호. 문자열이면 하이픈 포함 가능
초기 잔액
통화 코드. 기본 KRW
계좌 유형. DEPOSIT, FOREIGN, FUND, LOAN, INSURANCE, PENSION, CASH 등
Response Fields
▶[]AssetrequiredexpandableBE `/assets` 원본 응답 배열의 각 원소
자산 ID
자산 타입
자산 번호
워크스페이스 ID
자산명
별칭
금융기관 코드
금융기관명
업종
업종명
숨김 여부
활성 여부
휴면 여부
휴면 가능 여부
무료 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
자동 할당 여부
▶scrapHistoryScrapHistory | nullrequiredexpandable자산별 마지막 수집 이력. 수집 이력이 없으면 null
마지막 수집 요청 시각
마지막 수집 성공 시각
마지막 수집 실패 시각
▶cardAssetCardInfooptionalexpandable카드 자산 정보
만료 연도
만료 월
한도 금액
사용 금액
잔여 한도
이전 카드 번호
▶bankAccountAssetBankAccountInfooptionalexpandable계좌 자산 정보
계좌 잔액
원본 계좌 잔액
통화 코드
조회 시작일
조회 종료일
계좌 번호
계좌명
별칭
계좌 유형
거래내역 보유 여부
▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable홈택스 자산 정보
홈택스 자산 카테고리
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
연락처
업태
종목
▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable증권 자산 정보
총액(원화)
예수금(원화)
외화예수금(원화)
▶foreignDepositsForeignDeposit[]requiredexpandable외화예수금 보유 목록
외화예수금 ID
통화 코드
금액
생성 시각
보유 주식 평가액 합계(원화)
계좌번호
▶productsProduct[]requiredexpandable보유 투자상품
상품 ID
상품 유형 코드
상품 유형명
상품명
상품 코드
수량
통화 코드
현재 금액(원화)
현재 금액
평가 금액(원화)
평가 금액
평가 손익(원화)
평가 손익
수익률
생성 시각
▶customAssetAssetCustomInfooptionalexpandable커스텀 자산 정보
커스텀 자산 유형
자산 번호
금액
▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable이커머스 스토어 계정 정보
스토어 사용자명
OTP 인증 여부
생성 시각
수정 시각
비밀번호 보유 여부
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"
}'{
"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를 조회하세요.
대상 카드 자산 ID
카드 사용 내역 배열
결제 일시
가맹점명
결제 금액
결제 상태. 기본 NORMAL
오류 거래 표시
Response Fields
▶[]TicketrequiredexpandableBE `/tickets` 원본 응답 배열의 각 원소
티켓 ID
워크스페이스 ID
거래/증빙 내용
거래 금액
입출금 방향
거래 일시
수정 거래 일시
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
이상치 상태
티켓 상태
▶ticketTagsTicketTag[]optionalexpandable티켓에 붙은 태그(다중 태그) 목록. 목록 V2·단건 조회 응답에 있습니다
태그 ID (`ticket-tags` 의 id)
태그 이름
▶ticketTagGroupTicketTagGroup | nullrequiredexpandable태그 그룹. 그룹이 없으면 null
태그 그룹 ID
태그 그룹 이름
(deprecated) 1차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 1차 태그 ID
거래처명
거래처 ID
(deprecated) 2차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 2차 태그 ID
포함 여부
계정과목을 지정한 주체. `USER`는 사람이 확정한 값, 그 밖(`AI_INFERENCE`·`LLM_INFERENCE`·`PATTERN_CLASSIFICATION`·`CACHE_INFERENCE`·`PAYMENT_PROOF` 등)은 자동 분류입니다
포함 여부를 정한 주체. 값의 의미는 `expenseCategoryUpdateSource`와 같습니다
▶usersUserResponse[]requiredexpandable연결 유저 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesMessage[]optionalexpandable댓글·변경 기록 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답(ticketReferences가 있는 응답)에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
메시지 ID
티켓 ID
▶userUserResponserequiredexpandable작성자
유저 ID
유저 이름
유저 이메일
삭제 여부
작성자 ID
작성자 이름
메시지 내용
메시지 타입
생성 시각
삭제 시각
댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서는 commentCount와 같은 값입니다.
▶attachmentsAttachment[]optionalexpandable첨부파일 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
첨부파일 ID
티켓 ID
파일명
업로드 URL
MIME 타입
첨부파일 수
삭제되지 않은 댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
은행거래 ID
워크스페이스 ID
거래 방향
설명
거래 후 잔액
원본 거래 후 잔액
거래 금액
원본 거래 금액
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
거래 상대방
설명 분류
내용
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶issuerobjectrequiredexpandable발행자
이메일
유저 ID
삭제 여부
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
영수/청구 구분
대표 품목
비고
상태
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
수정사유
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
결제 상태
다른 거래·증빙과 연결되어 있는지 여부. 목록 V2 응답과 티켓 단건 조회 API는 결재·계약 연결을 세지 않습니다.
연결된 거래·증빙 수. isConnected와 같은 기준으로 셉니다.
▶ticketReferencesTicketReference[]optionalexpandable연결내역(결재·계약 연결 포함). 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
연결 상대 ID
연결 상대 타입(TicketType 또는 WORKFLOW·CONTRACT·PG_SETTLEMENT 같은 연결 대상 타입)
연결 목적(예: TAX_INVOICE_PAYMENT_MANAGEMENT, DEDUPLICATE_CHECK_CARD_USAGE)
세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부
생성 시각
부모 티켓 ID
분할 티켓 여부
매입 상태
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
할부개월
거래구분
거래일시
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
거래일시
매입일
매입 금액
총 수수료
가맹점 수수료
포인트 수수료
기타 수수료
지급 금액
지급 예정일
▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable포스기/CREFIA 정산 상세
정산 상세 ID
정산 ID
포스기/CREFIA 자산 ID
항목명
금액
입출금 방향
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
수기거래 ID
통화 코드
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
품목명
수량
세액
단가
공급가액
단가의 부가세 포함 여부
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
자산 ID
조직 (COUPANG, NAVER 등)
별칭
정산 ID
정산일
정산 비율
항목명
금액
정산 상세 타입
입출금 방향
추천 티켓 여부
과세 유형
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"
}
]
}'{
"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를 조회하세요.
대상 계좌 자산 ID
계좌 거래 배열
거래 일시
거래 방향
적요/거래 내용
거래 금액
거래 후 잔액
거래 상대방
오류 거래 표시
Response Fields
▶[]TicketrequiredexpandableBE `/tickets` 원본 응답 배열의 각 원소
티켓 ID
워크스페이스 ID
거래/증빙 내용
거래 금액
입출금 방향
거래 일시
수정 거래 일시
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
이상치 상태
티켓 상태
▶ticketTagsTicketTag[]optionalexpandable티켓에 붙은 태그(다중 태그) 목록. 목록 V2·단건 조회 응답에 있습니다
태그 ID (`ticket-tags` 의 id)
태그 이름
▶ticketTagGroupTicketTagGroup | nullrequiredexpandable태그 그룹. 그룹이 없으면 null
태그 그룹 ID
태그 그룹 이름
(deprecated) 1차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 1차 태그 ID
거래처명
거래처 ID
(deprecated) 2차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 2차 태그 ID
포함 여부
계정과목을 지정한 주체. `USER`는 사람이 확정한 값, 그 밖(`AI_INFERENCE`·`LLM_INFERENCE`·`PATTERN_CLASSIFICATION`·`CACHE_INFERENCE`·`PAYMENT_PROOF` 등)은 자동 분류입니다
포함 여부를 정한 주체. 값의 의미는 `expenseCategoryUpdateSource`와 같습니다
▶usersUserResponse[]requiredexpandable연결 유저 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesMessage[]optionalexpandable댓글·변경 기록 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답(ticketReferences가 있는 응답)에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
메시지 ID
티켓 ID
▶userUserResponserequiredexpandable작성자
유저 ID
유저 이름
유저 이메일
삭제 여부
작성자 ID
작성자 이름
메시지 내용
메시지 타입
생성 시각
삭제 시각
댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서는 commentCount와 같은 값입니다.
▶attachmentsAttachment[]optionalexpandable첨부파일 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
첨부파일 ID
티켓 ID
파일명
업로드 URL
MIME 타입
첨부파일 수
삭제되지 않은 댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
은행거래 ID
워크스페이스 ID
거래 방향
설명
거래 후 잔액
원본 거래 후 잔액
거래 금액
원본 거래 금액
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
거래 상대방
설명 분류
내용
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶issuerobjectrequiredexpandable발행자
이메일
유저 ID
삭제 여부
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
영수/청구 구분
대표 품목
비고
상태
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
수정사유
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
결제 상태
다른 거래·증빙과 연결되어 있는지 여부. 목록 V2 응답과 티켓 단건 조회 API는 결재·계약 연결을 세지 않습니다.
연결된 거래·증빙 수. isConnected와 같은 기준으로 셉니다.
▶ticketReferencesTicketReference[]optionalexpandable연결내역(결재·계약 연결 포함). 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
연결 상대 ID
연결 상대 타입(TicketType 또는 WORKFLOW·CONTRACT·PG_SETTLEMENT 같은 연결 대상 타입)
연결 목적(예: TAX_INVOICE_PAYMENT_MANAGEMENT, DEDUPLICATE_CHECK_CARD_USAGE)
세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부
생성 시각
부모 티켓 ID
분할 티켓 여부
매입 상태
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
할부개월
거래구분
거래일시
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
거래일시
매입일
매입 금액
총 수수료
가맹점 수수료
포인트 수수료
기타 수수료
지급 금액
지급 예정일
▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable포스기/CREFIA 정산 상세
정산 상세 ID
정산 ID
포스기/CREFIA 자산 ID
항목명
금액
입출금 방향
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
수기거래 ID
통화 코드
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
품목명
수량
세액
단가
공급가액
단가의 부가세 포함 여부
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
자산 ID
조직 (COUPANG, NAVER 등)
별칭
정산 ID
정산일
정산 비율
항목명
금액
정산 상세 타입
입출금 방향
추천 티켓 여부
과세 유형
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": "샘플 거래처"
}
]
}'{
"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를 보장하지 않으므로 빈 배열일 수 있습니다.
생성할 수기관리 전표 배열. 최대 100건
거래처 ID
매출/매입 방향
수기거래 유형
거래 일시
거래 금액
적요/거래 내용
통화 코드. 기본 KRW
추가 설명. 기본 빈 문자열
계정과목 ID
붙일 태그 ID 목록(`ticket-tags` API 의 id). 최대 100개
(deprecated) 1차 태그 ID — 지원하지 않습니다(2026-10-03~ 400). `ticketTagIds`를 쓰세요
(deprecated) 2차 태그 ID — 지원하지 않습니다(2026-10-03~ 400). `ticketTagIds`를 쓰세요
품목 배열
품목명
수량
단가
세액
공급가액. 생략하면 단가 × 수량을 원 단위로 절사해 저장한다
단가의 부가세 포함 여부 (기본 false)
Response Fields
수기관리 전표 생성 요청 성공 여부
생성을 요청한 전표 수
backend 생성 응답에서 확인된 수기관리 티켓 ID 목록. 응답 body가 없으면 빈 배열
▶ticketsTicket[]requiredexpandablebackend가 생성 티켓을 응답한 경우의 공개 티켓 목록. 응답 body가 없으면 빈 배열
▶[]TicketrequiredexpandableBE `/tickets` 원본 응답 배열의 각 원소
티켓 ID
워크스페이스 ID
거래/증빙 내용
거래 금액
입출금 방향
거래 일시
수정 거래 일시
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
계정과목 ID
계정과목명
부가 정보
설명
코드
카테고리 타입
숨김 여부
비용 유형
즐겨찾기 여부
워크스페이스 ID
기본 과세 유형
이상치 상태
티켓 상태
▶ticketTagsTicketTag[]optionalexpandable티켓에 붙은 태그(다중 태그) 목록. 목록 V2·단건 조회 응답에 있습니다
태그 ID (`ticket-tags` 의 id)
태그 이름
▶ticketTagGroupTicketTagGroup | nullrequiredexpandable태그 그룹. 그룹이 없으면 null
태그 그룹 ID
태그 그룹 이름
(deprecated) 1차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 1차 태그 ID
거래처명
거래처 ID
(deprecated) 2차 태그명 — 2026-10-01 이후 갱신되지 않습니다. `ticketTags`를 쓰세요
(deprecated) 2차 태그 ID
포함 여부
계정과목을 지정한 주체. `USER`는 사람이 확정한 값, 그 밖(`AI_INFERENCE`·`LLM_INFERENCE`·`PATTERN_CLASSIFICATION`·`CACHE_INFERENCE`·`PAYMENT_PROOF` 등)은 자동 분류입니다
포함 여부를 정한 주체. 값의 의미는 `expenseCategoryUpdateSource`와 같습니다
▶usersUserResponse[]requiredexpandable연결 유저 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
▶messagesMessage[]optionalexpandable댓글·변경 기록 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답(ticketReferences가 있는 응답)에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
메시지 ID
티켓 ID
▶userUserResponserequiredexpandable작성자
유저 ID
유저 이름
유저 이메일
삭제 여부
작성자 ID
작성자 이름
메시지 내용
메시지 타입
생성 시각
삭제 시각
댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서는 commentCount와 같은 값입니다.
▶attachmentsAttachment[]optionalexpandable첨부파일 목록. [Deprecated · 티켓 조회 API 목록 응답] 기존(V1) 목록 응답의 이 필드는 곧 삭제될 예정이며, 목록 V2 응답에는 이미 없습니다. 티켓 단건 조회 API에서는 계속 제공합니다.
첨부파일 ID
티켓 ID
파일명
업로드 URL
MIME 타입
첨부파일 수
삭제되지 않은 댓글 수. 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
결제일
가맹점명
가맹점 주소
사용 금액
취소 금액
할인 금액
부가세
할부 개월
결제 방식
결제 상태
승인번호
가맹점 사업자번호
원본 금액
통화 코드
환율
매입일
수수료
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
은행거래 ID
워크스페이스 ID
거래 방향
설명
거래 후 잔액
원본 거래 후 잔액
거래 금액
원본 거래 금액
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
거래 상대방
설명 분류
내용
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶issuerobjectrequiredexpandable발행자
이메일
유저 ID
삭제 여부
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
영수/청구 구분
대표 품목
비고
상태
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
수정사유
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
결제 상태
다른 거래·증빙과 연결되어 있는지 여부. 목록 V2 응답과 티켓 단건 조회 API는 결재·계약 연결을 세지 않습니다.
연결된 거래·증빙 수. isConnected와 같은 기준으로 셉니다.
▶ticketReferencesTicketReference[]optionalexpandable연결내역(결재·계약 연결 포함). 목록 V2 응답과 티켓 단건 조회 API에서 제공합니다.
연결 상대 ID
연결 상대 타입(TicketType 또는 WORKFLOW·CONTRACT·PG_SETTLEMENT 같은 연결 대상 타입)
연결 목적(예: TAX_INVOICE_PAYMENT_MANAGEMENT, DEDUPLICATE_CHECK_CARD_USAGE)
세금계산서를 실제 티켓 연결 없이 완료 처리했는지 여부
생성 시각
부모 티켓 ID
분할 티켓 여부
매입 상태
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
할부개월
거래구분
거래일시
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
카드사
카드명
카드 타입
카드번호
승인번호
거래일시
매입일
매입 금액
총 수수료
가맹점 수수료
포인트 수수료
기타 수수료
지급 금액
지급 예정일
▶merchantSettlementDetailTransactionMerchantSettlementDetailTransactionoptionalexpandable포스기/CREFIA 정산 상세
정산 상세 ID
정산 ID
포스기/CREFIA 자산 ID
항목명
금액
입출금 방향
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
수기거래 ID
통화 코드
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
품목명
수량
세액
단가
공급가액
단가의 부가세 포함 여부
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
자산 ID
조직 (COUPANG, NAVER 등)
별칭
정산 ID
정산일
정산 비율
항목명
금액
정산 상세 타입
입출금 방향
추천 티켓 여부
과세 유형
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
}
]
}
]
}'{
"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입니다. 안전한 재시도가 필요하면 호출 단위로 고정된 값을 직접 넣으세요.
삭제할 수기관리 티켓 ID 배열. 최대 100건
Response Fields
수기관리 전표 삭제 성공 여부
삭제된 수기관리 티켓 ID 목록
티켓에서 확인해 실제 upstream 삭제에 사용한 내부 수기거래 ID 목록
삭제된 전표 수
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]
}'{
"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 전달 전 숫자만 남깁니다.
발행 구분. 기본 정발행
과세 유형. 기본 TAX
공급받는 자 구분. 기본 BUSINESS
영수/청구 구분. 기본 RECEIPT
작성일자
공급가액
세액. 생략 시 과세 건은 공급가액의 10%
합계금액. 생략 시 공급가액 + 세액
비고
공급자 사업자등록번호
공급자 상호
공급자 대표자명. 생략 시 companyName 사용
공급자 이메일
공급받는 자 사업자등록번호
공급받는 자 상호
공급받는 자 대표자명. 생략 시 companyName 사용
공급받는 자 이메일
품목 배열. 생략 시 공급가액 기준 1건 자동 생성
Response Fields
세금계산서 ID
발행 요청 UUID
▶accountTicketAssetrequiredexpandable발행에 사용된 홈택스 자산
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶trusteeTaxInvoiceUser | nulloptionalexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
세금계산서 거래 타입
전자세금계산서 거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
총 건수
현금 금액
수표 금액
어음 금액
외상미수금 금액
영수/청구 구분
대표 품목
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
비고
발행 상태
발행 결과 코드
발행 결과 메시지
수입신고번호
통신 시작일
통신 종료일
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
수정사유
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": ""
}
]
}'{
"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 전달 전 숫자만 남깁니다.
거래일시. upstream에는 YYYY-MM-DDTHH:mm:ss로 정규화
거래 내용. 기본 현금영수증
용도. 기본 EXPENSE_PROOF
과세 형태. 기본 TAXABLE
총금액
공급가액. 생략 시 자동 계산
부가세. 생략 시 자동 계산
봉사료. 기본 0
발행자 사업자등록번호
발행자 상호
구매자 식별번호
구매자 이름/상호
Response Fields
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
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": "샘플 거래처"
}
}'{
"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)로 전달하세요.
금액 필드는 음수도 받습니다(마이너스 세금계산서). 다만 음수 금액으로 발급하면 가산세가 발생할 수 있으므로, 이미 발행한 세금계산서를 정정하려는 경우에는 `tax-invoices-modify-issue`, `tax-invoices-cancel-issue`로 수정세금계산서를 발행하세요.
`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` 응답의 필드 누락만으로 판단하지 마세요.
거래처 담당자 이름은 세금계산서 발행 필드가 아닙니다. 세금계산서에 실리는 연락처는 `supplier`·`contractor`의 휴대전화(`phone`)·전화(`tel`)·이메일(`email`, `email2`)뿐입니다.
거래처 담당자는 세금계산서마다가 아니라 거래처 단위로 관리합니다. `contacts-managers-create`, `contacts-managers-update`, `contacts-managers-delete`로 관리하고, 세금계산서와는 티켓의 `contactId`(거래처 ID)로 이어집니다. 담당자 정보는 공급받는자(거래 상대방)에게 보이지 않는 그랜터 내부 관리 정보입니다.
그랜터에서 발행한 세금계산서는 홈택스 전송이 끝난 뒤에야 티켓으로 조회됩니다. 그 전에 거래처와 담당자를 찾으려면 거래 상대방(공급받는자) 사업자등록번호 `contractor.registrationNumber`로 `contacts`에서 거래처를 찾으세요.
발행 타입. 일반적으로 `정발행`을 사용합니다.
과세 유형
▶허용 값
청구 방향. 일반적으로 `정과금`을 사용합니다.
작성일자. 반복발행이면 `null`입니다.
발행 스케줄 타입
▶허용 값
반복발행(RECURRING)일 때 필요한 발행 일자 (1~31)
반복발행(RECURRING)일 때 필요한 종료일
영수/청구 구분
▶허용 값
공급가액. 음수 가능
세액. 음수 가능
합계금액. 음수 가능
현금 금액
수표 금액
어음 금액
외상미수금 금액. 결제수단 금액 합계는 totalAmount와 같아야 합니다.
세금계산서 상단 비고란에 표시되는 비고
공급받는자 유형
▶허용 값
강제 발행 여부
명세 작성 여부
그랜터 내부 메모. 세금계산서 품목/비고에는 표시되지 않습니다.
공급자 사업자등록번호
공급자 회사명
공급자 대표자명
공급자 이메일
공급자 보조 이메일
발행 세금계산서 담당자 연락처에 반영되는 공급자 연락처
기존 호환용 연락처 alias. tel 미입력 시 연락처로 사용되며, tel과 함께 보내면 tel이 우선됩니다.
공급자 업태
공급자 종목
공급자 사업장 주소
공급받는자 사업자등록번호
공급받는자 회사명
공급받는자 대표자명
공급받는자 이메일
공급받는자 보조 이메일
발행 세금계산서 담당자 연락처에 반영되는 공급받는자 연락처
기존 호환용 연락처 alias. tel 미입력 시 연락처로 사용되며, tel과 함께 보내면 tel이 우선됩니다.
공급받는자 업태
공급받는자 종목
공급받는자 사업장 주소
공급일자
세금계산서 품목란에 그대로 표시되는 품목명
규격
수량
단가. 음수 가능
품목 공급가액. 음수 가능
품목 세액. 음수 가능
품목 행 비고란에 표시되는 비고
Response Fields
세금계산서 ID
발행 요청 UUID
▶accountTicketAssetrequiredexpandable발행에 사용된 홈택스 자산
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶trusteeTaxInvoiceUser | nulloptionalexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
세금계산서 거래 타입
전자세금계산서 거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
총 건수
현금 금액
수표 금액
어음 금액
외상미수금 금액
영수/청구 구분
대표 품목
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
비고
발행 상태
발행 결과 코드
발행 결과 메시지
수입신고번호
통신 시작일
통신 종료일
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
수정사유
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 발행 테스트"
}'{
"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에서 `기재사항 착오정정`, `공급가액 변동`, `환입`만 허용합니다.
`기재사항 착오정정`은 이 endpoint를 두 번 호출합니다. 한 번은 당초분 전액을 음수로, 한 번은 올바른 내용으로 보내고 두 번 모두 `기재사항 착오정정` 사유와 원본 승인번호를 넣습니다. 공급받는자(사업자번호·상호)를 바로잡는 경우도 같으며, 정정분 공급받는자가 원본과 달라도 막지 않습니다.
`환입`(반품)은 반품된 금액만큼만 음수로 1장 발행합니다. `supplyValue`·`totalAmount`가 음수이고 `tradeItems`에 음수 금액 항목이 있어야 하며, 아니면 400으로 거절합니다. `reportingDate`는 반품된 날, `note`에는 당초 작성일을 적는 것이 국세청 안내입니다.
`reportingDate`는 바꾸지 않고 그대로 작성일자로 국세청에 전송됩니다. 사유에 맞는 날짜인지는 그랜터가 검사하지 않습니다.
`기재사항 착오정정` 두 장 중 정정 장만 거절됐다면 정정 장만 같은 원본 승인번호로 다시 보내세요. 마이너스 장과 같은 `Idempotency-Key`를 쓰면 10분 동안 마이너스 장 응답이 그대로 돌아오므로 새 키를 생성합니다. 그랜터는 같은 원본에 대한 중복 발행을 막지 않으니 이미 발행된 장을 다시 보내지 마세요.
공급받는자가 외국인(`contractorType=FOREIGNER`)이면 `contractor.registrationNumber`에 `9999999999999`, `note`에 외국인등록번호 또는 여권번호를 넣습니다. 개인(`INDIVIDUAL`)은 원본과 같은 주민등록번호로 보냅니다.
수정사유
▶허용 값
원본 승인번호
수정세금계산서 작성일자
정정 또는 차액 기준 품목 목록. 공급가액 변동은 차액을, 기재사항 착오정정은 당초분 음수 또는 정정본 내용을, 환입은 반품된 품목을 음수로 전달합니다.
공급가액. 차액 수정이면 음수/양수 모두 가능
세액. 차액 수정이면 음수/양수 모두 가능
합계금액. 차액 수정이면 음수/양수 모두 가능
Response Fields
세금계산서 ID
발행 요청 UUID
▶accountTicketAssetrequiredexpandable발행에 사용된 홈택스 자산
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶trusteeTaxInvoiceUser | nulloptionalexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
세금계산서 거래 타입
전자세금계산서 거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
총 건수
현금 금액
수표 금액
어음 금액
외상미수금 금액
영수/청구 구분
대표 품목
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
비고
발행 상태
발행 결과 코드
발행 결과 메시지
수입신고번호
통신 시작일
통신 종료일
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
수정사유
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": "공급가액 변동 정정"
}'{
"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)여야 합니다.
`contractorType`과 `contractor.registrationNumber`는 원본과 같게 보냅니다. 외국인(`FOREIGNER`)은 `9999999999999`와 함께 `note`에 외국인등록번호 또는 여권번호를 넣습니다.
`tradeItems[].taxItemName`은 발행된 취소 세금계산서의 품목란에 그대로 표시됩니다. 내부 추적용 문구는 `memo`를 사용하세요.
취소 사유
▶허용 값
원본 승인번호
취소발행 작성일자
음수 공급가액
음수 세액
음수 합계금액
음수 금액 기준 품목 목록
Response Fields
세금계산서 ID
발행 요청 UUID
▶accountTicketAssetrequiredexpandable발행에 사용된 홈택스 자산
자산 ID
워크스페이스 ID
자산명
자산 별칭
기관 코드
기관명
활성 여부
휴면 가능 여부
휴면 여부
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
유저 ID
유저 이름
유저 이메일
삭제 여부
고객 유형
업종 코드
업종명
유저 자동 할당 여부
카드 만료 연도
카드 만료 월
카드 한도 금액
카드 사용 금액
카드 잔여 한도
자동 승인 여부
이전 카드번호
계좌 잔액
원본 잔액
통화 코드
조회 시작일
조회 종료일
계좌 유형
거래내역 보유 여부
증권 총액
증권 예수금
외화예수금 상세 목록
외화예수금 합계
총 평가금액
계좌 번호
증권 보유 상품 목록
사업자등록번호
개업일자 코드
회사명
대표자명
주소
담당자명
담당자 이메일
연락처
업태
종목
홈택스 카테고리
생성 시각
수정 시각
조회 인증서 정보
발행 인증서 정보
▶supplierTaxInvoiceUserrequiredexpandable공급자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
▶trusteeTaxInvoiceUser | nulloptionalexpandable수탁자
사업자등록번호
회사명
대표자명
업태
종목
사업장 주소
이메일
보조 이메일
개업일자 코드
당사자 유형
관련 세금계산서
휴대전화
전화번호
승인번호
내용 타입
거래 타입
세금계산서 거래 타입
전자세금계산서 거래 타입
발행명
작성일자
전송일자
발행일자
공급가액
세액
합계금액
총 건수
현금 금액
수표 금액
어음 금액
외상미수금 금액
영수/청구 구분
대표 품목
▶tradeItemsTradeItem[]requiredexpandable품목 목록
공급일자
품목명
규격
수량
단가
공급가액
세액
비고
부가세 포함 여부
비고
발행 상태
발행 결과 코드
발행 결과 메시지
수입신고번호
통신 시작일
통신 종료일
▶issueOptionIssueOptionoptionalexpandable발행 옵션
발행 타입
과세 유형
청구 방향
권
호
공급받는자 유형
강제 발행 여부
명세 작성 여부
휴폐업 상태
휴폐업 일자
수정사유
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": "이중발급 취소"
}'{
"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` header는 optional입니다. 미입력 시 서버가 임의 생성합니다. 다만 timeout, 네트워크 끊김처럼 같은 발행 요청을 재시도해야 하는 경우에는 클라이언트가 직접 넣어야 중복 발행을 줄일 수 있습니다.
`Idempotency-Key`는 실제 발행 요청을 보내는 순간 생성하고, 같은 payload 재시도에만 같은 값을 재사용하세요. 화면 진입, 세션, 임시저장, 구매자 선택 같은 긴 수명에 묶어 재사용하지 마세요.
payload의 금액, 구매자, 거래 일시, 발행 용도, 과세 형태가 바뀌었거나 사용자가 새 현금영수증을 발행하는 경우에는 이전 `Idempotency-Key`를 재사용하지 말고 새 값을 생성하세요.
이미 사용한 `Idempotency-Key`로 다른 payload를 보내면 새 현금영수증이 발행되지 않고 기존 요청의 승인번호/결과가 반환될 수 있으므로, 외부 시스템에서는 payload fingerprint와 키를 함께 관리하는 것을 권장합니다.
`homeTaxAccountId`는 `assets` API에서 `assetType=HOME_TAX_ACCOUNT`로 조회한 활성 홈택스 자산 ID를 사용합니다.
`totalAmount`, `supplyValue`, `vat`, `serviceFee`는 모두 정수(integer)로 전달하세요.
`transactAt`은 발행일 기준 전일부터 당일까지만 받습니다. 국세청은 현금영수증 거래일자 소급 발급을 허용하지 않아 3~5일 전 거래일로는 발급되지 않고, 발행 대행사 오류가 그대로 돌아옵니다. 그랜터는 `transactAt`을 바꾸지 않고 그대로 전달합니다.
발행에 사용할 홈택스 자산 ID
거래 일시(발행일 기준 전일~당일)
거래 내용
발행 용도
▶허용 값
과세 형태
▶허용 값
총금액
공급가액
부가세
봉사료
발행자 사업자등록번호
발행자 회사명
구매자 식별번호
구매자명
Response Fields
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
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": "홍길동"
}
}'{
"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)로 전달하세요.
부분취소는 한 영수증에 여러 번 할 수 있습니다. 두 번째 이후 부분취소에도 `cashReceiptId`에는 항상 원본 영수증 ID를 넣습니다(국세청 기준 취소는 당초 승인거래의 승인번호·승인일자로 합니다). 앞선 부분취소로 생긴 영수증 ID를 넣으면 안 됩니다.
부분취소 금액 필드는 이번에 취소할 금액입니다(취소 후 남는 금액이 아님). 취소 금액 합계가 원래 금액을 넘으면 발행 대행사가 거절하며, 그랜터는 누적 취소액을 따로 계산해 막지 않으니 남은 금액 안에서 나눠 보내세요.
이미 일부를 취소한 영수증의 남은 금액을 모두 취소할 때도 `isPartialCancel=true`로 남은 금액을 보냅니다. `isPartialCancel=false`는 원래 금액 전체를 취소하는 요청이라 일부를 취소한 뒤에는 금액이 넘쳐 거절됩니다.
취소 건 `transactAt`도 발행일 기준 전일부터 당일까지만 받으며, 당초 승인 거래일보다 앞선 날짜로 보낼 수 없습니다. 원본을 발행한 당일에 바로 취소해도 원본과 취소 건이 다음 날 함께 국세청에 전송됩니다(전송 결과는 다음 날 오전 10시 이후 확인 가능).
취소 대상 현금영수증 ID
취소 거래 일시
취소 사유
▶허용 값
메모 또는 취소 내용
부분취소 여부
이번에 취소할 총금액(남는 금액 아님)
이번에 취소할 공급가액
이번에 취소할 부가세
이번에 취소할 봉사료
수신 이메일 목록
Response Fields
현금영수증 ID
워크스페이스 ID
영수증 구분
거래 일시
국세청 승인일자
거래구분
과세형태
공제여부
용도구분
발행구분
발행 상태
승인번호
총금액
공급가액
부가세
봉사료
거래 내용
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
사업자번호
상호
유저 ID
식별번호
사용자명
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
취소 사유
원본 승인번호
원본 승인일자
원본 현금영수증 ID
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"]
}'{
"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
Aggregation Tips
{
"period": "monthly",
"filters": {
"ticketTypes": ["EXPENSE_TICKET", "BANK_TRANSACTION_TICKET"],
"startDate": "2026-02-01",
"endDate": "2026-02-28",
"isIncluded": true
},
"groupBy": "expenseCategoryId"
}[
{
"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
}
]{
"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": []
}
}