建立 Return Shipment

Create return shipment

curl --request POST \
  --url https://api.returnshelper.com/uat/user/api/ReturnShipment/createReturnShipment \
  --header 'Content-Type: application/json' \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>' \
  --data '
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Return Label Title",
  "orderNumber": "123123",
  "totalValueCurrency": "usd",
  "shipment": {
    "shipToWarehouseId": 2,
    "boxType": "cus",
    "shipFrom": {
      "country": "usa",
      "contactName": "Your name",
      "street1": "Some address line 1",
      "state": "tx",
      "city": "Houston",
      "postalCode": "77235",
      "phone": "15622708183",
      "email": "user@example.com",
      "fax": "<string>",
      "street2": "Some address line 2",
      "street3": "<string>"
    },
    "parcel": {
      "weight": 10.5,
      "weightUnit": "g",
      "length": 10,
      "width": 10,
      "height": 10,
      "dimensionUnit": "cm",
      "items": [
        {
          "description": "Test item",
          "weight": 10.5,
          "value": 100,
          "weightUom": "g",
          "valueCurrencyCode": "usd"
        }
      ]
    },
    "sellerReferenceNumber": "<string>",
    "customFieldMap": {}
  },
  "totalValue": 100,
  "sellerReferenceNumber": "<string>",
  "remarks": "<string>"
}
'

{
  "data": {
    "returnRequestId": 123,
    "returnRequestNumber": "<string>",
    "shipmentId": 123,
    "referenceNumber": "<string>",
    "labelId": 123,
    "labelRequestStatusCode": "<string>",
    "cost": 123,
    "costCurrencyCode": "<string>"
  }
}

POST

api

ReturnShipment

createReturnShipment

Create return shipment

curl --request POST \
  --url https://api.returnshelper.com/uat/user/api/ReturnShipment/createReturnShipment \
  --header 'Content-Type: application/json' \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>' \
  --data '
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Return Label Title",
  "orderNumber": "123123",
  "totalValueCurrency": "usd",
  "shipment": {
    "shipToWarehouseId": 2,
    "boxType": "cus",
    "shipFrom": {
      "country": "usa",
      "contactName": "Your name",
      "street1": "Some address line 1",
      "state": "tx",
      "city": "Houston",
      "postalCode": "77235",
      "phone": "15622708183",
      "email": "user@example.com",
      "fax": "<string>",
      "street2": "Some address line 2",
      "street3": "<string>"
    },
    "parcel": {
      "weight": 10.5,
      "weightUnit": "g",
      "length": 10,
      "width": 10,
      "height": 10,
      "dimensionUnit": "cm",
      "items": [
        {
          "description": "Test item",
          "weight": 10.5,
          "value": 100,
          "weightUom": "g",
          "valueCurrencyCode": "usd"
        }
      ]
    },
    "sellerReferenceNumber": "<string>",
    "customFieldMap": {}
  },
  "totalValue": 100,
  "sellerReferenceNumber": "<string>",
  "remarks": "<string>"
}
'

{
  "data": {
    "returnRequestId": 123,
    "returnRequestNumber": "<string>",
    "shipmentId": 123,
    "referenceNumber": "<string>",
    "labelId": 123,
    "labelRequestStatusCode": "<string>",
    "cost": 123,
    "costCurrencyCode": "<string>"
  }
}

此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問，請參閱英文版本。

建立一份附帶面單請求的退件運貨單——幾乎是所有 Return Helper 整合的入口。運貨單將一個或多個包裹與其商品、聯絡資料、尺寸打包在一起。面單產生會非同步排程；即時回應中給出運貨單 ID 與 labelRequestStatusCode（通常為 queued），實際面單 URL 稍後透過 webhook 推送。

前置條件

呼叫前請備妥：

serviceTypeCode — 從下列任一端點取得可用的退件服務：
- 取得所有退件服務類型
- 依始發國家與倉庫取得服務類型
始發與目的地國家代碼 — 透過取得所有始發國家與取得所有國家取得。代碼使用 ISO3（usa、gbr、chn）。
包裹尺寸與重量 — 必填且必須 > 0。可透過取得所有尺寸單位與取得所有重量單位驗證單位。
等冪鍵 — 強烈建議。請在 x-returnhelper-idempotency-key 中傳入新的 UUID，以避免重試時產生重複的運貨單。詳見等冪性章節。

重要欄位

totalValue 與 totalValueCurrency — totalValue 必須嚴格等於 parcel.items[].value 之和。幣別使用 ISO 4217（例如 USD、GBP、EUR）；可透過取得所有交易類型確認幣別代碼是否支援。
parcel.items — 是否支援多明細取決於您的帳戶設定。僅支援單明細的帳戶若提交多明細，會收到驗證軟錯誤。如需調整設定，請聯絡客服。
尺寸 — dimension1 為最長邊，dimension2 為次長，dimension3 為最短。
sellerReferenceNumber — 您賣家自訂的識別碼，可在三個互相獨立的層級（頂層、shipment、以及 parcel.items[] 內每條 item）上傳入。原樣保存並在 Webhook 事件中回傳，便於與您自己的訂單系統對帳。層級語意、省略時的回退行為，以及建議的對帳工作流見 Seller Reference Number。

面單產生為非同步

即時回應包含 labelRequestStatusCode: queued。最終面單 URL 與追蹤號透過 labelGenerated webhook 事件推送（產生失敗則為 labelFailed）；倉庫收件由 markShipmentArrive 事件通知，隨後會有 inventoryCreated 事件。請訂閱 Webhooks——webhook 是運貨單生命週期的真實資料來源，並非輪詢的退路。

前置條件

重要欄位

面單產生為非同步

相關

授權

主體

回應

​前置條件

​重要欄位

​面單產生為非同步

​相關

授權

主體

回應

前置條件

重要欄位

面單產生為非同步

相關