granter API
그랜터 Public Docs API는 자산 연동 현황, 거래·증빙 데이터, 분류 기준, 잔액 흐름을 외부 시스템과 AI가 함께 이해할 수 있도록 구조화해 제공하는 읽기 전용 연동 문서입니다. 발급된 API key와 Basic 인증만으로 해당 워크스페이스 범위의 데이터를 안전하게 조회하고, 자체 서비스, 분석 파이프라인, AI 자동화 워크플로우에 바로 연결할 수 있습니다.
문서 이해를 위한 빠른 가이드
1) 이 문서가 다루는 범위
- `assets`: 카드, 계좌, 홈택스, 스토어처럼 거래가 들어오는 자산·연동 대상을 조회합니다.
- `tickets`: 카드 승인, 계좌 입출금, 세금계산서, 현금영수증, 결재 등 실제 업무에서 발생한 거래·증빙 이벤트를 조회합니다.
- `workflows`: 전자결재 문서, 결재선, 승인 상태처럼 결재 프로세스 자체를 조회합니다.
- `salary-histories`: 직원별 급여 내역, 지급 상태, 공제/수당 상세처럼 급여 도메인 데이터를 조회합니다.
- `inventory-products`, `inventories`: 품목 마스터와 현재 재고 수량을 분리해서 조회합니다.
- `balances`: 계좌별 잔액 흐름을 시계열로 조회해 자금 추이와 현금 상태를 파악할 수 있습니다.
- `tags`, `tag-details`, `categories`, `people`, `teams`, `contacts`: 원시 거래를 사람이 이해할 수 있는 회계·운영 언어로 바꾸는 기준 데이터를 조회합니다.
2) 추천 연동 순서
1. 발급된 live key 또는 test key를 준비하고 Basic 인증을 연결합니다.
2. `people`, `teams`, `contacts`, `categories`, `tags`, `tag-details`를 먼저 동기화해 분류 기준과 담당자 기준을 맞춥니다.
3. 전자결재 문서와 결재선 상태가 필요하면 `workflows`를 함께 수집합니다.
4. 급여 분석이나 인건비 자동화가 필요하면 `salary-histories`를 별도 도메인으로 함께 수집합니다.
5. 재고를 운영한다면 `inventory-products`와 `inventories`를 함께 수집해 품목 마스터와 수량 현황을 분리 적재합니다.
6. `assets`로 어떤 자산에서 데이터가 들어오는지 파악합니다.
7. `tickets`를 수집해 실제 거래·증빙 원천 데이터를 적재합니다.
8. 자금 흐름까지 보려면 `balances`를 별도 주기로 함께 수집합니다.
3) 설계 원칙과 실무 규칙
- 모든 조회는 API key가 속한 현재 워크스페이스 범위 안에서만 수행됩니다.
- Public Docs API는 API key 기준 분당 60회까지 호출할 수 있습니다.
- 응답은 원본 구조를 최대한 보존하므로, nullable/optional 필드는 자산 종류와 데이터 출처에 따라 비어 있을 수 있습니다.
- AI와 사람이 모두 이해하기 쉬운 데이터를 만들려면 `tickets`만 저장하지 말고 `workflows`, `salary-histories`, `inventory-products`, `inventories`, `categories`, `tags`, `people`, `teams`, `contacts` 같은 기준 정보도 함께 적재하는 편이 좋습니다.
- 날짜 입력은 `YYYY-MM-DD`, 응답 시각은 주로 ISO-8601 문자열 형식을 사용합니다.
- 금액은 단순 부호보다 `transactionType`, 티켓 타입, endpoint 의미를 함께 보고 해석하는 것이 안전합니다.
API 활용 팁
1) AI에 문서를 전달할 때
- 우측 상단의 `.md 다운로드`로 문서를 내려받아 AI 프롬프트나 지식 파일에 그대로 넣는 방식을 권장합니다.
- Markdown 파일은 endpoint, 요청 필드, 응답 예시가 구조화되어 있어 PDF나 스크린샷보다 AI가 더 안정적으로 읽고 참조할 수 있습니다.
- AI에게 요청할 때는 이 파일 전체를 기준 문서로 주고, 필요한 endpoint와 예시 body를 함께 만들도록 지시하면 가장 안정적입니다.
2) Rate limit 대응
- Public Docs API는 API key 기준 분당 60회까지 호출할 수 있습니다.
- 여러 endpoint를 한 번에 수집할 때는 동시 요청 수를 낮추고, `429 Too Many Requests`가 오면 잠시 대기한 뒤 재시도하세요.
- 초기 백필이나 대량 적재는 1분 단위 배치로 나누어 호출하는 편이 안전합니다.
3) 조회 기간이 31일을 넘는 경우
- 기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있습니다.
- 더 긴 기간이 필요하면 `startDate`, `endDate`를 31일 이하 구간으로 나눠 순차 조회한 뒤 결과를 합치세요.
- 합칠 때는 응답의 `id`를 기준으로 중복을 제거하고, 적재 테이블에서는 보통 `workspaceId + id` 조합을 키로 둡니다.
[
{ "startDate": "2026-01-01", "endDate": "2026-01-31" },
{ "startDate": "2026-02-01", "endDate": "2026-02-28" },
{ "startDate": "2026-03-01", "endDate": "2026-03-31" }
]그랜터 데이터 구조와 활용 관점
1) Workspace
Workspace는 하나의 회사 또는 운영 단위를 뜻하는 가장 큰 데이터 경계입니다. API key는 특정 `workspaceId`와 연결되며, 같은 회사 안의 자산, 거래, 태그, 계정과목, 구성원 정보가 모두 이 범위 안에서 조회됩니다. 외부 시스템 입장에서는 "어느 회사의 재무 데이터를 읽고 있는가"를 결정하는 기준이라고 보면 됩니다.
2) Asset (자산)
Asset은 계좌, 카드, 홈택스, 마켓 스토어처럼 거래가 수집되는 연결 대상입니다. 단순 목록이 아니라, 어떤 채널에서 어떤 데이터가 들어오는지 보여주는 출처 정보에 가깝습니다. 자산 유형(`assetType`), 활성 상태(`isActive`), 기관명, 계좌번호/카드번호 같은 식별 정보를 보면 이후 Ticket과 Balance를 어떤 맥락에서 해석해야 하는지 알 수 있습니다.
{
"id": 101,
"assetType": "CARD",
"workspaceId": 123,
"organizationName": "신한카드",
"isActive": true
}3) Ticket (거래 티켓)
Ticket은 실제 업무에서 발생한 거래·증빙 단위 데이터를 의미합니다. 카드 승인 1건, 계좌 입출금 1건, 세금계산서 1건, 현금영수증 1건처럼 "한 번의 재무 이벤트"를 표현한다고 보면 됩니다. 금액(`amount`), 방향(`transactionType`: IN/OUT), 발생일(`transactAt`), 내용(`content`), 분류 상태(`isIncluded`) 등을 가지며, 장부 정리, AI 분류, 분석 리포트, 업무 자동화의 공통 원천 데이터가 됩니다.
{
"id": 98765,
"ticketType": "EXPENSE_TICKET",
"workspaceId": 123,
"amount": 12000,
"transactionType": "OUT",
"transactAt": "2026-02-23T10:15:00.000Z",
"content": "점심 식대",
"isIncluded": true
}4) Workflow (전자결재 문서)
`workflows`는 기안 문서, 결재 상태, 결재선, 검토자 정보를 담는 전자결재 데이터입니다. `tickets`가 정산·증빙 중심의 재무 이벤트라면, `workflows`는 누가 어떤 안건을 올렸고 현재 몇 차 결재까지 진행됐는지를 보여주는 운영 문서에 가깝습니다. 비용 승인 플로우, 결재 병목 분석, 결재 대기 모니터링, 내부 승인 이력 적재에 적합합니다.
5) Salary History (급여 내역)
`salary-histories`는 급여 지급일, 총급여, 실지급액, 보험료, 세액, 수당·공제 상세를 담는 독립 도메인 데이터입니다. 급여는 티켓 도메인과 별도로 관리되므로, 인건비 분석, 급여 지급 상태 추적, 급여명세 자동화, 노무/세무 협업용 적재가 필요할 때는 `tickets` 대신 `salary-histories`를 직접 읽는 편이 맞습니다.
6) Inventory Product / Inventory (품목 / 재고)
`inventory-products`는 품목명, 단가, 통화, 추가 속성 같은 품목 마스터를 조회하는 API이고, `inventories`는 해당 품목의 현재 수량, 메시지 수, 최근 수정 시각 같은 재고 현황을 조회하는 API입니다. 하나는 "무엇을 관리하는가", 다른 하나는 "현재 얼마나 남아 있는가"에 초점이 있으므로 같이 적재하는 편이 자연스럽습니다.
7) Reference Data (분류/담당자 기준 정보)
`categories`, `tags`, `tag-details`, `people`, `teams`, `contacts`는 원시 거래를 사람이 읽을 수 있는 회계·운영 언어로 바꾸는 기준 데이터입니다. 예를 들어 "이 거래가 어떤 비용인지", "어떤 프로젝트/조직/담당자/팀/거래처와 연결되는지"를 설명할 때 사용합니다. 티켓 응답만으로도 일부 정보를 볼 수 있지만, AI 분석이나 외부 리포트까지 고려한다면 이 기준 데이터를 별도로 동기화해 두는 편이 훨씬 안정적입니다.
8) Balance (잔액 시계열)
`balances`는 특정 기간의 계좌 잔액 변화를 보여주는 시계열 데이터입니다. `tickets`가 "무슨 거래가 있었는가"를 설명한다면, `balances`는 "그 결과로 계좌에 얼마가 남아 있는가"를 보여줍니다. 자금 추이, 일별 잔액 리포트, 유동성 모니터링, 현금 흐름 대시보드에 적합한 데이터입니다.
9) 관계와 조회 관점
- Workspace 1개 아래에 여러 Asset이 존재합니다.
- Workspace 1개 아래에 여러 Ticket이 존재합니다.
- Workspace 1개 아래에 여러 Workflow(전자결재 문서)가 존재합니다.
- Workspace 1개 아래에 여러 Salary History(급여 내역)가 존재합니다.
- Workspace 1개 아래에 여러 Inventory Product(품목)와 Inventory(재고 엔트리)가 존재합니다.
- Ticket은 특정 Asset에서 수집된 거래나 증빙 이벤트를 표현합니다.
- `workflows` API는 결재 문서, 결재선, 승인 진행 상태를 읽을 때 사용합니다.
- `salary-histories` API는 직원별 급여 내역, 지급 상태, 공제/수당 구성을 읽을 때 사용합니다.
- `inventory-products`는 품목 마스터를, `inventories`는 현재 수량과 재고 상태를 읽을 때 사용합니다.
- `assets` API는 데이터 출처와 연동 상태를 이해할 때, `tickets` API는 실제 거래 원천 데이터를 읽을 때 사용합니다.
- `balances` API는 자금 상태와 잔액 흐름을 따로 추적할 때 사용합니다.
- `tags`(1차 태그), `tag-details`(2차 태그), `categories`, `people`, `teams`, `contacts` API는 Ticket을 해석하고 분류하는 기준 데이터로 사용합니다.
10) 통합 시 자주 보는 포인트
- 동일한 회사 데이터를 반복 적재할 때는 `workspaceId + 내부 id` 조합으로 기본 키를 설계하는 것이 일반적입니다.
- 티켓 집계 시에는 `transactionType`, `ticketType`, `isIncluded`를 함께 봐야 사람이 보는 리포트와 AI 분석 결과가 모두 안정적입니다.
- 전자결재 분석이 목적이라면 `workflows.status`, `currentStep`, `steps`를 함께 저장해 결재 대기와 승인 흐름을 추적하는 편이 좋습니다.
- 급여 분석이 목적이라면 `salaryPaymentStatus`, `employmentType`, `recognizedAmount`, `netAmount`를 함께 저장해 지급 현황과 인건비 구조를 분리해서 보는 편이 좋습니다.
- 재고 분석이 목적이라면 `inventory-products`와 `inventories`를 분리 저장하고, `inventoryProductId`로 조인하는 편이 운영 화면과 분석 리포트 양쪽에 유리합니다.
- 자산별 활성 여부와 참조 데이터의 숨김 여부(`isHidden`)는 운영 화면과 외부 리포트에서 의미가 다를 수 있으므로 원본 값을 함께 보관하는 편이 좋습니다.
POST /api/public-docs/tickets
카드, 계좌, 세금계산서, 현금영수증, 결재 등 실제 거래·증빙 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.
ticketTypeenumrequired
조회 대상 티켓 타입. 아래 TicketType 상세 목록을 참고하세요.
▶TicketType 상세(기본 접힘)
EXPENSE_TICKET·카드-카드 승인/사용 내역 티켓
BANK_TRANSACTION_TICKET·계좌-계좌 입출금 거래 티켓
TAX_INVOICE_TICKET·세금계산서-세금계산서 증빙 티켓
CASH_RECEIPT_TICKET·현금영수증-현금영수증 증빙 티켓
WORKFLOW·결재-워크플로우 결재 티켓
MERCHANT_CARD_TRANSACTION_TICKET·포스기-가맹점 카드거래 티켓
ECOMMERCE_SETTLEMENT_DETAIL_TICKET·이커머스정산 상세-이커머스 정산 상세 티켓
ECOMMERCE_SETTLEMENT·이커머스정산-이커머스 정산 집계 티켓
SALARY_HISTORY·급여-급여 내역 티켓
MANUAL_TRANSACTION_TICKET·수기관리-수기 입력 거래 티켓
Total·전체-통합/전체 조회용 타입
startDateYYYY-MM-DDoptional
조회 시작일
endDateYYYY-MM-DDoptional
조회 종료일
contactIdnumberoptional
거래처 ID
contactQueryOption"NONE" | "EXACT_MATCH"optional
거래처 검색 옵션
expenseCategoryIdnumberoptional
계정과목 ID
expenseCategoryQueryOption"NONE" | "EXACT_MATCH"optional
계정과목 검색 옵션
tagDetailIdnumberoptional
2차 태그 ID
tagDetailQueryOption"NONE" | "EXACT_MATCH"optional
2차 태그 검색 옵션
tagIdnumberoptional
1차 태그 ID
assetIdnumberoptional
자산 ID
Response Fields
▶[]TicketrequiredexpandableBE `/tickets` 원본 응답 배열의 각 원소
idnumberrequired
티켓 ID
workspaceIdnumberrequired
워크스페이스 ID
contentstringrequired
거래/증빙 내용
amountnumberrequired
거래 금액
transactionType"IN" | "OUT" | "ALL"required
입출금 방향
transactAtISO-8601 stringrequired
거래 일시
modifiedTransactAtISO-8601 stringoptional
수정 거래 일시
descriptionstringrequired
설명
▶expenseCategoryExpenseCategoryoptionalexpandable계정과목
idnumberrequired
계정과목 ID
namestringrequired
계정과목명
subInfostringrequired
부가 정보
descriptionstringrequired
설명
codenumber | stringrequired
코드
type"COMMON" | "CUSTOM"required
카테고리 타입
isHiddenbooleanrequired
숨김 여부
costType"NONE" | "VARIABLE" | "FIXED"required
비용 유형
isFavoritebooleanrequired
즐겨찾기 여부
workspaceIdnumberoptional
워크스페이스 ID
taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional
기본 과세 유형
anomalyStatus"NORMAL" | "ABUSE_SUSPECTED" | "ABUSE_CONFIRMED" | "ABUSE_REJECTED"required
이상치 상태
status"NONE" | "CONFIRMED" | "USER_CONFIRMED"required
티켓 상태
tagstringrequired
1차 태그명
tagIdnumber | nullrequired
1차 태그 ID
contactstringrequired
거래처명
contactIdnumber | undefinedrequired
거래처 ID
tagDetailstringrequired
2차 태그명
tagDetailIdnumber | nullrequired
2차 태그 ID
isIncludedbooleanrequired
포함 여부
▶usersUserResponse[]requiredexpandable연결 유저 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
▶messagesMessage[]requiredexpandable메시지 목록
idnumberrequired
메시지 ID
ticketIdnumberrequired
티켓 ID
▶userUserResponserequiredexpandable작성자
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
userIdnumberrequired
작성자 ID
userNamestringrequired
작성자 이름
contentstringrequired
메시지 내용
typeMessageTyperequired
메시지 타입
createdAtstringrequired
생성 시각
deletedAtstring | nulloptional
삭제 시각
messageCountnumberrequired
메시지 수
▶attachmentsAttachment[]requiredexpandable첨부파일 목록
idnumberrequired
첨부파일 ID
ticketIdnumberrequired
티켓 ID
namestringrequired
파일명
uploadedUrlstringrequired
업로드 URL
contentTypestringrequired
MIME 타입
attachmentCountnumberrequired
첨부파일 수
ticketTypeTicketTyperequired
조회 대상 티켓 타입
▶cardUsageCardUsageoptionalexpandable카드 사용 상세
workspaceIdnumberrequired
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
paymentDatestringrequired
결제일
storeNamestringrequired
가맹점명
storeAddressstringrequired
가맹점 주소
amountnumberrequired
사용 금액
canceledAmountnumberrequired
취소 금액
discountedAmountnumberrequired
할인 금액
vatnumberrequired
부가세
installmentMonthnumberrequired
할부 개월
paymentTypestringrequired
결제 방식
paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required
결제 상태
approvalNumbernumberrequired
승인번호
storeCorporateNumbernumberrequired
가맹점 사업자번호
originalAmountnumberrequired
원본 금액
currencystringrequired
통화 코드
exchangeRatenumberoptional
환율
purchaseDatestringoptional
매입일
feeAmountnumberoptional
수수료
isPurchasedbooleanoptional
매입 여부
▶purchaseUsageCardUsageoptionalexpandable매입 카드 사용 상세
workspaceIdnumberrequired
워크스페이스 ID
▶cardTicketAssetrequiredexpandable카드 자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
paymentDatestringrequired
결제일
storeNamestringrequired
가맹점명
storeAddressstringrequired
가맹점 주소
amountnumberrequired
사용 금액
canceledAmountnumberrequired
취소 금액
discountedAmountnumberrequired
할인 금액
vatnumberrequired
부가세
installmentMonthnumberrequired
할부 개월
paymentTypestringrequired
결제 방식
paymentStatus"NORMAL" | "CANCELED" | "REJECTED" | "PURCHASE_CANCELED"required
결제 상태
approvalNumbernumberrequired
승인번호
storeCorporateNumbernumberrequired
가맹점 사업자번호
originalAmountnumberrequired
원본 금액
currencystringrequired
통화 코드
exchangeRatenumberoptional
환율
purchaseDatestringoptional
매입일
feeAmountnumberoptional
수수료
isPurchasedbooleanoptional
매입 여부
▶bankTransactionBankTransactionoptionalexpandable계좌 거래 상세
bankTransactionIdnumberrequired
은행거래 ID
workspaceIdnumberrequired
워크스페이스 ID
transactionType"IN" | "OUT" | "ALL"required
거래 방향
descriptionstringrequired
설명
afterTransactionBalancenumberrequired
거래 후 잔액
originalAfterTransactionBalancenumberoptional
원본 거래 후 잔액
amountnumberrequired
거래 금액
originalAmountnumberoptional
원본 거래 금액
transactAtstringrequired
거래 일시
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
counterpartystringoptional
거래 상대방
descriptionTypestringoptional
설명 분류
contentstringoptional
내용
branchstringoptional
지점
▶taxInvoiceTaxInvoiceoptionalexpandable세금계산서 상세
idnumberrequired
세금계산서 ID
▶supplierTaxInvoiceUserrequiredexpandable공급자
registrationNumberstringrequired
사업자등록번호
companyNamestringrequired
회사명
ceoNamestringoptional
대표자명
namestringrequired
담당자명
businessTypesstringrequired
업태
businessItemsstringrequired
종목
businessPlacestringrequired
사업장 주소
emailstringrequired
이메일
email2stringoptional
보조 이메일
idnumberrequired
유저 ID
establishNumberstringoptional
개업일자 코드
userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional
당사자 유형
taxInvoiceTaxInvoiceoptional
관련 세금계산서
phonestringoptional
휴대전화
telstringoptional
전화번호
▶contractorTaxInvoiceUserrequiredexpandable공급받는자
registrationNumberstringrequired
사업자등록번호
companyNamestringrequired
회사명
ceoNamestringoptional
대표자명
namestringrequired
담당자명
businessTypesstringrequired
업태
businessItemsstringrequired
종목
businessPlacestringrequired
사업장 주소
emailstringrequired
이메일
email2stringoptional
보조 이메일
idnumberrequired
유저 ID
establishNumberstringoptional
개업일자 코드
userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional
당사자 유형
taxInvoiceTaxInvoiceoptional
관련 세금계산서
phonestringoptional
휴대전화
telstringoptional
전화번호
▶issuerobjectrequiredexpandable발행자
emailstringrequired
이메일
idnumberrequired
유저 ID
isDeletedbooleanrequired
삭제 여부
namestringrequired
이름
▶trusteeTaxInvoiceUserrequiredexpandable수탁자
registrationNumberstringrequired
사업자등록번호
companyNamestringrequired
회사명
ceoNamestringoptional
대표자명
namestringrequired
담당자명
businessTypesstringrequired
업태
businessItemsstringrequired
종목
businessPlacestringrequired
사업장 주소
emailstringrequired
이메일
email2stringoptional
보조 이메일
idnumberrequired
유저 ID
establishNumberstringoptional
개업일자 코드
userType"SUPPLIER" | "CONTRACTOR" | "TRUSTEE"optional
당사자 유형
taxInvoiceTaxInvoiceoptional
관련 세금계산서
phonestringoptional
휴대전화
telstringoptional
전화번호
approvalNumberstringrequired
승인번호
contentType"SUMMARY" | "DETAIL"required
내용 타입
transactionType"SELL" | "BUY" | "TRUSTEE"required
거래 타입
issueNamestringrequired
발행명
reportingDatestringrequired
작성일자
sendDatestringoptional
전송일자
issueDatestringoptional
발행일자
supplyValuenumberrequired
공급가액
taxAmountnumberrequired
세액
totalAmountnumberrequired
합계금액
purposeType"RECEIPT" | "CHARGE"required
영수/청구 구분
representationItemsstringrequired
대표 품목
notestringrequired
비고
status"REPORTED" | "SENT" | "ISSUED"required
상태
taxInvoiceTypestringrequired
세금계산서 종류
▶tradeItemsTradeItem[]requiredexpandable품목 목록
purchaseExpiryDatestringrequired
공급일자
taxItemNamestringrequired
품목명
standardsstringrequired
규격
quantitynumberrequired
수량
unitPricenumberrequired
단가
supplyValuenumberrequired
공급가액
taxAmountnumberrequired
세액
notestringrequired
비고
isIncludedVatbooleanoptional
부가세 포함 여부
modificationReasonstringoptional
수정사유
originalApprovalNumbernumberoptional
원본 승인번호
▶issueOptionIssueOptionoptionalexpandable발행 옵션
issueTypestringrequired
발행 타입
taxType"TAX" | "ZERO_TAX_RATE" | "TAX_EXEMPTION"required
과세 유형
chargeDirectionstringrequired
청구 방향
kwonnumberrequired
권
honumberrequired
호
contractorType"BUSINESS" | "INDIVIDUAL" | "FOREIGNER"required
공급받는자 유형
forceIssuebooleanrequired
강제 발행 여부
writeSpecificationbooleanrequired
명세 작성 여부
closeDownStatusstringrequired
휴폐업 상태
closeDownDatestringrequired
휴폐업 일자
paymentStatus"PAID" | "UNPAID"optional
결제 상태
createdAtISO-8601 stringrequired
생성 시각
parentIdnumberoptional
부모 티켓 ID
isSplittedbooleanrequired
분할 티켓 여부
purchaseStatus"APPROVED" | "PURCHASED" | "PURCHASE_ONLY"optional
매입 상태
isSoftwareExpenditurebooleanoptional
소프트웨어 지출 여부
▶merchantCardTransactionMerchantCardTransactionoptionalexpandable가맹점 카드 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
cardCompanystringrequired
카드사
cardNamestringrequired
카드명
cardTypeCardTyperequired
카드 타입
cardNumberstringrequired
카드번호
approvalNumberstringrequired
승인번호
installmentMonthnumberrequired
할부개월
transactionTypestringrequired
거래구분
transactAtstringrequired
거래일시
amountnumberrequired
금액
▶merchantPurchaseTransactionMerchantPurchaseTransactionoptionalexpandable가맹점 매입 거래 상세
▶assetTicketAssetrequiredexpandable자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
cardCompanystringrequired
카드사
cardNamestringrequired
카드명
cardTypestringrequired
카드 타입
cardNumberstringrequired
카드번호
approvalNumberstringrequired
승인번호
transactAtstringrequired
거래일시
purchaseDatestringrequired
매입일
purchaseAmountnumberrequired
매입 금액
totalFeenumberrequired
총 수수료
merchantServiceFeenumberrequired
가맹점 수수료
pointFeenumberrequired
포인트 수수료
etcFeenumberrequired
기타 수수료
paidAmountnumberrequired
지급 금액
expectedPaymentDatestringrequired
지급 예정일
▶cashReceiptCashReceiptoptionalexpandable현금영수증 상세
idnumberrequired
현금영수증 ID
workspaceIdnumberrequired
워크스페이스 ID
receiptType"SALES" | "PURCHASE"required
영수증 구분
transactAtstringrequired
거래 일시
transactDatestringrequired
국세청 승인일자
transactionType"APPROVAL" | "CANCEL"required
거래구분
taxationType"TAXABLE" | "NON_TAXABLE"optional
과세형태
deductionStatusstringoptional
공제여부
usage"TAX_DEDUCTION" | "EXPENSE_PROOF"required
용도구분
issueTypestringoptional
발행구분
issueStatusstringrequired
발행 상태
approvalNumberstringrequired
승인번호
totalAmountnumberrequired
총금액
supplyValuenumberrequired
공급가액
vatnumberrequired
부가세
serviceFeenumberrequired
봉사료
contentstringrequired
거래 내용
ntsResultCodestringoptional
국세청 결과 코드
▶issuerCashReceiptCounterPartyrequiredexpandable발행자
registrationNumberstringoptional
사업자번호
companyNamestringoptional
상호
userIdnumberoptional
유저 ID
identityNumberstringoptional
식별번호
userNamestringoptional
사용자명
emailsstring[]optional
이메일 목록
▶buyerCashReceiptCounterPartyrequiredexpandable구매자
registrationNumberstringoptional
사업자번호
companyNamestringoptional
상호
userIdnumberoptional
유저 ID
identityNumberstringoptional
식별번호
userNamestringoptional
사용자명
emailsstring[]optional
이메일 목록
▶cancelOptionobjectoptionalexpandable취소 정보
cancelReasonstringrequired
취소 사유
originalApprovalNumberstringrequired
원본 승인번호
originalTransactDatestringrequired
원본 승인일자
originalCashReceiptIdnumberrequired
원본 현금영수증 ID
▶manualTransactionManualTransactionoptionalexpandable수기거래 상세
idnumberrequired
수기거래 ID
currencyCurrencyCoderequired
통화 코드
manualTransactionType"ETC" | "CASH" | "INVOICE"required
수기거래 타입
▶tradeItemsManualTransactionTradeItem[]requiredexpandable거래 품목
itemNamestringrequired
품목명
quantitynumberrequired
수량
taxAmountnumberrequired
세액
unitPricenumberrequired
단가
hasPurchaseCanceledUsagesbooleanoptional
매입 취소 사용내역 보유 여부
▶ecommerceSettlementDetailTransactionEcommerceSettlementDetailTransactionoptionalexpandable이커머스 정산 상세
▶assetobjectrequiredexpandable이커머스 스토어 자산
idnumberoptional
자산 ID
organizationstringoptional
조직 (COUPANG, NAVER 등)
nicknamestringoptional
별칭
ecommerceSettlementIdnumberrequired
정산 ID
settlementDatestringrequired
정산일
settlementRationumberrequired
정산 비율
namestringrequired
항목명
amountnumberrequired
금액
typestringrequired
정산 상세 타입
transactionType"IN" | "OUT"required
입출금 방향
isRecommendedbooleanoptional
추천 티켓 여부
taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional
과세 유형
호출
API KEY
REQUEST EXAMPLE (JSON)
호출 예시
cURL
curl -X POST https://app.granter.biz/api/public-docs/tickets \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"ticketType": "EXPENSE_TICKET",
"startDate": "2026-03-01",
"endDate": "2026-03-07"
}'POST /api/public-docs/tickets
Ticket Response Example
[
{
"id": 49176,
"ticketType": "EXPENSE_TICKET",
"workspaceId": 1,
"description": "",
"content": "GLOBAL SOFTWARE INC.",
"amount": 14493,
"transactionType": "OUT",
"transactAt": "2026-02-28T17:04:34",
"status": "CONFIRMED",
"anomalyStatus": "NORMAL",
"expenseCategory": {
"id": 1008,
"name": "숙박비",
"subInfo": "판매비와 일반관리비",
"description": "출장업무 등 숙박에 대한 비용",
"code": "812",
"type": "COMMON",
"isHidden": false,
"costType": "FIXED",
"isFavorite": false,
"taxType": "EXEMPT"
},
"users": [
{
"id": 73,
"name": "담당자 A",
"email": "user-a@example.com",
"isDeleted": false
}
],
"owners": [
{
"id": 73,
"name": "소유자 A",
"email": "owner-a@example.com",
"isDeleted": false
}
],
"isIncluded": true,
"tag": "",
"tagId": null,
"contact": "",
"contactId": null,
"tagDetail": "",
"tagDetailId": null,
"messages": [
{
"id": 16099,
"ticketId": 49176,
"user": {
"id": 4,
"name": "운영자 A",
"email": "operator@example.com",
"isDeleted": false
},
"userId": 4,
"userName": "운영자 A",
"content": "계정과목을 없음에서 숙박비로 변경하였습니다.",
"type": "COMMON_CHANGE",
"createdAt": "2026-03-01T21:52:10.826539",
"deletedAt": null,
"isDeleted": false
}
],
"messageCount": 1,
"attachments": [],
"attachmentCount": 0,
"createdAt": "2026-02-28T19:50:38.773108",
"parentId": null,
"isSplitted": false,
"assetId": 53,
"cardUsage": {
"workspaceId": 1,
"card": {
"id": 53,
"workspaceId": 1,
"name": "KB국민 SME기업카드",
"nickname": "운영 법인카드",
"number": "558526******0880",
"organization": "KB",
"organizationName": "국민카드",
"businessType": "CD",
"businessTypeName": "CD",
"owners": [
{
"id": 73,
"name": "소유자 A",
"email": "owner-a@example.com",
"isDeleted": false
}
],
"isHidden": false,
"clientType": "CORPORATE",
"isActive": true,
"isDormant": false,
"isPossibleDormant": false,
"userAutoAssignEnabled": true,
"isFree": false,
"hasPassword": false,
"expirationYear": "2030",
"expirationMonth": "09",
"limitAmount": 1000000,
"usedAmount": 0,
"remainLimit": 0,
"previousCardNumber": null
},
"organizationName": "국민카드",
"paymentDate": "2026-02-28T17:04:34",
"storeName": "GLOBAL SOFTWARE INC.",
"storeType": "없음",
"storeAddress": "",
"storeCorporateNumber": "",
"amount": 14245,
"canceledAmount": 0,
"vat": 0,
"installmentMonth": 0,
"paymentType": "FULL",
"paymentStatus": "NORMAL",
"approvalNumber": "323461",
"discountedAmount": 0,
"originalAmount": "10.00",
"currency": "USD",
"isStoreInfoUpdated": true,
"isPurchased": true
},
"purchaseUsage": {
"workspaceId": 1,
"card": {
"id": 53,
"workspaceId": 1,
"name": "KB국민 SME기업카드",
"nickname": "운영 법인카드",
"number": "558526******0880",
"organization": "KB",
"organizationName": "국민카드",
"businessType": "CD",
"businessTypeName": "CD",
"owners": [
{
"id": 73,
"name": "소유자 A",
"email": "owner-a@example.com",
"isDeleted": false
}
],
"isHidden": false,
"clientType": "CORPORATE",
"isActive": true,
"isDormant": false,
"isPossibleDormant": false,
"userAutoAssignEnabled": true,
"isFree": false,
"hasPassword": false,
"expirationYear": "2030",
"expirationMonth": "09",
"limitAmount": 1000000,
"usedAmount": 0,
"remainLimit": 0,
"previousCardNumber": null
},
"organizationName": "국민카드",
"paymentDate": "2026-02-28T00:00:00",
"storeName": "GLOBAL SOFTWARE INC.",
"storeType": "",
"storeAddress": "",
"storeCorporateNumber": "",
"amount": 14493,
"canceledAmount": 0,
"vat": 0,
"installmentMonth": 0,
"paymentType": "FULL",
"paymentStatus": "NORMAL",
"approvalNumber": "GRANTER-0",
"discountedAmount": 0,
"originalAmount": "10.000",
"currency": "USD",
"purchaseDate": "2026-03-03",
"exchangeRate": "1449.30",
"foreignReceiptAmount": "10.00",
"feeAmount": 187
},
"bankTransaction": null,
"taxInvoice": null,
"paymentStatus": null,
"purchaseStatus": "PURCHASED",
"merchantCardTransaction": null,
"merchantPurchaseTransaction": null,
"cashReceipt": null,
"manualTransaction": null,
"hasPurchaseCanceledUsages": false,
"ecommerceSettlementDetailTransaction": null,
"taxType": "EXEMPT"
}
]POST /api/public-docs/assets
거래가 수집되는 자산과 연동 대상을 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
assetTypeenumrequired
CARD, BANK_ACCOUNT, HOME_TAX_ACCOUNT, CUSTOM, MERCHANT_GROUP, SECURITIES_ACCOUNT, ECOMMERCE, MANUAL
Response Fields
▶[]AssetrequiredexpandableBE `/assets` 원본 응답 배열의 각 원소
idnumberrequired
자산 ID
assetTypeAssetTyperequired
자산 타입
numberstringrequired
자산 번호
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
별칭
organizationOrganizationTyperequired
금융기관 코드
organizationNamestringrequired
금융기관명
businessTypeBusinessTyperequired
업종
businessTypeNameBusinessTypeNamerequired
업종명
isHiddenbooleanrequired
숨김 여부
isActivebooleanrequired
활성 여부
isDormantbooleanrequired
휴면 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isFreebooleanrequired
무료 여부
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientTypeClientTyperequired
고객 유형
userAutoAssignEnabledbooleanrequired
자동 할당 여부
▶cardAssetCardInfooptionalexpandable카드 자산 정보
expirationYearstringrequired
만료 연도
expirationMonthstringrequired
만료 월
limitAmountnumberrequired
한도 금액
usedAmountnumberrequired
사용 금액
remainLimitnumberrequired
잔여 한도
previousCardNumberstringoptional
이전 카드 번호
▶bankAccountAssetBankAccountInfooptionalexpandable계좌 자산 정보
accountBalancenumberrequired
계좌 잔액
originalBalancenumberrequired
원본 계좌 잔액
currencyCodestringrequired
통화 코드
startDatestringrequired
조회 시작일
endDatestringrequired
조회 종료일
accountNumberstringrequired
계좌 번호
accountNamestringrequired
계좌명
nickNamestringrequired
별칭
accountTypeAccountTyperequired
계좌 유형
isTransactionVisiblebooleanrequired
거래내역 보유 여부
▶homeTaxAccountAssetHomeTaxAccountInfooptionalexpandable홈택스 자산 정보
category"CASH_RECEIPT" | "TAX_INVOICE"required
홈택스 자산 카테고리
registrationNumberstringrequired
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringrequired
회사명
ceoNamestringrequired
대표자명
addressstringrequired
주소
contactNamestringrequired
담당자명
telstringrequired
연락처
businessTypesstringrequired
업태
businessItemsstringrequired
종목
▶readCertificateobjectoptionalexpandable조회 인증서
idnumberrequired
인증서 ID
isExpiredbooleanrequired
만료 여부
expiredAtstringoptional
만료 시각
connectedAtstringoptional
연결 시각
▶issueCertificateobjectoptionalexpandable발행 인증서
registDateTimestringrequired
등록 시각
expireDateTimestringrequired
만료 시각
issuerDistinguishNamestringrequired
발급자 구분명
issuerNamestringrequired
발급자명
subjectDistinguishNamestringrequired
주체 구분명
oidstringrequired
OID
registContactNamestringrequired
등록자명
registContactIdstringrequired
등록자 ID
▶securitiesAccountAssetSecuritiesAccountInfooptionalexpandable증권 자산 정보
totalAmountnumberrequired
총액(원화)
depositAmountnumberrequired
예수금(원화)
foreignDepositAmountnumberrequired
외화예수금(원화)
▶foreignDepositsForeignDeposit[]requiredexpandable외화예수금 보유 목록
idnumberrequired
외화예수금 ID
currencyCurrencyCoderequired
통화 코드
amountnumberrequired
금액
createdAtstringrequired
생성 시각
totalValuationAmountnumberrequired
보유 주식 평가액 합계(원화)
accountNumberstringrequired
계좌번호
▶productsProduct[]requiredexpandable보유 투자상품
idnumberrequired
상품 ID
productTypestringrequired
상품 유형 코드
productTypeNamestringrequired
상품 유형명
namestringrequired
상품명
codestringoptional
상품 코드
quantitynumberoptional
수량
currencyCurrencyCoderequired
통화 코드
krwPresentAmountnumberoptional
현재 금액(원화)
presentAmountnumberoptional
현재 금액
krwValuationAmountnumberoptional
평가 금액(원화)
valuationAmountnumberoptional
평가 금액
krwValuationPLnumberoptional
평가 손익(원화)
valuationPLnumberoptional
평가 손익
earningsRatenumberoptional
수익률
createdAtstringrequired
생성 시각
▶customAssetAssetCustomInfooptionalexpandable커스텀 자산 정보
assetType"CASH" | "LIABILITY" | "ASSET"required
커스텀 자산 유형
assetNumberstringrequired
자산 번호
amountnumberrequired
금액
▶ecommerceAccountAssetEcommerceAccountInfooptionalexpandable이커머스 스토어 계정 정보
usernamestringrequired
스토어 사용자명
isOtpVerifiedbooleanrequired
OTP 인증 여부
createdAtstringoptional
생성 시각
modifiedAtstringoptional
수정 시각
hasPasswordbooleanoptional
비밀번호 보유 여부
호출
API KEY
REQUEST EXAMPLE (JSON)
호출 예시
cURL
curl -X POST https://app.granter.biz/api/public-docs/assets \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"assetType": "CARD"
}'POST /api/public-docs/assets
Asset Response Example
[
{
"id": 54,
"assetType": "CARD",
"number": "426586******9827",
"workspaceId": 1,
"name": "샘플 법인카드",
"nickname": "운영 카드",
"organization": "KB",
"organizationName": "국민카드",
"businessType": "CD",
"businessTypeName": "CD",
"isHidden": false,
"isActive": true,
"isDormant": false,
"isPossibleDormant": false,
"owners": [
{
"id": 67,
"name": "소유자 A",
"email": "owner-a@example.com",
"isDeleted": false
}
],
"clientType": "CORPORATE",
"userAutoAssignEnabled": true,
"isFree": false,
"hasPassword": false,
"createdAt": "2024-12-25T13:01:51.863136",
"modifiedAt": "2026-03-08T12:05:58.877862",
"card": {
"expirationYear": "2030",
"expirationMonth": "09",
"limitAmount": 1000000,
"usedAmount": 0,
"remainLimit": 0,
"previousCardNumber": null
},
"bankAccount": null,
"homeTaxAccount": null,
"securitiesAccount": null,
"customAsset": null,
"ecommerceAccount": null
}
]POST /api/public-docs/balances
계좌별 잔액 흐름과 현금 추이를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.
startDateYYYY-MM-DDoptional
조회 시작일 (전달 시 endDate와 함께 전달 필수)
endDateYYYY-MM-DDoptional
조회 종료일 (전달 시 startDate와 함께 전달 필수)
Response Fields
▶[]AssetBalancerequiredexpandableBE `/bank-accounts/daily-balances` 응답을 계좌 기준으로 가공한 배열의 각 원소
▶bankAccountTicketAssetrequiredexpandable계좌 자산 정보
idnumberrequired
자산 ID
workspaceIdnumberrequired
워크스페이스 ID
namestringrequired
자산명
nicknamestringrequired
자산 별칭
organizationstringrequired
기관 코드
organizationNamestringrequired
기관명
isActivebooleanrequired
활성 여부
isPossibleDormantbooleanrequired
휴면 가능 여부
isDormantbooleanrequired
휴면 여부
numberstringrequired
자산 번호
▶ownersUserResponse[]requiredexpandable소유자 목록
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
clientType"PERSONAL" | "CORPORATE" | "ALL"required
고객 유형
businessTypestringrequired
업종 코드
businessTypeNamestringrequired
업종명
userAutoAssignEnabledbooleanoptional
유저 자동 할당 여부
expirationYearstringoptional
카드 만료 연도
expirationMonthstringoptional
카드 만료 월
limitAmountnumberoptional
카드 한도 금액
usedAmountnumberoptional
카드 사용 금액
remainLimitnumberoptional
카드 잔여 한도
isAutoApprovalbooleanoptional
자동 승인 여부
previousCardNumberstringoptional
이전 카드번호
accountBalancenumberoptional
계좌 잔액
originalBalancenumberoptional
원본 잔액
currencyCodestringoptional
통화 코드
startDatestringoptional
조회 시작일
endDatestring | nulloptional
조회 종료일
accountTypestringoptional
계좌 유형
isTransactionVisiblebooleanoptional
거래내역 보유 여부
totalAmountnumberoptional
증권 총액
depositAmountnumberoptional
증권 예수금
foreignDepositAmountobject[]optional
외화예수금 상세 목록
foreignDepositsnumberoptional
외화예수금 합계
totalValuationAmountnumberoptional
총 평가금액
accountNumberstringoptional
계좌 번호
productsProduct[]optional
증권 보유 상품 목록
registrationNumberstringoptional
사업자등록번호
establishNumberstringoptional
개업일자 코드
companyNamestringoptional
회사명
ceoNamestringoptional
대표자명
addressstringoptional
주소
contactNamestringoptional
담당자명
emailstringoptional
담당자 이메일
telstringoptional
연락처
businessTypesstringoptional
업태
businessItemsstringoptional
종목
categorystringoptional
홈택스 카테고리
createdAtstringoptional
생성 시각
updatedAtstringoptional
수정 시각
readCertificateobjectoptional
조회 인증서 정보
issueCertificateobjectoptional
발행 인증서 정보
▶balancesBalanceByDate[]requiredexpandable기간별 잔액 목록
baseDateYYYY-MM-DDrequired
잔액 기준일
accountBalancenumberrequired
계좌 잔액 (원화)
originalBalancenumberrequired
원본 통화 기준 잔액
호출
API KEY
REQUEST EXAMPLE (JSON)
호출 예시
cURL
curl -X POST https://app.granter.biz/api/public-docs/balances \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"startDate": "2026-03-01",
"endDate": "2026-03-07"
}'POST /api/public-docs/balances
Balance Response Example
[
{
"bankAccount": {
"id": 3,
"assetType": "BANK_ACCOUNT",
"number": "140014******561",
"workspaceId": 1,
"name": "기업자유예금",
"nickname": "메인 통장",
"organization": "SHINHAN_BANK",
"organizationName": "신한은행",
"businessType": "BK",
"businessTypeName": "BK",
"isHidden": false,
"isActive": true,
"isDormant": false,
"isPossibleDormant": false,
"owners": [
{
"id": 9,
"name": "소유자 B",
"email": "owner-b@example.com",
"isDeleted": false
}
],
"clientType": "CORPORATE",
"userAutoAssignEnabled": true,
"isFree": false,
"hasPassword": false,
"createdAt": "2024-07-18T11:23:29.369334",
"modifiedAt": "2026-03-08T12:06:11.683152",
"card": null,
"bankAccount": {
"accountBalance": -89911970,
"originalBalance": "-89911970",
"currencyCode": "KRW",
"startDate": "20240119",
"endDate": "",
"accountNumber": "140014******561",
"accountName": "기업자유예금",
"nickName": "메인 통장",
"accountType": "DEPOSIT",
"isTransactionVisible": true
},
"homeTaxAccount": null,
"securitiesAccount": null,
"customAsset": null,
"ecommerceAccount": null
},
"balances": [
{
"accountBalance": -89911970,
"baseDate": "2026-03-01",
"originalBalance": -89911970
},
{
"accountBalance": -89911970,
"baseDate": "2026-03-02",
"originalBalance": -89911970
}
]
}
]GET /api/public-docs/tag-details
1차 태그 아래의 세부 분류 기준 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
Response Fields
▶[]TagrequiredexpandableBE `/tag-details` 원본 응답 배열의 각 원소
idnumberrequired
1차/2차 태그 ID
namestringrequired
1차/2차 태그명
descriptionstringrequired
설명
createdAtstringrequired
생성 시각
modifiedAtstringrequired
수정 시각
type"Tag" | "TagDetail" | "Supplier"required
태그 분류 타입 (Tag=1차 태그, TagDetail=2차 태그)
workspaceIdnumberoptional
워크스페이스 ID
tagIdnumberoptional
상위 1차 태그 ID (2차 태그에 해당)
codestring | numberoptional
코드
outAmountnumberoptional
지출 집계 금액
inAmountnumberoptional
입금 집계 금액
isHiddennumber | booleanoptional
숨김 여부
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/tag-details \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/tag-details
2차 태그 Response Example
[
{
"id": 5,
"workspaceId": 1,
"name": "마케팅 비용",
"description": "",
"tagId": 82,
"isHidden": false,
"createdAt": "2024-11-11T19:58:19.541909",
"modifiedAt": "2026-01-30T14:38:32.668294"
}
]GET /api/public-docs/categories
회계 처리와 분석에 사용하는 계정과목 기준 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
Response Fields
▶[]ExpenseCategoryrequiredexpandableBE `/expense-categories` 원본 응답 배열의 각 원소
idnumberrequired
계정과목 ID
namestringrequired
계정과목명
subInfostringrequired
부가 정보
descriptionstringrequired
설명
codenumber | stringrequired
코드
type"COMMON" | "CUSTOM"required
카테고리 타입
isHiddenbooleanrequired
숨김 여부
costType"NONE" | "VARIABLE" | "FIXED"required
비용 유형
isFavoritebooleanrequired
즐겨찾기 여부
workspaceIdnumberoptional
워크스페이스 ID
taxType"DETERMINE_NEEDED" | "TAXABLE" | "EXEMPT" | "ZERO_RATED" | nulloptional
기본 과세 유형
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/categories \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/categories
Category Response Example
[
{
"id": 285,
"name": "가수금",
"subInfo": "부채",
"description": "계정과목이 명확치 않은 현금 입금액",
"code": "257",
"type": "COMMON",
"isHidden": false,
"costType": "VARIABLE",
"isFavorite": false,
"taxType": null
}
]GET /api/public-docs/people
담당자, 결재자, 분류 주체로 활용되는 워크스페이스 구성원 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
Response Fields
▶[]UserrequiredexpandableBE `/workspaces` 응답의 `users` 배열 원본
idnumberrequired
유저 ID
namestringrequired
이름
emailstringrequired
이메일
workspaceIdnumberoptional
워크스페이스 ID
workspaceNamestringoptional
워크스페이스명
teamIdnumberoptional
팀 ID
teamNamestringoptional
팀명
phoneNumberstringoptional
전화번호
▶roleWorkspaceRolerequiredexpandable워크스페이스 역할
idnumberrequired
역할 ID
namestringrequired
역할명
isOwnerbooleanrequired
오너 여부
isDefaultbooleanrequired
기본 역할 여부
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/people \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/people
People Response Example
[
{
"id": 4,
"name": "구성원 A",
"email": "member-a@example.com",
"workspaceId": 1,
"workspaceName": "샘플 워크스페이스",
"teamId": 133,
"teamName": "마케팅팀",
"nickname": "담당자 A",
"phoneNumber": "01012345678",
"role": {
"id": 1,
"name": "소유자",
"isOwner": true,
"isDefault": false
},
"cards": [],
"notificationConfig": {
"userId": 4,
"slack": false,
"appPush": false,
"email": false,
"kakao": false
}
}
]GET /api/public-docs/contacts
거래처, 고객사, 공급사처럼 상대방 기준으로 관리하는 거래처 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
현재 응답은 최신 거래처 목록 기준으로 최대 100건을 조회합니다.
Response Fields
▶[]ContactrequiredexpandableBE `/contacts` 원본 응답 배열의 각 원소
idnumberrequired
거래처 ID
workspaceIdnumberrequired
워크스페이스 ID
registrationNumberstringrequired
사업자등록번호
companyNamestringrequired
회사명
ceoNamestringrequired
대표자명
businessTypesstringrequired
업태
businessItemsstringrequired
종목
businessPlacestringrequired
사업장 주소
emailstring | nulloptional
이메일
email2string | nulloptional
보조 이메일
phonestring | nulloptional
휴대전화
telstring | nulloptional
전화번호
lastIssuedAtstringrequired
최근 발행 시각
region"DOMESTIC" | "FOREIGN"optional
거래처 지역 구분
isHiddenbooleanoptional
숨김 여부
▶managersContactManager[]optionalexpandable거래처 담당자 목록
idnumberrequired
거래처 담당자 ID
contactIdnumberrequired
거래처 ID
namestringrequired
담당자 이름
phoneNumberstring | nulloptional
휴대전화
telNumberstring | nulloptional
전화번호
faxNumberstring | nulloptional
팩스번호
emailstring | nulloptional
이메일
memostringrequired
메모
nationstringoptional
국가
accountNumberstring | nulloptional
계좌번호
bankNamestring | nulloptional
은행명
bankAccountOwnerNamestring | nulloptional
예금주명
memostringoptional
메모
isFavoritebooleanoptional
즐겨찾기 여부
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/contacts \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/contacts
Contact Response Example
[
{
"id": 928,
"workspaceId": 1,
"registrationNumber": "1111111111",
"companyName": "샘플 거래처",
"ceoName": "대표자 A",
"businessTypes": "",
"businessItems": "",
"businessPlace": "",
"email": null,
"email2": null,
"phone": null,
"tel": null,
"bankName": null,
"bankAccountOwnerName": null,
"accountNumber": null,
"lastIssuedAt": "2026-02-19T16:32:29.514778",
"managers": [],
"region": "DOMESTIC",
"nation": "",
"isHidden": false,
"memo": "",
"isFavorite": false
}
]GET /api/public-docs/teams
구성원을 조직 단위로 묶어 관리하는 팀 기준 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
Response Fields
▶[]TeamrequiredexpandableBE `/teams` 원본 응답 배열의 각 원소
idnumberrequired
팀 ID
namestringrequired
팀명
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/teams \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/teams
Team Response Example
[
{
"id": 6,
"name": "인사팀"
}
]GET /api/public-docs/workflows
기안 문서, 결재 상태, 결재선 정보를 포함한 전자결재 데이터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
직접 호출 시 `status`, `draftedByMe`, `limit`, `offset` query string을 사용할 수 있습니다.
테스트 패널은 기본 목록 조회를 수행합니다.
status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"optional
결재 상태 필터
draftedByMebooleanoptional
내가 올린 결재만 조회할지 여부
limitnumberoptional
조회 건수 제한. 지정하지 않으면 최대 100건까지 조회합니다.
offsetnumberoptional
페이지 오프셋
Response Fields
▶[]WorkflowrequiredexpandableBE `/workflows` 원본 응답 배열의 각 원소
idnumberrequired
전자결재 ID
workspaceIdnumberrequired
워크스페이스 ID
titlestringrequired
결재안 제목
contentstringrequired
결재 내용
amountnumberrequired
결재 금액
originalAmountnumberrequired
원본 결재 금액
expectedPaymentDateYYYY-MM-DDrequired
이체 요청일
status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required
결재 상태
currencystringrequired
통화 코드
createdAtISO-8601 stringrequired
결재 요청 시각
modifiedAtISO-8601 stringrequired
최종 수정 시각
currentStepnumberrequired
현재 결재 차수
tagstring | nulloptional
연결된 태그명
tagIdnumber | nulloptional
연결된 태그 ID
▶userUserrequiredexpandable기안자 정보
idnumberrequired
기안자 ID
namestringrequired
기안자 이름
emailstringrequired
기안자 이메일
isDeletedbooleanrequired
삭제 여부
▶refundAccountRefundAccountoptionalexpandable환급 계좌 정보
accountHolderstringrequired
예금주명
accountNumberstringrequired
계좌번호
organizationNamestringrequired
은행명
▶stepsWorkflowStep[]requiredexpandable결재 단계 목록
idnumberrequired
결재 단계 ID
stepnumberrequired
결재 차수
status"REQUESTED" | "APPROVED" | "REJECTED" | "COMPLETED"required
결재 단계 상태
createdAtISO-8601 stringrequired
생성 시각
modifiedAtISO-8601 stringrequired
수정 시각
▶approverApproverrequiredexpandable결재자 정보
idnumberrequired
결재자 ID
namestringrequired
결재자 이름
emailstringrequired
결재자 이메일
isDeletedbooleanrequired
삭제 여부
▶reviewersReviewer[]requiredexpandable검토자 목록
idnumberrequired
검토자 연결 ID
▶reviewerUserResponserequiredexpandable검토자 정보
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
▶messagesWorkflowMessage[]optionalexpandable결재 메시지 목록
idnumberrequired
메시지 ID
contentstringrequired
메시지 내용
typestringrequired
메시지 타입
createdAtISO-8601 stringrequired
생성 시각
deletedAtISO-8601 string | nulloptional
삭제 시각
▶userUserResponserequiredexpandable작성자 정보
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
▶attachmentsWorkflowAttachment[]optionalexpandable첨부파일 목록
idnumberrequired
첨부파일 ID
namestringrequired
파일명
uploadedUrlstringrequired
업로드 URL
contentTypestringrequired
MIME 타입
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/workflows \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/workflows
Workflow Response Example
[
{
"id": 333,
"workspaceId": 1,
"user": {
"id": 8,
"name": "기안자 A",
"email": "drafter@example.com",
"isDeleted": false
},
"title": "3월 운영비 집행",
"content": "<p>3월 운영비 집행 승인 요청입니다.</p>",
"amount": 50000,
"originalAmount": 50000,
"expectedPaymentDate": "2026-02-11",
"status": "COMPLETED",
"currentStep": 1,
"currency": "KRW",
"createdAt": "2026-02-11T11:12:14.478782",
"messages": [
{
"id": 878,
"user": {
"id": 8,
"name": "기안자 A",
"email": "drafter@example.com",
"isDeleted": false
},
"content": "1차 결재가 승인되었습니다.",
"type": "SYSTEM",
"createdAt": "2026-02-11T11:12:25.120704",
"deletedAt": null
},
{
"id": 879,
"user": {
"id": 8,
"name": "기안자 A",
"email": "drafter@example.com",
"isDeleted": false
},
"content": "결재 상태가 결재완료로 변경되었습니다.",
"type": "SYSTEM",
"createdAt": "2026-02-11T11:12:27.811770",
"deletedAt": null
}
],
"attachments": [],
"refundAccount": null,
"steps": [
{
"id": 573,
"approver": {
"id": 8,
"name": "결재자 A",
"email": "approver@example.com",
"isDeleted": false
},
"step": 1,
"status": "APPROVED",
"createdAt": "2026-02-11T11:12:14.483147",
"modifiedAt": "2026-02-11T11:12:25.137155"
}
],
"reviewers": [],
"tag": null,
"tagId": null,
"modifiedAt": "2026-02-11T11:12:27.813271"
}
]POST /api/public-docs/salary-histories
직원별 급여 내역, 지급 상태, 보험료, 수당·공제 상세를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
급여는 티켓과 분리된 독립 도메인입니다.
조회 시 `startDate`, `endDate`는 필수입니다.
기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.
`employmentType`, `salaryPaymentStatus`, `employeeId`, `keyword`는 선택 필터입니다.
startDateYYYY-MM-DDrequired
조회 시작일
endDateYYYY-MM-DDrequired
조회 종료일
employmentType"REGULAR_EMPLOYEE" | "NON_REGULAR_EMPLOYEE" | "SPECIAL_EMPLOYEE" | "REPRESENTATIVE" | arrayoptional
고용 형태 필터. 단일 값 또는 배열을 전달할 수 있습니다.
salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID" | arrayoptional
급여 지급 상태 필터. 단일 값 또는 배열을 전달할 수 있습니다.
employeeIdnumberoptional
직원 ID 필터
keywordstringoptional
직원명 또는 설명 키워드 검색
Response Fields
▶[]SalaryHistoryrequiredexpandableBE `/salary-histories` 원본 응답 배열의 각 원소
idnumberrequired
급여 이력 ID
workspaceIdnumberrequired
워크스페이스 ID
▶employeeUserResponseoptionalexpandable직원 정보
idnumberrequired
유저 ID
namestringrequired
유저 이름
emailstringrequired
유저 이메일
isDeletedbooleanrequired
삭제 여부
employeeIdnumberrequired
직원 ID
employeeNamestringoptional
직원명
employeeEmailstring | nulloptional
직원 이메일
employmentType"REGULAR_EMPLOYEE" | "NON_REGULAR_EMPLOYEE" | "SPECIAL_EMPLOYEE" | "REPRESENTATIVE"required
고용 형태
totalAmountnumberrequired
총급여
recognizedAmountnumberrequired
실질인정금액
paymentDateYYYY-MM-DDrequired
지급일
mealAmountnumberrequired
비과세 식대
bonusAmountnumberrequired
상여금
allowanceAmountnumberrequired
수당 합계
pensionInsuranceAmountnumberrequired
국민연금
healthInsuranceAmountnumberrequired
건강보험
employInsuranceAmountnumberrequired
고용보험
careInsuranceAmountnumberrequired
장기요양보험
bankstringoptional
은행명
bankAccountstringoptional
은행 계좌번호
netAmountnumberrequired
실지급액
descriptionstringoptional
설명
employmentDiscount"NONE" | "GENERAL" | "YOUTH"required
고용 할인 유형
incomeTaxAmountnumberoptional
소득세
localIncomeTaxAmountnumberoptional
지방소득세
salaryPaymentStatus"PENDING" | "REVIEWED" | "PAID"required
급여 지급 상태
isEmailNotifiedbooleanrequired
명세서 email 발송 여부
emailNotifiedAtISO-8601 string | nulloptional
email 발송 시각
messageCountnumberrequired
메시지 개수
scheduledWorkHoursnumberrequired
당월 근무 시간
shortfallHoursnumberrequired
미달 근무 시간
unpaidLeaveHoursnumberoptional
무급휴가 시간
recognizedWorkHoursnumberrequired
근무 인정 시간
appliedRatioTypestringoptional
적용 비율 타입
appliedRationumberoptional
적용 비율
▶taxExemptionsTitleAmount[]optionalexpandable비과세급 상세
titlestringrequired
항목명
amountnumberrequired
금액
▶incentivesTitleAmount[]optionalexpandable인센티브 상세
titlestringrequired
항목명
amountnumberrequired
금액
▶allowancesTitleAmount[]optionalexpandable수당 상세
titlestringrequired
항목명
amountnumberrequired
금액
▶deductionsTitleAmount[]optionalexpandable공제 상세
titlestringrequired
항목명
amountnumberrequired
금액
createdAtISO-8601 stringrequired
생성 시각
modifiedAtISO-8601 stringrequired
수정 시각
호출
API KEY
REQUEST EXAMPLE (JSON)
호출 예시
cURL
curl -X POST https://app.granter.biz/api/public-docs/salary-histories \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"startDate": "2026-02-01",
"endDate": "2026-02-28"
}'POST /api/public-docs/salary-histories
Salary History Response Example
[
{
"id": 303,
"workspaceId": 1,
"employee": {
"id": 67,
"name": "직원 A",
"email": "employee-a@example.com",
"isDeleted": false
},
"employeeName": "직원 A",
"employeeEmail": null,
"employmentType": "REGULAR_EMPLOYEE",
"totalAmount": 5000000,
"paymentDate": "2026-02-01",
"mealAmount": 3000,
"bonusAmount": 10000,
"pensionInsuranceAmount": 261000,
"healthInsuranceAmount": 198080,
"employInsuranceAmount": 49580,
"careInsuranceAmount": 26020,
"bank": "국민은행",
"bankAccount": "123-45-****",
"recognizedAmount": 5003000,
"netAmount": 4519877,
"description": "",
"employmentDiscount": "NONE",
"incomeTaxAmount": 405590,
"localIncomeTaxAmount": 40550,
"salaryPaymentStatus": "PENDING",
"isEmailNotified": false,
"emailNotifiedAt": null,
"messageCount": 0,
"scheduledWorkHours": 28,
"shortfallHours": 0,
"unpaidLeaveHours": 0,
"recognizedWorkHours": 28,
"allowanceAmount": 500000,
"appliedRatioType": "",
"appliedRatio": 1,
"taxExemptions": [{ "title": "비과세급", "amount": 3000 }],
"incentives": [{ "title": "상여금", "amount": 10000 }],
"allowances": [{ "title": "직책수당", "amount": 500000 }],
"deductions": [{ "title": "기타 공제", "amount": 12303 }],
"createdAt": "2026-02-11T14:02:48.545431",
"modifiedAt": "2026-02-28T14:22:59.327028"
}
]GET /api/public-docs/inventory-products
품목명, 단가, 통화, 추가 속성으로 구성된 품목 마스터를 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
직접 호출 시 `limit`, `lastSeenId` query string을 사용할 수 있습니다.
limitnumberoptional
조회 건수 제한
lastSeenIdnumberoptional
페이지네이션 기준 ID
Response Fields
▶[]InventoryProductrequiredexpandableBE `/inventory-products` 원본 응답 배열의 각 원소
idnumberrequired
품목 ID
namestringrequired
품목명
unitPricenumberrequired
단가
currencyCurrencyCoderequired
통화 코드
▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable추가 속성 목록
idnumberrequired
추가 속성 ID
keystringrequired
속성명
valuestringrequired
속성값
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/inventory-products \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/inventory-products
Inventory Product Response Example
[
{
"id": 63,
"name": "샘플 품목 A",
"unitPrice": 123,
"currency": "KRW",
"additionalProperties": [
{ "id": 23, "key": "EXP date", "value": "" },
{ "id": 22, "key": "창고", "value": "" },
{ "id": 13, "key": "커스텀속성2", "value": "" }
]
}
]GET /api/public-docs/inventories
품목별 현재 재고 수량, 재고 메시지 수, 최근 수정 시각을 포함한 재고 현황을 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
요청 body는 사용하지 않습니다.
직접 호출 시 `limit`, `lastSeenId` query string을 사용할 수 있습니다.
limitnumberoptional
조회 건수 제한
lastSeenIdnumberoptional
페이지네이션 기준 ID
Response Fields
▶[]InventoryStockrequiredexpandableBE `/inventories` 원본 응답 배열의 각 원소
idnumberrequired
재고 엔트리 ID
inventoryProductIdnumberrequired
품목 ID
namestringrequired
품목명
unitPricenumberrequired
단가
quantitynumberrequired
현재 재고 수량
currencyCurrencyCoderequired
통화 코드
createdAtISO-8601 stringrequired
생성 시각
modifiedAtISO-8601 stringrequired
수정 시각
messageCountnumberrequired
메시지 개수
▶additionalPropertiesInventoryAdditionalProperty[]optionalexpandable추가 속성 목록
idnumberrequired
추가 속성 ID
keystringrequired
속성명
valuestringrequired
속성값
호출
API KEY
호출 예시
cURL
curl -X GET https://app.granter.biz/api/public-docs/inventories \ -H "Authorization: Basic <BASE64(API_KEY:)>"
GET /api/public-docs/inventories
Inventory Stock Response Example
[
{
"id": 3,
"inventoryProductId": 2,
"name": "샘플 재고 품목 A",
"unitPrice": 880000,
"quantity": 10,
"currency": "KRW",
"createdAt": "2025-12-05T12:29:29.850909",
"modifiedAt": "2026-02-11T13:05:46.900783",
"messageCount": 0,
"additionalProperties": [
{ "id": 18, "key": "1211", "value": "123123" },
{ "id": 14, "key": "123", "value": "123" },
{ "id": 22, "key": "창고", "value": "" }
]
}
]POST /api/public-docs/attendances
구성원의 출퇴근 기록과 휴가 사용 내역을 기간별로 조회합니다.
Request Fields
`workspaceId`는 요청값을 받지 않고 API key에서 자동으로 결정됩니다.
조회 시 `startDate`, `endDate`는 필수입니다.
기간 기반 조회는 요청 1회당 최대 31일까지 사용할 수 있으며, 더 긴 범위는 31일 이하 구간으로 나눠 조회한 뒤 합쳐서 사용하세요.
`userIds`로 특정 구성원만 필터링하거나, `recordType`으로 근무/휴가를 구분할 수 있습니다.
startDateYYYY-MM-DDrequired
조회 시작일
endDateYYYY-MM-DDrequired
조회 종료일
userIdsnumber[]optional
조회 대상 유저 ID 목록
recordType"WORK" | "LEAVE"optional
기록 타입 필터. WORK: 근무만, LEAVE: 휴가만, 미입력 시 전체
Response Fields
▶[]TimeCardRecordrequiredexpandable근무/휴가 기록 배열
▶timeCardTimeCardrequiredexpandable타임카드 정보
workspaceIdnumberrequired
워크스페이스 ID
userIdnumberrequired
유저 ID
baseDateYYYY-MM-DDrequired
기준일
startedAtISO-8601 stringrequired
시작 일시
endedAtISO-8601 stringoptional
종료 일시
createdAtISO-8601 stringrequired
생성 일시
modifiedAtISO-8601 stringrequired
수정 일시
▶workRecordWorkRecord | nulloptionalexpandable근무 기록 (휴가인 경우 null)
workRecordIdnumberrequired
근무 기록 ID
▶clockInLocationClockLocationrequiredexpandable출근 위치
ipstringrequired
IP 주소
addressstringrequired
주소
addressDetailstringrequired
상세 주소
latitudenumberrequired
위도
longitudenumberrequired
경도
radiusnumberrequired
허용 반경 (m)
▶clockOutLocationClockLocation | nulloptionalexpandable퇴근 위치
ipstringrequired
IP 주소
addressstringrequired
주소
addressDetailstringrequired
상세 주소
latitudenumberrequired
위도
longitudenumberrequired
경도
radiusnumberrequired
허용 반경 (m)
isRemotebooleanrequired
원격 근무 여부
▶leaveRecordLeaveRecord | nulloptionalexpandable휴가 기록 (근무인 경우 null)
leaveRecordIdnumberrequired
휴가 기록 ID
approverUserIdnumber | nulloptional
결재자 유저 ID
reasonstringrequired
휴가 사유
statusREQUESTED | APPROVED | REJECTEDrequired
승인 상태
approvedAtISO-8601 string | nulloptional
승인 일시
rejectedAtISO-8601 string | nulloptional
반려 일시
rejectedReasonstring | nulloptional
반려 사유
createdAtISO-8601 stringrequired
생성 일시
modifiedAtISO-8601 stringrequired
수정 일시
호출
API KEY
REQUEST EXAMPLE (JSON)
호출 예시
cURL
curl -X POST https://app.granter.biz/api/public-docs/attendances \
-H "Content-Type: application/json" \
-H "Authorization: Basic <BASE64(API_KEY:)>" \
-d '{
"startDate": "2026-03-01",
"endDate": "2026-03-15"
}'POST /api/public-docs/attendances
Attendance Response Example
[
{
"timeCard": {
"workspaceId": 1,
"userId": 67,
"baseDate": "2026-03-10",
"startedAt": "2026-03-10T09:00:00",
"endedAt": "2026-03-10T18:00:00",
"createdAt": "2026-03-10T09:00:12.345678",
"modifiedAt": "2026-03-10T18:00:45.123456"
},
"workRecord": {
"workRecordId": 101,
"clockInLocation": {
"ip": "192.168.1.10",
"address": "서울특별시 강남구",
"addressDetail": "테헤란로 123",
"latitude": 37.5065,
"longitude": 127.0536,
"radius": 200.0
},
"clockOutLocation": {
"ip": "192.168.1.10",
"address": "서울특별시 강남구",
"addressDetail": "테헤란로 123",
"latitude": 37.5065,
"longitude": 127.0536,
"radius": 200.0
},
"isRemote": false
},
"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"
}
}
]Error Responses
401 Unauthorized
Basic Authorization 헤더가 없거나, API key가 유효하지 않거나, API key에서 workspace 정보를 확인할 수 없는 경우
400 Bad Request
요청 body 형식/값이 잘못된 경우
티켓 API 유효성 규칙: `ticketType` 필수, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`, ID 필드는 양의 정수
잔액 API 유효성 규칙: `startDate/endDate`는 함께 전달, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`
급여 API 유효성 규칙: `startDate/endDate` 필수, `startDate/endDate`는 `YYYY-MM-DD` 형식, `startDate <= endDate`, `employeeId`는 양의 정수
429 Too Many Requests
API key 기준 분당 60회 제한을 초과한 경우
Aggregation Tips
1) 집계 설계의 기본 원칙
- 집계용 리포트를 만들 때는 `tickets`를 원천 이벤트, `balances`를 잔액 시계열로 나눠 보는 편이 가장 안전합니다. 거래 합계와 분류는 `tickets`, 시작/종료 잔액은 `balances` 기준으로 해석하세요.
- 기간 버킷은 보통 `daily`, `monthly`, `quarterly`, `total` 중 하나로 먼저 정하고, 그다음 `category`, `tag`, `user`, `contact`, `asset` 같은 집계 축을 선택해 표를 구성합니다.
- 실무에서는 보통 `기간 -> 자산/티켓 타입 -> isIncluded=true -> 중복 거래 제외 -> 태그/계정과목/거래처` 순서로 필터를 적용한 뒤 집계를 시작하면 결과가 안정적입니다.
- 금액은 `amount` 하나만 보지 말고 `transactionType`, `inAmount`, `outAmount`를 함께 해석하세요. 특히 지출표와 입출금표를 같은 규칙으로 합치려면 방향값을 분리해 두는 편이 좋습니다.
{
"period": "monthly",
"filters": {
"ticketTypes": ["EXPENSE_TICKET", "BANK_TRANSACTION_TICKET"],
"startDate": "2026-02-01",
"endDate": "2026-02-28",
"isIncluded": true
},
"groupBy": "expenseCategoryId"
}2) 예시: 월별 계정과목별 지출내역
- 월별 지출표는 보통 `tickets`와 `categories`를 같이 씁니다. 먼저 카드/계좌/수기 등 보고 싶은 티켓 타입을 모으고, `transactionType=OUT`, `isIncluded=true`인 건만 남깁니다.
- 그다음 `transactAt -> YYYY-MM`으로 월 버킷을 만들고, `expenseCategory.id` 기준으로 묶습니다. 표시명과 고정비/변동비 구분이 필요하면 `categories.id`로 조인해 `name`, `costType`을 붙입니다.
- 비용 리포트는 이렇게 만든 계정과목별 월 금액을 다시 합쳐 `총 소비`, `고정비`, `변동비`, `기타` 같은 상위 지표를 만듭니다. 즉, `월-계정과목` 1차 집계 테이블을 먼저 만들고 그 위에 상위 지표를 2차 계산하는 구조입니다.
- 손익계산서처럼 더 높은 단계의 리포트가 필요하면 `categories.subInfo`를 이용해 `매출`, `매출원가`, `판매관리비`, `영업외수익`, `영업외비용`으로 다시 묶어 `매출총이익`, `영업이익`, `세전이익`을 계산하면 됩니다.
[
{
"period": "2026-02",
"categoryId": 101,
"categoryName": "식비",
"costType": "VARIABLE",
"outAmount": -158000,
"displayAmount": 158000,
"count": 9
},
{
"period": "2026-02",
"categoryId": 205,
"categoryName": "급여",
"costType": "FIXED",
"outAmount": -4200000,
"displayAmount": 4200000,
"count": 4
}
]3) 예시: 자금일보 구성
- 자금일보는 `잔액 요약`과 `거래 상세`를 분리해서 만드는 편이 안정적입니다. 상단 잔액 표는 `balances`로 전일 잔액과 현재 잔액을 잡고, 같은 기간 `tickets`를 합산해 입금/출금 합계를 붙입니다.
- 화면 구성은 보통 상단에 자산별 `이전잔액 + 입출금 합계 + 현재잔액`을 두고, 하단에는 `계좌 입출금`, `카드 사용`, `세금계산서`, `현금영수증`, `수기관리` 같은 상세 테이블을 분리하는 방식이 읽기 쉽습니다.
- 체크카드 승인과 계좌 출금처럼 중복 가능성이 있는 건은 연결된 계좌 내역을 제외하는 규칙을 함께 두는 편이 좋습니다. 이렇게 해야 대표 거래만 남고 자금 흐름이 과대 집계되지 않습니다.
- 핵심은 `잔액은 balances`, `흐름과 분류는 tickets`로 역할을 나누는 것입니다. 티켓만으로 순유입을 계산할 수는 있지만, 그 값이 자금일보의 기초/기말 잔액과 항상 같지는 않습니다.
{
"date": "2026-03-08",
"balances": [
{
"assetId": 11,
"assetName": "국민은행",
"openingBalance": 12500000,
"inAmount": 3200000,
"outAmount": -1850000,
"closingBalance": 13850000
}
],
"sections": {
"bankTransactions": [{ "ticketId": 1, "content": "거래처 입금", "amount": 3200000 }],
"cardExpenses": [{ "ticketId": 2, "content": "점심 식대", "amount": 12000 }],
"taxInvoices": [],
"cashReceipts": [],
"manualTransactions": []
}
}4) 같은 방식으로 확장할 수 있는 집계
- 태그별 분석은 `tagId`, `tagDetailId` 기준으로 같은 집계 패턴을 반복하면 됩니다. 계정과목 집계와 구조는 같고, 그룹 축만 바뀝니다.
- 거래처별 분석은 `contactId`, 담당자별 분석은 `user_ids`를 기준으로 묶습니다. 여러 사용자가 함께 사용한 건은 `amount / user_count`처럼 균등 배분 규칙을 미리 정해 두면 인원별 집계가 흔들리지 않습니다.
- 외부 대시보드는 `원천 티켓 보관 -> 1차 집계 테이블 생성 -> 리포트별 2차 계산` 흐름으로 설계하면 월별 지출표, 자금일보, 태그 리포트 같은 화면을 일관된 규칙으로 확장하기 쉽습니다.