创建 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 是运货单生命周期的真实数据源，并非轮询补救方案。

前置条件

重要字段

面单生成是异步的

相关

授权

请求体

响应

​前置条件

​重要字段

​面单生成是异步的

​相关

授权

请求体

响应

前置条件

重要字段

面单生成是异步的

相关