代表性的 API 範例

API 範例 curl 收據取得

本文的對象
這是給初次接觸 API 的開發者的動作確認用範例集。以不依賴實作語言的 curl 介紹。

所有範例中假設 $TOKEN 中已放入存取權杖。完整的規格請參閱 API 參考（Swagger）。

1. 取得自己的店鋪一覽

curl https://api.receiptroller.io/v1/stores \
  -H "Authorization: Bearer $TOKEN"

回應

{
  "object": "list",
  "data": [
    {
      "id": "str_abc123",
      "name": "渋谷店",
      "currency": "JPY",
      "created_at": "2025-12-01T00:00:00Z"
    }
  ],
  "has_more": false
}

2. 取得過去 24 小時的收據

curl "https://api.receiptroller.io/v1/receipts?store_id=str_abc123&issued_after=2026-04-26T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $TOKEN"

3. 取得個別收據的明細

curl https://api.receiptroller.io/v1/receipts/rcp_xyz789 \
  -H "Authorization: Bearer $TOKEN"

回應（一部分）

{
  "id": "rcp_xyz789",
  "store_id": "str_abc123",
  "issued_at": "2026-04-27T10:15:22Z",
  "total_amount": 3850,
  "tax_amount": 350,
  "currency": "JPY",
  "items": [
    {
      "product_id": "prd_a01",
      "name": "コーヒー豆 200g",
      "quantity": 1,
      "unit_price": 1500,
      "amount": 1500
    },
    {
      "product_id": "prd_a02",
      "name": "ドリッパー",
      "quantity": 1,
      "unit_price": 2000,
      "amount": 2000
    }
  ],
  "payment_method": "credit_card"
}

4. 新增建立商品

curl -X POST https://api.receiptroller.io/v1/products \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 01HV6N3M2K9PQR" \
  -d '{
    "store_id": "str_abc123",
    "sku": "COFFEE-200G-001",
    "name": "コーヒー豆 エチオピア 200g",
    "price": 1800,
    "currency": "JPY",
    "tax_rate": 0.10
  }'

5. 更新庫存量

curl -X PATCH https://api.receiptroller.io/v1/inventory/prd_a01 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 42,
    "warehouse_id": "wh_main"
  }'

6. 登錄 Webhook 端點

curl -X POST https://api.receiptroller.io/v1/webhook_endpoints \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhook",
    "events": ["receipt.issued", "receipt.refunded"],
    "description": "正式 - 庫存同步用"
  }'

7. 取得自己的使用者資訊（User 系權限範圍）

curl https://api.receiptroller.io/v1/me \
  -H "Authorization: Bearer $USER_TOKEN"

※ $USER_TOKEN 是以 user.profile 權限範圍取得的一般消費者的權杖。

8. 使用者本人的收據一覽（User 系權限範圍）

curl "https://api.receiptroller.io/v1/me/receipts?limit=20" \
  -H "Authorization: Bearer $USER_TOKEN"

各語言 SDK、用戶端產生

不提供各語言的官方 SDK。取而代之，以 OpenAPI（Swagger）格式公開全部端點的定義。

https://receiptroller.io/openapi/v1.json

將此 URL 交給 AI 編碼助理，或匯入 openapi-generator、NSwag、Kiota 等程式碼產生工具，即可自動產生帶型別的 API 用戶端。手寫實作的情況，也可以支援 OAuth 2.0 與 JSON HTTP 的泛用函式庫（axios、Requests、HttpClient 等）直接實作。

社群中所開發的範例程式碼會分享在開發者社群。