此页面由英文翻译而成。英文版为官方权威来源。如翻译内容有任何不一致之处，请以英文版为准。

身份验证

所有 Flex Forward API 端点都需要通过 两个头部 进行身份验证：x-rr-apikey 与 x-rr-apitoken。

获取 API 认证信息

API 认证信息在 Return Helper User Portal 中管理。您需要有 Return Helper 用户账户——与 Flex Forward Portal 使用相同的登录信息。请按照 Return Helper API 身份验证指南的步骤，在 Settings → Signing Key and API Token 查看或生成您的认证信息。您需要该处显示的两个值：

认证信息	头部
API 密钥	`x-rr-apikey: YOUR_API_KEY`
API 令牌	`x-rr-apitoken: YOUR_API_TOKEN`

同一组 API 密钥与 API 令牌可用于验证 Flex Forward API 与 Return Helper User API 两者：

API	身份验证方式
Flex Forward API	`x-rr-apikey` 以及 `x-rr-apitoken`
Return Helper User API	`x-rr-apikey` 以及 `x-rr-apitoken`

每个需要验证的 Flex Forward 请求都必须同时包含两个头部。缺少任一头部，或仅使用 Authorization: Bearer 令牌，都不是文档所记载的客户身份验证方式。

请妥善保管您的 API 令牌与 API 密钥。请勿在客户端代码、公开仓库或不安全的渠道中分享。

访问方式

使用与 Flex Forward Portal 相同的账户登录 Return Helper User Portal。

获取认证信息

前往 Settings → Signing Key and API Token，或按照 Return Helper API 文档的 Authentication 说明操作。请同时复制 API 密钥与 API 令牌。

验证 Flex Forward 请求

在每个请求中同时包含 x-rr-apikey 与 x-rr-apitoken（见下方）。同一组认证信息亦可验证 Return Helper User API 请求。

需要帮助？

如需账户访问、Portal 登录问题或其他查询，请联系 [email protected]。

发送已验证的请求

在每个请求中同时包含两个头部：

curl -X POST https://api.flexforward.com/labels \
  -H "x-rr-apikey: YOUR_API_KEY" \
  -H "x-rr-apitoken: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "idempotencyKey": "unique-key-per-request",
      "courier": "yunexpress",
      "service": {
        "productCode": "HKMUZXR"
      },
      "label": {
        "format": "PDF"
      },
      "units": {
        "weight": "KG",
        "dimension": "CM"
      },
      "order": {
        "customerOrderNumber": "N-2026-05-27-TEST-03",
        "orderNumbers": {
          "platformOrderNumber": "platform-order-number",
          "referenceNumbers": [
            "ref-number-1",
            "ref-number-2"
          ]
        }
      },
      "shipment": {
        "shipTo": {
          "contact": {
            "firstName": "Alex",
            "lastName": "Smith",
            "phone": "8554377467",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "18 Distribution Blvd"
            ],
            "city": "Edison",
            "state": "New jersey",
            "postalCode": "08817",
            "countryCode": "US"
          }
        },
        "shipFrom": {
          "contact": {
            "firstName": "John",
            "lastName": "Doe",
            "phone": "886900676877",
            "email": "[email protected]"
          },
          "address": {
            "streetLines": [
              "Habucho"
            ],
            "city": "Kishiwada-Shi",
            "state": "Osaka",
            "postalCode": "596-0825",
            "countryCode": "JP"
          }
        },
        "parcels": [
          {
            "weight": 0.5,
            "dimension": {
              "length": 30,
              "width": 20,
              "height": 10
            },
            "items": [
              {
                "descriptionEn": "Muji Ink pen",
                "descriptionLocal": "文具",
                "quantity": 1,
                "unitPrice": {
                  "amount": 29.99,
                  "currency": "USD"
                },
                "unitWeight": 0.5
              }
            ]
          }
        ]
      },
      "serviceOptions": [
        {
          "code": "V1",
          "value": "云途预缴"
        }
      ],
      "courierOptions": {
        "yunexpress": {
          "sourceCode": "YT",
          "sensitiveType": "D"
        }
      }
  }'

错误响应

若任一认证信息缺失或无效，API 会返回 401 Unauthorized 响应：

{
  "error": "Unauthorized"
}

若认证信息有效，但调用方无权访问所请求的资源，API 会返回 403 Forbidden 响应：

{
  "error": "Forbidden"
}

认证信息最佳实践

定期轮换 API 密钥与令牌
为开发与生产环境使用不同的认证信息
将认证信息存放在环境变量或密钥管理工具中——切勿硬编码

快速开始

指南

使用场景指南

平台

身份验证

身份验证

获取 API 认证信息

访问方式

发送已验证的请求

错误响应

认证信息最佳实践

​身份验证

​获取 API 认证信息

​访问方式

​发送已验证的请求

​错误响应

​认证信息最佳实践

身份验证

获取 API 认证信息

访问方式

发送已验证的请求

错误响应

认证信息最佳实践