​

变更记录

Flex Forward API 与文档的重要变更按时间倒序列出。

---

​

2026 年 10 月

​

API 变更

• EU 商品标识符： shipment.parcels[].items[].attributes.productIdentifiers 用于说明报关申报所需的商品标识符。寄往 EU、摩纳哥、法国海外地区或北爱尔兰（邮政编码以 BT 开头）的每件商品都必须提供 mpid、nspid 和 spid，且每个字段均为代码列表。寄往其他地区时，这些字段均为可选。说明还列出了代码限制，包括 spid 不能为空，且只有商品没有条形码时才能使用 Y081。

---

​

2026 年 9 月

​

API 变更

• 端点： GET /orders/{orderId} — 获取一条订单及其创建标签时提供的物流商详细信息。响应包含订单的运输阶段（status）、商业 exceptionState、物流商标识符、申报的包裹重量与尺寸，以及向物流商提交时的 error；另包含您发送的订单号、报关标识符、服务选项与物流商选项。请将 POST /labels 返回的标签 id 作为 {orderId}；此端点仅接受 UUID，不接受 customerOrderNumber。它与仅返回标签文件的 GET /labels/{id} 互为补充。
• 幂等性： 使用不同请求体重复 idempotencyKey 会返回 409 IDEMPOTENCY_CONFLICT。相同密钥和请求体的请求会重放已保存结果。没有保存请求指纹的旧记录仍保持原有的重放行为。
• 标签格式： label.format 支持 PDF 和 PNG，省略时默认使用 PDF。文档响应以小写 pdf 或 png 报告所选格式。
• 客户订单号： 指定值必须为 1–40 个 ASCII 字母、数字、- 或 _，区分大小写，且账户内唯一；省略时由系统自动生成。FlexForward 会将 {clientCode}-{customerOrderNumber} 传给物流商，作为其客户参考并在支持的情况下打印。
• 商品价格： unitPrice.amount 必须至少为 0.01。免费赠品、样品和促销赠品也必须按 0.01 或以上的名义价值申报，不能为 0。unitPrice.currency 仅接受 USD。省略货币值同样视为 USD。
• IOSS 处理： customs.taxIds.ioss 现已明确说明，提供的非空白值会先去除首尾空白后再使用。如果该字段被省略或留空，且目的地为 EU 税务国家，则会自动应用 FlexForward 的默认 IOSS 代码。您在 IOSS registrations 下注册的代码，除非在请求中发送，否则不会自动应用。应用 FlexForward 的默认代码会产生费用，因为系统会连同运费一并记入 VAT 预付款和服务费；如果您在此提供自己的代码，则不会收费。

​

文档修正

• 在核心概念的资源表与集成流程中新增订单资源与 GET /orders/{orderId}。
• 更新国际发货指南，以反映 unitPrice.amount 的最小值为 0.01，并说明不接受价值为 0 的报关申报。
• 澄清 IOSS 的判定与计费方式：提供的 customs.taxIds.ioss 值会被保留；如果该字段被省略或留空，且目的地为 EU 税务国家，则会自动应用 FlexForward 的默认 IOSS 代码；此外，默认代码路径会收费，而提供自己的代码则不会收费。

​

文档维护

• 添加检查，确保生成的 API 文档与来源保持一致，并审查相关指南更新。

---

​

2026 年 7 月

​

变更

• 文档 / OpenAPI： 更正公开身份验证说明。客户集成必须同时发送 x-rr-apikey 与 x-rr-apitoken。已移除 Bearer 令牌示例与公开 OpenAPI 的 bearerAuth 方案作为客户身份验证方式。
• 身份验证： API 认证信息改为从 Return Helper User Portal 的 Settings → Signing Key and API Token 获取，取代以往通过电子邮件申请令牌的流程。

---

​

2026 年 6 月

​

Added

• 端点： GET /couriers — 列出您账户可用的物流商代码。使用返回的 code 值作为创建标签或列出物流商产品时的 courier。

---

​

2026 年 5 月

​

Added

• 端点： GET /products — 列出物流商可用的配送产品。使用返回的产品代码创建标签。
• 认证： 记载 Flex Forward 请求使用 API 密钥 + 令牌头认证（x-rr-apikey / x-rr-apitoken）。
• 端点： GET /labels/{id} — 现在支持以逗号分隔的标识符（标签 UUID 或客户订单编号）进行批量获取。未找到或失败的标签会从响应中省略。
• 响应： GET /labels/{id} 响应现在包含 customerOrderNumber 字段。

​

Changed

• service.shipperAccountId 现在为可选字段。省略时，系统会使用您账户针对该物流商的默认配送账户来创建标签。仍然发送此字段的请求可继续正常运作。
• API 规格： 为所有端点添加详细描述、示例和操作 ID。
• 文档： 改进快速入门指南、请求示例及其他修正。

---

​

v1.0.0

Flex Forward API 与开发者文档的首次公开发布。

​

Added

• 端点： POST /labels（创建配送标签）、GET /labels/{id}（获取标签文档 URL）、GET /tracking/{id}（获取配送追踪）
• 生产物流商： YunExpress（全球跨境电商配送路线）
• 幂等性： 通过 idempotencyKey 内建标签创建重复防止功能
• 统一追踪： 规范化状态标签（Pending、InfoReceived、InTransit、Delivered、Exception、Cancelled、Unknown）以及跨所有物流商的结构化检查点格式
• 认证： API 密钥 + 令牌头认证（x-rr-apikey / x-rr-apitoken），生产与开发环境使用独立认证信息
• 文档： 快速入门指南、认证参考、错误处理指南、幂等性与重试模式、环境详情、核心概念、版本管理政策、常见问题