請求與回應的基本（JSON）

API 請求回應 JSON 分頁

本文的對象
適用於實作呼叫 ReceiptRoller API 的用戶端的開發者。

請求的基本

協定：HTTPS 必須（HTTP 拒絕）
格式：請求本文、回應皆為 JSON
字元碼：UTF-8
驗證：Authorization: Bearer {access_token}

必要、建議標頭

Authorization: Bearer eyJhbGciOi...    ← 必要
Content-Type: application/json          ← POST/PUT 必要
Accept: application/json                ← 建議
User-Agent: MyApp/1.2.3                 ← 建議（聯繫時的特定用）
Idempotency-Key: 01HV6N3M2K...          ← POST/PUT 建議（防止重複）

回應的基本結構

單一資源

{
  "id": "rcp_xyz789",
  "object": "receipt",
  "created_at": "2026-04-27T10:15:23Z",
  "store_id": "str_abc123",
  "total_amount": 3850,
  "currency": "JPY"
}

一覽（帶分頁）

{
  "object": "list",
  "data": [
    { "id": "rcp_001", ... },
    { "id": "rcp_002", ... }
  ],
  "has_more": true,
  "next_cursor": "cur_xxx"
}

分頁（游標方式）

一覽 API 為游標方式。以 ?limit=50&cursor={前次的 next_cursor} 取得下一頁。

預設 limit: 20、最大: 100
has_more: false 則為最終頁
游標有效 6 小時
排序原則上為新到舊（created_at DESC）

篩選

以查詢參數篩選。

GET /v1/receipts?store_id=str_abc&issued_after=2026-04-01&issued_before=2026-04-30

支援的比較運算子：
?total_amount[gte]=1000     ← 1000 以上
?total_amount[lt]=5000      ← 未滿 5000
?status[in]=issued,refunded ← 任一

日期時間格式

全部為 ISO 8601 格式（YYYY-MM-DDTHH:mm:ssZ）
回應固定為 UTC（末尾 Z）
請求時可帶時區傳送（自動轉換為 UTC）

金額的表現

金額為最小貨幣單位的整數（例：JPY 則 1=1 圓，USD 則 1=1 分）
不含小數點、千分位
貨幣以 currency 欄位明示（ISO 4217）

ID 的格式

所有資源 ID 都帶有前綴。可一眼辨別型別。

前綴	資源
`rcp_`	收據
`str_`	店鋪
`prd_`	商品
`cus_`	顧客
`evt_`	事件

冪等性鍵（Idempotency-Key）

在 POST/PUT 指定相同的 Idempotency-Key 時，ReceiptRoller 端會偵測重複，回傳最初的結果。可防止網路重試時的二次建立。

使用 UUID 或 ULID 等唯一的值
鍵會保存 24 小時
不同的端點間不共享