---
title: "订单"
description: "学习如何通过 Orders API 检索订单信息和管理配送记录。"
source: "https://docs.tokenz.one/zh-CN/v2/order"
api_version: "v2"
locale: "zh-CN"
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-CN/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 令牌
- `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 之后