訂單

學習如何透過 Orders API 檢索訂單資訊和管理配送記錄。

Order API 為訂單管理提供三個獨立的端點。Order Retrieval API 允許您存取包括狀態、商品和客戶詳情在內的綜合訂單資訊。Order Cancellation API 讓您在不再需要時取消訂單並取得最新狀態，Delivery Registration API 使您能夠為訂單履行追蹤註冊具有彈性負載結構的配送記錄。

訂單在商家建立結帳工作階段時自動建立，包含所有交易詳情，包括商品、金額和客戶資訊。

金額格式： API 中所有貨幣值（如 amount 欄位）均以各貨幣的最小單位表示。請參閱支援的貨幣以了解每種貨幣的確切編碼。

概述

Order 系統提供三個主要的 API 端點：

Order Retrieval API: 存取包括狀態、商品和客戶詳情在內的詳細訂單資訊
Order Cancellation API: 取消不再需要的訂單，並取得包含 canceledAt 時間戳記的最新訂單狀態
Delivery Registration API: 靈活地註冊配送記錄。接受任何 JSON 結構，同時為關鍵欄位提供警告和建議

這些 API 獨立運作 - 您可以隨時檢索訂單資訊，並在訂單發貨或送達時註冊配送記錄。Delivery Registration API 設計彈性，接受任何有效的 JSON 負載，同時透過警告系統引導您包含重要資訊。

訂單生命週期

當支付處理時，訂單會自動經過不同的狀態：

訂單建立: 商家建立結帳工作階段時自動建立訂單
訂單處理: 訂單經過各種狀態：requiresPayment → processing → succeeded
訂單檢索: 使用 Orders API 存取訂單詳情以進行履行和追蹤
配送註冊: 在訂單履行時獨立註冊配送資訊

訂單狀態值

訂單透過以下狀態值進展：

requiresPayment: 此訂單的付款仍在等待中
processing: 已收到付款，訂單正在處理中
succeeded: 訂單已成功完成
failed: 訂單在處理後失敗
blocked: 訂單暫時被封鎖，無法進一步操作
canceled: 訂單已被取消，不會繼續處理
expired: 訂單已過期，不再有效

流程圖

API 呼叫範例

Order Retrieval API

使用訂單 ID 獲取特定訂單的詳細資訊。您可以從結帳工作階段建立回應或 Webhook 中找到訂單 ID。

bash

curl --request GET \
  --url https://api.tokenz.one/v1/order/{YOUR_ORDER_ID} \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

回應:

json

{
  "id": "order_1D5xA9BnKfv_t",
  "object": "order",
  "status": "requiresPayment",
  "amount": {
    "amount": 3700,
    "currency": "JPY"
  },
  "items": [
    {
      "id": "item_1D6F8mR5TnK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 1200,
            "currency": "JPY"
          },
          "quantity": 3,
          "label": "ひとにぎりのエメラルド",
          "description": "80+8",
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
          ]
        }
      }
    },
    {
      "id": "item_1xejV7puGeK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 100,
            "currency": "JPY"
          },
          "quantity": 1,
          "label": "Diamond",
          "description": "",
          "images": [],
          "sku": "sku_103843dfjhdfgiu",
          "taxCategory": "VIRTUAL_CURRENCY"
        }
      }
    }
  ],
  "description": "Game items purchase",
  "reference": "ORDER_2024_001",
  "test": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:30Z"
}

Order Cancellation API

當您不再希望訂單繼續執行時，可取消現有的訂單。此端點不需要請求本文——只需在路徑中提供訂單 ID。

bash

curl --request POST \
  --url https://api.tokenz.one/v1/order/{YOUR_ORDER_ID}/cancel \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json'

回應:

json

{
  "id": "order_1D5xA9BnKfv_t",
  "object": "order",
  "status": "canceled",
  "amount": {
    "amount": 3700,
    "currency": "JPY"
  },
  "items": [
    {
      "id": "item_1D6F8mR5TnK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 1200,
            "currency": "JPY"
          },
          "quantity": 3,
          "label": "ひとにぎりのエメラルド",
          "description": "80+8",
          "images": [
            "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp"
          ]
        }
      }
    },
    {
      "id": "item_1xejV7puGeK_t",
      "detail": {
        "product": {
          "price": {
            "amount": 100,
            "currency": "JPY"
          },
          "quantity": 1,
          "label": "Diamond",
          "description": "",
          "images": [],
          "sku": "sku_103843dfjhdfgiu",
          "taxCategory": "VIRTUAL_CURRENCY"
        }
      }
    }
  ],
  "description": "Game items purchase",
  "reference": "ORDER_2024_001",
  "test": true,
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T10:05:30Z",
  "canceledAt": "2024-01-15T10:05:32Z"
}

若訂單無法取消（例如已成功完成），API 會回傳帶有 order.status-invalid 錯誤碼的 422 Unprocessable Entity。

Delivery Registration API

為訂單註冊配送資訊，支援彈性的資料格式。API 接受任何有效的 JSON 結構，並回傳警告和建議，幫助您優化配送追蹤。

注意：此 API 支援對同一訂單進行多次呼叫，實現分批配送追蹤。例如，如果一個訂單包含多個商品，分多批發貨，您可以為每批貨物呼叫一次此 API。每次呼叫都會建立獨立的配送記錄，讓您能夠準確追蹤訂單履行進度。

bash

curl --request POST \
  --url https://api.tokenz.one/v1/order/{YOUR_ORDER_ID}/delivery \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
            "at": "2025-01-15T10:30:00Z",
            "user": {
              "userId": "user_67890",
              "phoneNumber": "+1234567890",
              "emailAddress": "test-user@example.com"
            },
            "items": [
              {
                "sku": "TEST-SKU-001",
                "name": "Test Product for Delivery",
                "itemId": "item_12345",
                "itemChange": {
                  "inAppBalanceAfter": 102,
                  "inAppBalanceBefore": 100
                },
                "deliveredQuantity": 2
              }
            ],
            "status": "succeeded",
            "metadata": {
              "customField": "test_value",
              "merchantNotes": "Successfully delivered via API",
              "deliveryChannel": "api"
            },
            "progress": "completed",
            "cartContext": {
              "deviceId": "device_abc123",
              "timestamp": "2025-01-15T10:00:00Z",
              "ipAddress": "192.168.1.100",
              "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
              "geoLocation": {
                "lat": 37.7749,
                "lon": -122.4194,
                "region": "US"
              }
            },
            "deliveryInfo": {
              "deliveryMethod": "digital_download",
              "confirmationType": "email",
              "confirmationProof": "delivery_confirmation_12345"
            },
            "deliveryContext": {
              "deviceId": "device_abc123",
              "timestamp": "2025-01-15T10:30:00Z",
              "ipAddress": "192.168.1.100",
              "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
            }
          }'

回應:

json

{
  "success": true,
  "message": "Delivery record has been registered successfully"
}

API 彈性和指導

Delivery Registration API 以彈性為設計理念 - 您可以提交任何有效的 JSON 結構，API 都會接受它。然而，為了幫助您從配送追蹤中獲得最大價值，API 在回應中提供警告和建議。

警告和建議系統

當您註冊配送記錄時，API 會分析您的負載並返回指導：

警告: 當缺失或無效的關鍵欄位時發出警報，這些欄位強烈建議用於有效的配送追蹤
建議: 推薦可以增強分析、詐騙偵測和配送優化的可選欄位

這個系統允許您從簡單開始，並根據提供的回饋逐步改進您的整合。

欄位定義和重要性級別

狀態和進度枚舉值

status：單次配送的狀態

succeeded - 這次特定的配送成功完成
failed - 這次特定的配送失敗

progress：訂單整體配送進度

completed - 訂單中的所有商品已全部配送完成
in_progress - 部分配送 - 一部分商品已配送，其他待配送
pending - 訂單中還沒有任何商品被配送

重要區別：對於包含多個商品且分批發貨的訂單：

status 追蹤每次單獨的配送/發貨
progress 追蹤整個訂單的完成情況
範例：一個包含3件商品、分兩批發貨的訂單，會有兩條配送記錄（每條有自己的status），而progress反映的是這3件商品是否全部配送完成

欄位重要性分類

欄位按重要性分類，以幫助您確定整合的優先順序：

關鍵欄位（缺失/無效時生成警告）：

status: 配送狀態（參見上述枚舉值）
progress: 配送進度（參見上述枚舉值）
at: 配送發生時的 ISO 8601 時間戳記
cartContext.timestamp: 提供 cartContext 時，其中的時間戳記
deliveryContext.timestamp: 提供 deliveryContext 時，其中的時間戳記

推薦欄位（缺失時生成建議）：

items: 帶有詳細資訊的已配送商品陣列
items[].deliveredQuantity: 每個商品配送的數量
items[].itemChange.inAppBalanceBefore/After: 對餘額追蹤至關重要
user: 用於個人化洞察的使用者資訊
user.userId: 用於配送追蹤的使用者識別碼
user.emailAddress: 用於識別的使用者電子郵件
deliveryContext: 用於詐騙偵測的上下文資訊
deliveryInfo: 配送方法和確認詳情

可選欄位（無警告，但有價值）：

metadata: 用於您特定用例的自訂欄位，類型: Map<String, String>
cartContext: 原始購買上下文
地理位置資料

配送記錄資料結構

雖然配送記錄端點接受任何有效的 JSON 結構，我們強烈建議提供全面的配送資訊，以便在發生爭議時保護您的業務。配送記錄越詳細，在出現問題時您的證據就越充分。

如上述 curl 命令範例所示，我們建議發送包含所有可用欄位的完整負載。

為什麼全面的記錄對爭議處理很重要

提供完整的配送資訊對爭議保護至關重要：

證據存檔：當客戶提出爭議時，詳細的記錄可作為配送證明
時間線驗證：時間戳和上下文資料有助於確定配送的時間和方式
商品追蹤：詳細的商品記錄證明了配送的具體內容和數量

雖然 API 會接受最小資料，但不完整的記錄可能使您在爭議中缺乏足夠的證據。請始終包含所有可用資訊，以維護全面的稽核記錄。

回應狀態碼

Orders API 回傳標準的 HTTP 狀態代碼和詳細的錯誤訊息：

200 OK: 訂單檢索或取消成功
201 Created: 配送記錄註冊成功
400 Bad Request: 無效的請求格式或缺少必填欄位
401 Unauthorized: 無效或缺失的 API TOKEN
403 Forbidden: 對請求的資源存取被拒絕
404 Not Found: 未找到訂單或存取被拒絕
422 Unprocessable Entity: 在目前訂單狀態下不允許的操作（例如嘗試取消已完成的訂單會回傳 order.status-invalid）
500 Server Error: 內部伺服器錯誤

所有錯誤回應都包含一個結構化的錯誤物件，包含代碼和訊息以便程式化處理。

錯誤回應範例

json

{
  "status": 404,
  "code": "entity.not-found",
  "message": "The requested order could not be found."
}

訂單 Webhook

設定 Webhook 來接收訂單事件通知：

`order.created`

當訂單建立時觸發：

json

{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890abc",
  "object": "order.created",
  "createdAt": "2024-01-15T00:00:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v1",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "requiresPayment",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-01-16T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "regionCode": "JP"
      }
    }
  }
}

`order.succeeded`

當訂單在付款後成功完成時觸發：

json

{
  "id": "e5f6a7b8-c9d0-1234-efab-345678901def",
  "object": "order.succeeded",
  "createdAt": "2024-01-15T00:45:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v1",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "succeeded",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-01-16T10:00:00Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:45:00Z",
        "regionCode": "JP"
      }
    }
  }
}

`order.expired`

當訂單到達到期時間而未完成時觸發：

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "object": "order.expired",
  "createdAt": "2024-12-31T23:59:59Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v1",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "expired",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "expiresAt": "2024-12-31T23:59:59Z",
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-12-31T23:59:59Z",
        "regionCode": "JP"
      }
    }
  }
}

`order.canceled`

當訂單被取消時觸發：

json

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "object": "order.canceled",
  "createdAt": "2024-01-15T10:05:32Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v1",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "canceled",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T10:05:32Z",
        "canceledAt": "2024-01-15T10:05:32Z",
        "regionCode": "JP"
      }
    }
  }
}

`order.failed`

當訂單失敗時觸發：

json

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "object": "order.failed",
  "createdAt": "2024-01-15T11:00:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v1",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "failed",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "items": [
          {
            "id": "item_1D6F8mR5TnK_t",
            "detail": {
              "product": {
                "price": {
                  "amount": 3700,
                  "currency": "JPY"
                },
                "quantity": 1,
                "label": "Game Item Bundle",
                "description": "In-game items",
                "images": []
              }
            }
          }
        ],
        "description": "Game items purchase",
        "reference": "ORDER_2024_001",
        "test": true,
        "createdAt": "2024-01-15T10:00:00Z",
        "updatedAt": "2024-01-15T11:00:00Z",
        "regionCode": "JP"
      }
    }
  }
}

最佳實踐

訂單和配送記錄管理

在系統中儲存訂單 ID 以供未來參考
使用 Webhook 接收即時訂單狀態更新
在發貨或配送後立即維護獨立的配送記錄並註冊。雖然我們的 API 為爭議解決提供備份儲存，但您的系統應該是配送資料的主要來源
對於分批發貨，多次呼叫 Delivery Registration API - 每批貨物發貨時呼叫一次。每次呼叫都會建立獨立的配送記錄，實現多批次訂單的準確追蹤

Delivery Registration API 整合策略

使用全面的負載結構來最小化警告並最大化追蹤能力
包含所有推薦欄位（at、user、items、deliveryContext、deliveryInfo）以獲得最佳效能
對所有時間戳記使用 ISO 8601 格式（at、cartContext.timestamp、deliveryContext.timestamp）並確保它們在 2024-03-01T00:00:00.000Z 之後