リクエストとレスポンスの基本（JSON）

API リクエストレスポンス JSON ページネーション

この記事の対象
レシートローラー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 を指定すると、レシートローラー側で重複検知し、最初の結果を返します。ネットワーク再試行時の二重作成を防げます。

UUIDやULIDなど一意な値を使用
キーは24時間保存される
異なるエンドポイント間では共有されない