현금영수증 목록 조회
GET /v2/cash-receipts 로 워크스페이스의 현금영수증을 상태, 종류, 발급 방식, 주문, 날짜로 걸러 조회해요.
GET /v2/cash-receipts
워크스페이스의 현금영수증을 최신순으로 조회해요. 원본 현금영수증과 취소 영수증, 발급에 실패한 현금영수증이 모두 나와요.
쿼리 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
offset |
integer | 건너뛸 항목 수예요. 0 이상이에요. 기본값은 0이에요. |
|
limit |
integer | 가져올 항목 수예요. 1~100이에요. 기본값은 100이에요. |
|
search |
string | 현금영수증 ID, 주문 ID, 국세청 승인번호, 주문번호(1043, #1043)가 같거나, 구매자 이름에 검색어가 들어간 현금영수증을 찾아요. 숫자가 3자리 이상이면 식별번호에서도 찾고, 하이픈은 무시해요. |
|
status |
string | PENDING, ISSUED, FAILED, CANCELED 중에서 골라요. 여러 개를 쉼표로 이어 보낼 수 있어요. |
|
type |
string | PERSONAL, CORPORATE 중에서 골라요. |
|
method |
string | AUTO, MANUAL 중에서 골라요. |
|
kind |
string | ORIGINAL, CANCELLATION 중에서 골라요. |
|
invoiceId |
string | 이 주문에 연결된 현금영수증만 조회해요. | |
dateFrom |
string | 이 날짜(KST)부터 발급을 요청한 현금영수증만 조회해요. YYYY-MM-DD |
|
dateTo |
string | 이 날짜(KST)까지 발급을 요청한 현금영수증만 조회해요. 그날도 포함해요. YYYY-MM-DD |
주문에 자동 발급된 현금영수증을 찾으려면 invoiceId와 kind=ORIGINAL을 함께 쓰세요.
요청 예시
curl "https://api.paysync.kr/v2/cash-receipts?offset=0&limit=20&status=FAILED" \
-H "Authorization: Bearer $PAYSYNC_API_KEY"const params = new URLSearchParams({ offset: "0", limit: "20", status: "FAILED" });
const res = await fetch(`https://api.paysync.kr/v2/cash-receipts?${params}`, {
headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { items, totalItems } = await res.json();import os
import requests
res = requests.get(
"https://api.paysync.kr/v2/cash-receipts",
headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
params={"offset": 0, "limit": 20, "status": "FAILED"},
)
print(res.json())응답
items는 현금영수증 객체 배열이고, totalItems는 조건에 맞는 전체 수예요.
{
"code": "10001",
"items": [
{
"id": "crt_b2c3d4e5f6g7h8i9j0k1l2m3",
"kind": "ORIGINAL",
"status": "FAILED",
"type": "PERSONAL",
"identifier": "0101234567",
"amount": 32000,
"failure": {
"stage": "NTS",
"code": "TS1",
"message": "구매자 식별번호(휴대폰 번호·사업자등록번호)가 유효하지 않아요.",
"action": "FIX_IDENTIFIER"
},
"reissuedToId": null,
"...": "..."
}
],
"totalItems": 1
}
오류
| HTTP | code |
발생 조건 |
|---|---|---|
| 401 | 290006 |
API 키가 올바르지 않아요. |
| 403 | 40001 |
limit이 100을 넘어요. |
| 422 | 30001 |
offset이 0보다 작아요. |
| 422 | 30002 |
limit이 0 이하예요. |
| 422 | 30004 |
dateFrom이나 dateTo가 YYYY-MM-DD 형식이 아니에요. |
| 422 | 30005 |
dateFrom이 dateTo보다 늦어요. |
| 422 | 220001 |
invoiceId 형식이 틀렸어요. |
| 422 | 240002 |
type 값이 목록에 없어요. |
| 422 | 240011 |
status 값이 목록에 없어요. |
| 422 | 240015 |
kind 값이 목록에 없어요. |
| 422 | 240016 |
method 값이 목록에 없어요. |