此頁面由英文翻譯而成。英文版為官方權威來源。如翻譯內容有任何不一致之處，請以英文版為準。

身份驗證

所有 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 金鑰。請勿在客戶端程式碼、公開儲存庫或不安全的管道中分享。

存取方式

登入 User Portal

使用與 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 認證資訊

存取方式

發送已驗證的請求

錯誤回應

認證資訊最佳實踐