銷售管理 API（Orders / OMS API）的使用方式

本指南的目的

本文彙整使用 ReceiptRoller 的銷售管理 API（Orders / OMS API），建立、取得、更新、狀態轉移（確認／處理中／取消／店鋪 POS 接收）、刪除商業帳戶底下訂單的方法。這是在整合 Web 接單、電話訂單、市集平台串接等店鋪銷售通路時的入口指南。

前提

• 已透過 OAuth 2.0 授權碼流程取得存取權杖
• 應用程式的權限範圍中包含 store.orders.read（讀取）／store.orders.write（建立、更新、刪除、狀態轉移）
• 已得知商業帳戶 ID（UUID）（取得商業帳戶、店鋪、POS 端末的一覽）
• 基底 URL: https://receiptroller.io

端點一覽

訂單狀態的種類

1. 取得訂單一覽

GET /api/v1/orders?organizationId={organizationId}&status=Pending
Authorization: Bearer {access_token}

查詢參數（選填）

• status — 以訂單狀態篩選
• channel — Web / POS / Phone / Manual / Marketplace
• paymentStatus — Unpaid / Paid / Refunded / PartialRefund

回應為 orders 陣列中的訂單物件。各物件的主要欄位請參閱下方的「訂單物件的結構」。

2. 取得 1 筆訂單的詳細

GET /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}

3. 新增建立訂單

POST /api/v1/orders?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "orderNumber": "RR-2026-0002",
  "channel": "Phone",
  "customerName": "佐藤花子",
  "customerEmail": "hanako@example.com",
  "customerPhone": "080-9876-5432",
  "shippingAddress": {
    "postalCode": "100-0001",
    "prefecture": "東京都",
    "city": "千代田区",
    "line": "千代田1-1"
  },
  "items": [
    { "productId": "prd-002", "productName": "アイスティー", "sku": "TEA-ICE-001",
      "quantity": 3, "unitPrice": 380, "subtotal": 1140 }
  ],
  "paymentMethod": "BankTransfer",
  "paymentStatus": "Unpaid",
  "subtotalAmount": 1140,
  "taxAmount": 114,
  "shippingAmount": 500,
  "totalAmount": 1754,
  "linkedStoreId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "notes": "電話受注。日中の配達希望。"
}

重點

• 僅 customerName 為必填
• 即使在請求本文包含 organizationId 也會被忽略。一定會使用以權杖／查詢解析出的商業帳戶
• 初始狀態恆為 Pending。要推進狀態請使用專用的轉移端點

4. 更新訂單

PUT /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "customerName": "佐藤花子",
  "customerPhone": "080-9876-5432",
  "shippingAddress": { "postalCode": "100-0001", "prefecture": "東京都",
                       "city": "千代田区", "line": "千代田1-1-1（番地修正）" },
  "items": [ ... ],
  "subtotalAmount": 1140, "taxAmount": 114, "shippingAmount": 500, "totalAmount": 1754
}

重點

• 請勿用於狀態變更。狀態的規則是要透過 /confirm / /process / /cancel / /fulfill-via-pos 更新（以便稽核日誌正確保留操作種類）
• 以 POS 接收關聯的 linkedPosTransaction 資訊也無法以 PUT 更新 — 僅限透過專用端點
• 付款狀態（paymentStatus）可更新
• orderNumber 與 createdAt 無法更新（伺服器端保護）

5. 推進狀態（確認 → 處理中 → 出貨等）

確認（Pending → Confirmed）

POST /api/v1/orders/{orderId}/confirm?organizationId={organizationId}

設為處理中（Confirmed → Processing）

POST /api/v1/orders/{orderId}/process?organizationId={organizationId}

取消

POST /api/v1/orders/{orderId}/cancel?organizationId={organizationId}

狀態轉移端點會回傳更新後的完整訂單物件作為回應。

※ 至出貨（Shipped）／配送完成（Delivered）／退款（Refunded）的轉移，目前會透過 WMS／結帳系統串接自動發生。若想從應用程式直接轉移，請在 社群 告知使用情境。

6. 於店鋪 POS 接收（線上訂單的店頭交付）

這是將「顧客於線上下單 → 於店鋪櫃台接收 → 於收銀結帳」的流程以一次操作完結的端點。會將 POS 交易與 OMS 訂單相互連結，並將訂單一口氣轉移至 Delivered ＋ Paid。

POST /api/v1/orders/{orderId}/fulfill-via-pos?organizationId={organizationId}
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "posTerminalId": "term-001",
  "posTransactionId": "tx-9001"
}

動作

• 在 OMS 訂單的 linkedPosTransaction 記錄 { terminalId, transactionId }
• 在 POS 交易的 links.omsOrderId 記錄訂單 ID（反方向連結）
• 將訂單狀態轉移至 Delivered
• 若付款狀態為 Unpaid 則變更為 Paid，並記錄 paidAt（因已於收銀結帳完成）
• 在時間軸追加「FulfilledViaPos」項目
• 觸發訂單更新 Webhook（order.updated）— 承載中會包含 linked_pos_terminal_id 與 linked_pos_transaction_id

冪等性

• 以相同 posTransactionId 對同一訂單再次呼叫也無副作用。對重試／二次點擊是安全的

錯誤情況

• 找不到訂單 / POS 交易 → 404
• POS 交易已關聯至其他 OMS 訂單 → 404（防止衝突）
• POS 交易不屬於此商業帳戶 → 404（防止跨租戶）

回應範例（訂單物件的一部分）

{
  "id": "ord-001",
  "status": "Delivered",
  "payment": { "method": "CreditCard", "status": "Paid", "paidAt": "2026-06-01T13:42:00Z" },
  "linkedStore": { "id": "f47ac10b-...", "name": "渋谷店" },
  "linkedPosTransaction": {
    "terminalId": "term-001",
    "transactionId": "tx-9001"
  },
  ...
}

使用情境

• 顧客於 Web Pending 下單 → 在店鋪的收銀應用程式 POST /confirm → 交付商品 → 於收銀結帳 → POS 交易記錄後立即從收銀應用程式 POST /fulfill-via-pos
• 在交易一覽（Transactions API）中，POS 列與 OMS 列雙方都會相互持有連結，UI 端即可控制重複顯示

7. 刪除訂單

DELETE /api/v1/orders/{orderId}?organizationId={organizationId}
Authorization: Bearer {access_token}

回應為 204 No Content。已刪除訂單會從一覽、搜尋結果中消失。

訂單物件的結構

{
  "id": "ord-001",
  "orderNumber": "RR-2026-0001",
  "channel": "Web",
  "status": "Pending",
  "customer": { "name": "...", "email": "...", "phone": "..." },
  "shippingAddress": { "postalCode": "...", "prefecture": "...", "city": "...", "line": "..." },
  "items": [ { "productId": "...", "productName": "...", "sku": "...",
               "quantity": 2, "unitPrice": 480, "subtotal": 960 } ],
  "itemCount": 2,
  "payment": { "method": "CreditCard", "status": "Paid", "paidAt": "..." },
  "amounts": { "subtotal": 960, "tax": 96, "shipping": 500, "discount": 0, "total": 1556 },
  "linkedStore": { "id": "...", "name": "..." },
  "linkedPosTransaction": null,        // 若已於店鋪POS接收則為 { terminalId, transactionId }
  "notes": "...",
  "preOrder": { "isPreOrder": false, "targetShipDate": null },
  "createdAt": "...",
  "updatedAt": "..."
}

明細（Items）的結構

{
  "productId": "prd-001",
  "productName": "ブレンドコーヒー M",
  "sku": "CFE-BLD-M",
  "quantity": 2,
  "unitPrice": 480,
  "subtotal": 960,
  "unit": "個"
}

productId 為 ReceiptRoller 商品主檔的 ID（可透過 商品管理 API 取得）。經由 POS 或 EC 外部系統的訂單，也可以不帶 productId，僅送 productName + sku。

典型的流程（行動應用程式）

1. 以 OAuth 取得存取權杖 → 權限範圍包含 store.orders.read 與 store.orders.write
2. 以 GET /api/v1/me/organizations 選擇商業帳戶
3. 在接單儀表板畫面取得 GET /api/v1/orders?status=Pending
4. 在新增接單畫面 POST /api/v1/orders（在此之前先以 GET /api/v1/products 選擇商品）
5. 在訂單詳細畫面點「確認」按鈕 → /confirm
6. 包裝負責人「設為處理中」 → /process
7. 在店鋪的收銀應用程式「店鋪接收完成」 → 指定 POS 交易 ID 呼叫 /fulfill-via-pos
8. 因顧客因素取消 → /cancel

錯誤回應

相關資訊

• 取得商業帳戶、店鋪、POS 端末的一覽
• 商品管理 API（Products API）的使用方式
• 營業額實績 API（Sales API）的使用方式
• 交易一覽 API（Transactions API：POS＋OMS 整合摘要）的使用方式
• OAuth 權限範圍一覽與可用與否