跳轉到主要內容
POST
Create resend order
此頁面由 AI 自動翻譯。API 技術規格以英文呈現為標準。如有任何疑問,請參閱英文版本。
建立補寄訂單——將一個或多個已收到的退件庫存項打包,再寄到客戶地址。會觸發非同步面單產生;面單 URL 透過 webhook 推送。

前置條件

  • 目標庫存項已在您的帳戶中。returnInventoryId 由 newInventoryCreated webhook 事件推送——請在自有端快取。
  • 同一次補寄的所有庫存必須位於同一倉庫。
  • 每筆庫存目前的 handlingStatusCode 必須可推進至 rsd(補寄)——通常需為 ohd(暫存)。
  • 任何項所屬行項目不可存在待處理 VAS。
  • 每筆庫存必須實際在庫(非運輸中,亦未處於其他活躍流程)。
  • 備妥目的地地址。

必填欄位

  • resendShipment — 完整 Shipment payload(目的地址、聯絡人、尺寸、重量、服務類型)。國家代碼為 ISO3。
    • warehouseId 為必填,且必須與 returnInventoryIdList 中各項目所屬的倉庫相同(同一次補寄的所有項目共用同一倉庫)。省略將導致驗證失敗。
    • payload 內的 shipmentServiceType 是 Shipment Service Type(不是 Return Service Type)— 有效代碼請見 取得 Warehouse 可用的 Shipment Service Types。傳入 Return Service Type 代碼會在驗證階段失敗。
  • returnInventoryIdList — 非空 List<long>。上限為 ResendConfig.groupResendMaxRmaCount(通常為個位數;如需打包更多請聯絡客服)。

選填欄位

  • description — 補寄訂單的自由文字描述(上限 255 字元)。會保存至訂單,並由取得補寄訂單詳情回傳。
  • remarks — 補寄訂單的商家備註(上限 5000 字元)。會保存至訂單,並由取得補寄訂單詳情回傳。
兩者對應 Portal 上 Create Resend 表單的 Description 與 Remarks 欄位。皆為選填——省略即代表該訂單不設描述或備註。
  • resendNumber — 您為此補寄自訂的參考編號:1–50 個字元,僅限英文字母、數字、- 及 _。在您的帳戶內必須唯一:若該值已用於您帳戶內的其他補寄(包括已取消的補寄),驗證將失敗。省略時由 Return Helper 自動產生。此值會在回應及重寄狀態更新 webhook 中回傳。
resendNumber 將改為唯讀。 Return Helper 將為每筆補寄產生 resendNumber,您自己的參考編號將改為設定於新的選填欄位 sellerReferenceNumber。與 resendNumber 不同,sellerReferenceNumber 並非唯一值——Return Helper 不會拒絕重複的值。為避免重試時重複建立補寄,請傳送 x-returnhelper-idempotency-key 標頭。若您目前有設定 resendNumber,請參閱遷移計畫。

副作用

  • 每筆庫存的 handlingCode 會被設為 rsd。
  • 待面單就緒後,倉庫將出貨。

標籤產生:自動 vs 手動服務類型

補寄是否自動產生運單標籤,取決於您在 resendShipment.shipmentServiceType 中傳入的 shipment service type。每個 shipment service type 都帶有 isEnableAutoCreateLabel 旗標——請從 取得 Warehouse 可用的 Shipment Service Types 取得,並讀取您打算使用的代碼的 isEnableAutoCreateLabel。

自動標籤(isEnableAutoCreateLabel: true)

標籤在建立後非同步產生。補寄狀態流轉為: queued → label-success → completed(若標籤產生失敗則 queued → failed) 僅當補寄處於 label-success 且在截止時間之前,才能透過 取消補寄訂單 取消。處於 queued 時無法取消,因為標籤仍在產生中。

手動標籤(isEnableAutoCreateLabel: false)

不會自動產生標籤;由倉庫處理該補寄。補寄狀態流轉為: pending → in-progress → completed 當補寄處於 pending 且在截止時間之前,可透過 取消補寄訂單 取消。

取消截止時間

每個補寄都有取消截止時間,即工作日的 08:00 UTC,於補寄建立時設定。只要補寄處於其可取消狀態(自動標籤為 label-success,手動標籤為 pending),您可在該截止時間之前取消。一旦超過截止時間,便無法再透過 API 取消。
若已超過截止時間但您仍需取消補寄,請聯絡我們的客服團隊協助。截止時間過後無法保證能取消——包裹可能已經寄出。

等冪性

x-returnhelper-idempotency-key 標頭為選填。未帶此標頭的呼叫會正常執行,但不具備防重複的保護。請參閱等冪性。

相關

授權

x-rr-apikey
string
header
必填

Your API key

x-rr-apitoken
string
header
必填

Your API token — keep this private

主體

application/json
returnInventoryIdList
integer<int64>[]
必填

List of return inventory IDs for resend

resendShipment
object
必填

Destination shipment address for the resend

description
string

Optional free-text description for the resend order. Stored against the order and returned by Get resend order details.

Maximum string length: 255
remarks
string

Optional merchant remarks/notes for the resend order. Stored against the order and returned by Get resend order details.

Maximum string length: 5000
resendNumber
string

Optional. Your own reference for this resend: 1-50 characters, letters, digits, - and _ only. A value already used on another resend in your account, including a cancelled one, fails validation. When omitted, Return Helper generates one. Planned change: this field will become read-only and generated by Return Helper; use sellerReferenceNumber instead once it is available. See the announcement.

Maximum string length: 50
Pattern: ^[A-Za-z0-9_-]{1,50}$
範例:

"INV-10042"

回應

Success

resendId
integer<int64>

Created resend identifier

resendNumber
string

Resend number: the resendNumber you supplied, or the one Return Helper generated when you omitted it.

範例:

"RSD221003-0000001"