> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Seller Reference Number

> 如何使用 `sellerReferenceNumber` 將 Return Helper 紀錄與您自己的訂單、PO 或 SKU 系統對帳。

<Warning>
  此頁面由 AI 自動翻譯。如有任何疑問或不一致之處，請以[英文版本](/reference/seller-reference-number)為準。
</Warning>

`sellerReferenceNumber` 是您附加到 Return Helper 紀錄上的賣家自訂識別碼，用於把這些紀錄與您自己的系統關聯起來。Return Helper 原樣儲存該值，並在相關 Webhook 事件中回傳給您。

## 三個層級

該欄位存在於三個**互相獨立**的層級上，**每個層級可承載不同的值**。請將它們視為各自獨立的對帳鍵。

| 層級             | 欄位                                            | 典型用途                 |
| -------------- | --------------------------------------------- | -------------------- |
| Return Request | `returnRequest.sellerReferenceNumber`         | 您的 RMA / 退貨單號，或顧客訂單號 |
| Shipment       | `shipment.sellerReferenceNumber`              | 您的包裹參考號、標籤批次號或訂單號    |
| Line Item      | `returnRequestLineItem.sellerReferenceNumber` | 您的 SKU 或行項目 ID       |

當您透過 User API 建立一筆退貨時，可在各層級獨立賦值。它們會在對應的 Webhook 負載中分別出現。

## 格式

字串長度為 **1–50 字元**。多數可列印字元均被接受，包括 `#`、`-`、`_` 與括號。空白字元、控制字元以及不可見 Unicode（零寬空格、BOM）會被拒絕。值原樣保存——不做修剪或大小寫正規化。

## 省略欄位時 Return Helper 會存什麼

如果您在某個層級未提供 `sellerReferenceNumber`——或傳 `null` 或 `""`——Return Helper 會以其內部序列號替代該層級的值。因此該欄位在您收到的負載中**永遠不為空**，但值可能是一個對您而言沒有意義的 Return Helper 序列號。

**如果您依賴該欄位進行對帳，請在每個層級上明確設定。**

## 商家如何使用

建立退貨時為每個層級明確設定 `sellerReferenceNumber`，然後**用 Webhook 事件中回傳的值與您自己的紀錄進行對帳**——Return Helper 會在驅動您退貨生命週期的同一組負載中攜帶該欄位，因此事件中攜帶的資訊足以直接匹配到您系統中的對應紀錄。Shipment、庫存與處理類 Webhook 事件均會在相應層級包含 `sellerReferenceNumber`。

<Note>
  `sellerReferenceNumber` 是對帳鍵，**並非**唯一性約束。您帳戶中的兩筆紀錄可以承載相同的值。請用它做匹配，而非去重。
</Note>

## 渠道整合的特定行為

當退貨是透過渠道整合而非直接透過 User API 建立時，Return Helper 會用渠道特定的識別碼自動填入 `sellerReferenceNumber`。下列值就是您在這些流程的 Webhook 負載中會看到的。

### Shopify

| 層級             | 值                                                |
| -------------- | ------------------------------------------------ |
| Return Request | Return Helper 內部序列號——**並非** Shopify 的 return ID。 |
| Shipment       | Shopify 的**訂單名稱**（例如 `#1234`）。                   |
| Line Item      | Shopify 的**商品 ID**。                              |

要把 Shopify 退貨與您的 Shopify 訂單對上，請使用 **Shipment 層級**的值（訂單名稱）。Return Request 層級的值並不攜帶 Shopify 特定資訊，應視為不透明。

### Loop

Loop 建立的是一份 Return Shipment；該流程中沒有 Return Request 層級。

| 層級                  | 值                                                  |
| ------------------- | -------------------------------------------------- |
| Return Shipment（頂層） | Loop `returnId`                                    |
| Shipment            | Loop `loopReturnLabelRequestId`                    |
| Line Item           | Loop 提供時為商品 **SKU**；否則為 `loopReturnLabelRequestId` |

要與 Loop 的紀錄對帳：頂層值標識 Loop 的退貨；Shipment 層級的值標識具體的 Loop 標籤請求。

## 範例：在 `createReturnShipment` 上設定

[Create Return Shipment](/zh-Hant/api-reference/returnshipment/create-return-shipment) 端點在三個層級都接受 `sellerReferenceNumber`。在下面的請求中，每個層級都設了一個獨特、易追蹤的值，方便您觀察它後續出現在何處。

```json highlight={6,10,32} theme={null}
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Customer return — PO 42",
  "totalValue": 30.00,
  "totalValueCurrency": "usd",
  "sellerReferenceNumber": "PO-2026-00042",
  "shipment": {
    "shipToWarehouseId": 2,
    "boxType": "cus",
    "sellerReferenceNumber": "PARCEL-A1",
    "shipFrom": {
      "country": "usa",
      "contactName": "Jane Buyer",
      "phone": "15622708183",
      "email": "user@example.com",
      "street1": "123 Example St",
      "state": "tx",
      "city": "Houston",
      "postalCode": "77235"
    },
    "parcel": {
      "weight": 200,
      "weightUnit": "g",
      "length": 20, "width": 15, "height": 10, "dimensionUnit": "cm",
      "items": [
        {
          "description": "Red T-shirt, size M",
          "weight": 200,
          "weightUom": "g",
          "value": 30.00,
          "valueCurrencyCode": "usd",
          "sellerReferenceNumber": "SKU-RED-MEDIUM"
        }
      ]
    }
  }
}
```

會產生：

| 層級             | 儲存的值                                                | 在哪裡出現                                                                                                                                                                                                                                                                                                |
| -------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Return Request | `PO-2026-00042`（頂層 `sellerReferenceNumber`）         | 任何攜帶 Return Request 物件的事件中的 `returnRequest.sellerReferenceNumber`——最常見是 [Warehouse Shipment Arrived](/zh-Hant/webhooks#warehouse-shipment-arrived-v2)（V202207）                                                                                                                                       |
| Shipment       | `PARCEL-A1`（`shipment.sellerReferenceNumber`）       | [Warehouse Shipment Arrived](/zh-Hant/webhooks#warehouse-shipment-arrived-v2) 中的 `shipment.sellerReferenceNumber`                                                                                                                                                                                    |
| Line Item      | `SKU-RED-MEDIUM`（每條 item 的 `sellerReferenceNumber`） | [Warehouse Shipment Arrived](/zh-Hant/webhooks#warehouse-shipment-arrived-v2)（V202207）中的 `returnInventoryList[].sellerReferenceNumber` 與 `lineItems[].sellerReferenceNumber`；[Inventory Handling Complete](/zh-Hant/webhooks#inventory-handling-complete) 中的 `returnInventory.sellerReferenceNumber` |

### 通知長什麼樣

當倉庫標記 Shipment 為已收貨時，`markShipmentArrive` 事件（V202207）會在同一份負載中回傳您在三個層級上設的值（下方已為清晰起見做了精簡）：

```json highlight={4,10,20,27} theme={null}
{
  "returnRequest": {
    "returnRequestId": 74484,
    "sellerReferenceNumber": "PO-2026-00042",
    "returnTitle": "Customer return - PO 42",
    "rma": "USE-2-260514-D00004-15"
  },
  "shipment": {
    "shipmentId": 43325,
    "sellerReferenceNumber": "PARCEL-A1",
    "trackingNumber": "RHDEMO202606011780282223",
    "shipmentStatusCode": 6,
    "shipmentServiceType": "fedex_ground",
    "receiveDate": "2026-06-01T03:02:00Z"
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 22501,
      "returnRequestLineItemId": 50560,
      "sellerReferenceNumber": "SKU-RED-MEDIUM",
      "rma": "USE-2-260514-D00004-15"
    }
  ],
  "lineItems": [
    {
      "returnRequestLineItemId": 50560,
      "sellerReferenceNumber": "SKU-RED-MEDIUM"
    }
  ],
  "category": "rsl",
  "action": "markShipmentArrive",
  "version": "202207"
}
```

處理完成後，Line Item 層級的值也會在 `completeInventoryHandling` 中作為庫存紀錄上的欄位出現：

```json highlight={6,7} theme={null}
{
  "returnInventory": {
    "returnInventoryId": 22501,
    "returnRequestId": 74484,
    "returnRequestLineItemId": 50560,
    "sellerReferenceNumber": "SKU-RED-MEDIUM",
    "returnRequestLineItemNumber": "SKU-RED-MEDIUM",
    "description": "Red T-shirt size M",
    "handlingCode": 2,
    "handlingStatusCode": 2,
    "completeOn": "2026-06-01T04:06:00Z",
    "rma": "USE-2-260514-D00004-15"
  },
  "category": "rinv",
  "action": "completeInventoryHandling",
  "version": "202207"
}
```

<Note>
  **V202207 欄位別名。** 在 V202207 Webhook 負載中，舊有的 `*Number` 欄位（`returnRequestNumber`、`shipmentNumber`、`returnRequestLineItemNumber`）是 `sellerReferenceNumber` 的別名，承載**相同的值**——並非 Return Helper 的內部序列。如需可靠地引用 Return Helper 紀錄，請使用 `*Id` 欄位（`returnRequestId`、`shipmentId`、`returnInventoryId`）。
</Note>

同步的 `CreateReturnShipment` 回應**不會**在任何層級回傳 `sellerReferenceNumber`——它只回傳 `returnRequestNumber`（Return Helper 內部序列）與 `referenceNumber`（您傳入的 `orderNumber`）。請用上述的 Webhook 負載做基於 SRN 的對帳。

## 對帳工作流

對於透過 `createReturnShipment` 建立的退貨：

1. **呼叫 `createReturnShipment`**，在您需要對帳的每個層級上設定 `sellerReferenceNumber`。同步回應會回傳 Return Helper 的內部 ID（`returnRequestId`、`shipmentId`、`labelId`），但**不會**回傳 `sellerReferenceNumber`。
2. **等待 `markShipmentArrive` Webhook**（版本差異見下文）。這是第一個把您的 SRN 值與 Return Helper 識別碼綁在一起回傳給您的事件。
3. **持久化映射**——把您的訂單（按 SRN）與 `returnInventoryId` 關聯起來。SRN 是連接鍵；`returnInventoryId` 是您此後用於所有作業的主鍵。許多商家也會同時儲存 `returnRequestId` 與 `shipmentId` 用於較高層的分組，但包裹收貨後作業上的主鍵是 `returnInventoryId`。
4. **從此之後，使用 `returnInventoryId` 與 Return Helper 溝通**——用於處理指令、VAS、Recall、Dispose，以及任何後續的庫存層級 Webhook，例如 [Inventory Handling Complete](/zh-Hant/webhooks#inventory-handling-complete)。您持久化的映射會把那些事件路由回正確的顧客訂單。

對於透過渠道整合（Shopify、Loop）建立的退貨，第 1 步由渠道把退貨推送到 Return Helper 替代；自動填入的 SRN 值見 [渠道整合的特定行為](#channel-specific-behaviour)。第 2–4 步完全一致。

### `markShipmentArrive` 版本

`markShipmentArrive` 存在兩種負載形態。**V202207 是新帳號的預設版本**——您的帳號接收這一版本，除非您明確聯絡 Return Helper 客服切換至 V202407。

| 版本                | 負載形態                                                                                     | 庫存投遞方式                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **V202207**（預設）   | 打包——`shipment`、`returnRequest`、`returnInventoryList[]`、`lineItems[]`、`label` 一次性放在同一個事件中 | 內嵌於 `returnInventoryList[]`                                                      |
| **V202407**（按需啟用） | 精簡——僅含 `shipment` 物件                                                                     | 串流——其後跟隨每筆庫存紀錄一個 [`newInventoryCreated`](/zh-Hant/webhooks#inventory-created) 事件 |

兩者產生的是相同的生命週期與相同的終態。差異在於投遞方式：V202207 把所有資訊塞進一個大負載中（一次處理完事），V202407 發出更精簡的 `markShipmentArrive` 後再單獨投遞庫存事件（每筆負載較小，當一個 shipment 拆出許多庫存時較合適）。如果您預期 shipment 經常會產生很多庫存（多包裹或 VAS 拆件），請聯絡客服啟用 V202407。

針對同一工作流的 V202407 `markShipmentArrive` 負載長這樣：

```json highlight={7} theme={null}
{
  "shipment": {
    "shipmentId": "43328",
    "returnRequestId": "74487",
    "trackingNumber": "RHDEMO202606011780289491",
    "referenceNumber": "PO-2026-00042",
    "sellerReferenceNumber": "PARCEL-A1",
    "shipToWarehouseId": 2,
    "receiveDate": "2026-06-01T04:54:25Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "version": "202407"
}
```

只有 Shipment 層級的 SRN 出現。`sellerReferenceNumber` 與 `referenceNumber` 是互相獨立的欄位——V202407 不使用 V202207 那種 `*Number` 別名模式。

**對上述工作流的影響：**

* **V202207**——第 2 步是一次連接：一個 `markShipmentArrive` 事件就給您第 3 步所需的全部 SRN 層級與全部 Return Helper ID。
* **V202407**——第 2 步變成兩階段連接。`markShipmentArrive` 給您 `shipment.sellerReferenceNumber` ↔ `shipmentId`。其後每筆 `newInventoryCreated` 攜帶 `shipmentId`（您在第 1 步存的映射中查它），以及新的 `returnInventoryId`（您把它持久化以供第 3 步起使用）。因為 `newInventoryCreated` 本身不攜帶 `sellerReferenceNumber`，`shipmentId` 鏈條是唯一的連接路徑——您必須在庫存事件抵達**之前**就把 SRN ↔ `shipmentId` 映射存好。

## 建議

* 在每個對帳重要的層級上**明確**設定 `sellerReferenceNumber`，不要依賴預設值。
* 把三個層級視為各自獨立。Shopify 下它們永遠不同；直接透過 User API 使用時也可能不同。
* 用 Webhook 負載追蹤生命週期事件，而非輪詢列表端點。具體哪個事件攜帶哪個層級的 `sellerReferenceNumber`，參見 [Webhooks 參考](/zh-Hant/webhooks)。