订单

学习如何通过 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 令牌
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 之后