---
title: "訂單"
description: "學習如何透過 Orders API 檢索訂單資訊和管理配送記錄。"
source: "https://docs.tokenz.one/zh-TW/v2/order"
api_version: "v2"
locale: "zh-TW"
version_status: "current"
docs_stage: "prod"
---

# 訂單

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

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

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

**金額格式：** API 中所有貨幣值（如 `amount` 欄位）均以各貨幣的最小單位表示。請參閱[支援的貨幣](https://docs.tokenz.one/zh-TW/v2/checkout/currency)以了解每種貨幣的確切編碼。

## 概述

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

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

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

## 訂單生命週期

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

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

### 訂單狀態值

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

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

```mermaid
sequenceDiagram;
autonumber;
participant M as 商家應用程式;
participant T as Tokenz API;
participant DB as 訂單資料庫;
%% Order Retrieval Flow;
Note over M,DB: Order Retrieval API;
M->>T: GET /v2/order/{id};
T->>DB: 查詢訂單詳情;
DB-->>T: 返回訂單資料;
T-->>M: 訂單詳情;
%% Delivery Registration Flow (Independent);
Note over M,DB: Delivery Registration API;
M->>T: POST /v2/order/{orderId}/delivery;
T->>DB: 儲存配送記錄;
T-->>M: 配送記錄確認;
```

## API 呼叫範例

### Order Retrieval API

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

```bash
curl --request GET \
  --url https://api.tokenz.one/v2/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/v2/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/v2/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-15T10:00:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "requiresPayment",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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-15T10:45:00Z",
  "test": true,
  "eventData": {
    "type": "order",
    "version": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "succeeded",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "expired",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "canceled",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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": "v2",
    "data": {
      "order": {
        "id": "order_1D5xA9BnKfv_t",
        "object": "order",
        "status": "failed",
        "amount": {
          "amount": 3700,
          "currency": "JPY"
        },
        "consumerAmount": {
          "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 之後