> ## 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.

# Return Shipment を作成

<Warning>
  このページはAIによって自動翻訳されています。API技術仕様は英語が正式です。不明点がある場合は[英語版](/api-reference/returnshipment/create-return-shipment)を参照してください。
</Warning>

ラベルリクエストを伴う返品シップメントを作成します——ほぼすべての Return Helper 統合の入口です。シップメントは 1 つまたは複数のパーセルを、商品・連絡先・寸法とまとめて表します。ラベル生成は非同期キューで処理され、即時レスポンスでシップメント ID と `labelRequestStatusCode`（通常は `queued`）が返り、実際のラベル URL は後ほど webhook で配信されます。

## 前提条件

呼び出し前に以下を準備してください：

1. **`serviceTypeCode`** — 以下のいずれかから利用可能な返品サービスを取得してください：
   * [すべての返品サービスタイプを取得](/ja/api-reference/servicetype/get-all-return-service-types)
   * [発地国と倉庫でサービスタイプを取得](/ja/api-reference/servicetype/get-service-types-by-origin-country-and-warehouse)
2. **発地・宛先国コード** — [すべての発地国を取得](/ja/api-reference/country/get-all-from-countries-origin-countries) と [すべての国を取得](/ja/api-reference/country/get-all-countries) で取得します。コードは **ISO3**（`usa`、`gbr`、`chn`）です。
3. **パーセル寸法と重量** — 必須かつ `> 0` であること。単位は [すべての寸法単位を取得](/ja/api-reference/dimensionuom/get-all-dimension-units-of-measurement) および [すべての重量単位を取得](/ja/api-reference/weightuom/get-all-weight-units-of-measurement) で確認できます。
4. **冪等キー** — 強く推奨。`x-returnhelper-idempotency-key` に新しい UUID を送って、リトライによる重複シップメントを防いでください。詳細は [冪等性セクション](/ja/introduction#idempotency) を参照してください。

## 重要なフィールド

* **`totalValue` と `totalValueCurrency`** — `totalValue` は `parcel.items[].value` の合計と厳密に等しい必要があります。通貨は ISO 4217（例：`USD`、`GBP`、`EUR`）。コードがサポートされているかは [すべての取引タイプを取得](/ja/api-reference/transactiontype/get-all-transaction-types) で確認してください。
* **`parcel.items`** — 複数明細のサポートはアカウント設定に依存します。単一明細のみ許可されているアカウントが複数明細を送ると、バリデーションのソフトエラーになります。設定変更が必要な場合はサポートにご連絡ください。
* **寸法** — `dimension1` が最長辺、`dimension2` が次に長い辺、`dimension3` が最短辺です。
* **`sellerReferenceNumber`** — 出品者側の識別子で、3 つの独立したレイヤー（トップレベル、`shipment`、`parcel.items[]` 内の各アイテム）で受け付けます。そのまま保存され、Webhook イベントで返却されるため自社の注文システムとの突合に利用できます。レイヤーの意味、省略時のフォールバック挙動、推奨される突合ワークフローについては [Seller Reference Number](/ja/reference/seller-reference-number) を参照してください。

## ラベル生成は非同期

即時レスポンスには `labelRequestStatusCode: queued` が含まれます。最終的なラベル URL と追跡番号は `labelGenerated` webhook イベント（失敗時は `labelFailed`）で配信されます。倉庫到着は `markShipmentArrive` イベント、その後 `inventoryCreated` イベントが続きます。[Webhooks](/ja/webhooks) を購読してください——webhook はシップメントライフサイクルの真実のソースであり、ポーリングの代替手段ではありません。

## 関連

* [発地から配送料を取得](/ja/api-reference/shipment/get-shipping-fees-from-origin-location) — コミット前に料金をプレビュー。
* [Webhooks](/ja/webhooks) — `labelGenerated`、`labelFailed`、`markShipmentArrive` を購読してシップメントライフサイクル全体を受信。
* [Seller Reference Number](/ja/reference/seller-reference-number) — `sellerReferenceNumber` の設定方法と、Webhook イベントを使った自社注文レコードとの突合方法。


## OpenAPI

````yaml post /api/ReturnShipment/createReturnShipment
openapi: 3.1.0
info:
  title: Return Helper API
  description: API documentation for Return Helper — covering User and Public endpoints.
  version: 1.0.0
servers:
  - url: https://api.returnshelper.com/uat/user
    description: Sandbox — User API
  - url: https://api.returnshelper.com/uat/public
    description: Sandbox — Public API
  - url: https://api.returnhelpercentre.com/v1/user
    description: Production — User API
  - url: https://api.returnhelpercentre.com/v1/public
    description: Production — Public API
  - url: https://api.returnhelperchina.com/user
    description: Production — User API (China)
security:
  - ApiKey: []
    ApiToken: []
paths:
  /api/ReturnShipment/createReturnShipment:
    post:
      tags:
        - ReturnShipment
      summary: Create return shipment
      operationId: ReturnUserApi_CreateReturnShipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateReturnShipmentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeneralCreateReturnShipmentReply'
        '401':
          description: >-
            Authentication failed. Returned when the `x-rr-apikey` or
            `x-rr-apitoken` header is missing or invalid. The body uses the
            standard `ApiResponse` envelope with `meta.error.message` describing
            the auth failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - ApiKey: []
          ApiToken: []
      servers:
        - url: https://api.returnshelper.com/uat/user
          description: Sandbox — User API
components:
  schemas:
    CreateReturnShipmentRequest:
      type: object
      properties:
        serviceTypeCode:
          type: string
          description: Return service type code
          default: fedex_ground
        orderTitle:
          type: string
          description: Order title / return title
          default: Return Label Title
        totalValue:
          type: number
          description: Total declared value of the return
          default: 100
        totalValueCurrency:
          type: string
          description: Currency code for totalValue (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number
        remarks:
          type: string
          description: Additional remarks
        shipment:
          $ref: '#/components/schemas/CreateShipmentPayload'
          description: Shipment details including origin address and parcel info
      required:
        - serviceTypeCode
        - orderTitle
        - totalValue
        - totalValueCurrency
        - shipment
    GeneralCreateReturnShipmentReply:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreateReturnShipmentReply'
          description: Created return shipment details
    ApiResponse:
      type: object
      description: >-
        Universal response envelope. Successful responses include the business
        payload as additional top-level fields alongside `correlationId` and
        `meta`. Failed responses (auth errors, validation errors) only populate
        `correlationId` and `meta`, with `meta.errorCode` and `meta.error`
        describing the failure.
      properties:
        correlationId:
          type:
            - string
            - 'null'
          description: >-
            Unique correlation ID for tracing the request through Return Helper
            systems.
        meta:
          $ref: '#/components/schemas/ApiResponseMeta'
    CreateShipmentPayload:
      type: object
      properties:
        shipToWarehouseId:
          type: integer
          description: Destination warehouse ID
          default: 2
        boxType:
          type: string
          description: Box type code
          default: cus
        sellerReferenceNumber:
          type: string
          description: Seller reference number for this shipment
        shipFrom:
          $ref: '#/components/schemas/ReturnShipmentShipFromPayload'
          description: Origin address
        parcel:
          $ref: '#/components/schemas/ReturnShipmentParcelPayload'
          description: Parcel dimensions, weight, and item list
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
      required:
        - shipToWarehouseId
        - boxType
        - shipFrom
        - parcel
    CreateReturnShipmentReply:
      type: object
      properties:
        returnRequestId:
          type: integer
          format: int32
        returnRequestNumber:
          type:
            - string
            - 'null'
        shipmentId:
          type: integer
          format: int64
        referenceNumber:
          type:
            - string
            - 'null'
        labelId:
          type: integer
          format: int64
        labelRequestStatusCode:
          type:
            - string
            - 'null'
        cost:
          type: number
          format: decimal
        costCurrencyCode:
          type:
            - string
            - 'null'
    ApiResponseMeta:
      type: object
      description: >-
        Application-level metadata for every API response. Inspect `status` and
        `errorCode` to detect soft-error responses (validation failures arrive
        as HTTP 200 with `meta.status: 400`).
      properties:
        status:
          type: integer
          description: >-
            Application-level status code. For successful operations this
            mirrors the HTTP status (e.g. 200). For validation failures it
            reports the logical status (e.g. 400) even though the wire HTTP
            status is 200.
        data:
          type: object
          additionalProperties:
            type: string
          description: Reserved free-form metadata key/value pairs. Usually empty.
        errorCode:
          type:
            - string
            - 'null'
          description: >-
            Machine-readable error code (e.g. `VALIDATION_FAILED`). Non-null
            only when the operation failed.
        error:
          type: object
          additionalProperties: true
          description: >-
            Field-level or message-level error detail keyed by request property
            name. Empty object on success.
    ReturnShipmentShipFromPayload:
      type: object
      properties:
        country:
          type: string
          description: ISO3 origin country code
          default: usa
        contactName:
          type: string
          description: Sender contact name
          default: Your name
        phone:
          type: string
          description: Sender phone number
          default: '15622708183'
        email:
          type: string
          description: Sender email address
          default: user@example.com
        fax:
          type: string
          description: Sender fax number
        street1:
          type: string
          description: Address line 1
          default: Some address line 1
        street2:
          type: string
          description: Address line 2
          default: Some address line 2
        street3:
          type: string
          description: Address line 3
        state:
          type: string
          description: State / province
          default: tx
        city:
          type: string
          description: City
          default: Houston
        postalCode:
          type: string
          description: Postal code
          default: '77235'
      required:
        - country
        - contactName
        - street1
        - state
        - city
        - postalCode
    ReturnShipmentParcelPayload:
      type: object
      properties:
        weight:
          type: number
          description: Parcel weight
          default: 10.5
        weightUnit:
          type: string
          description: Weight unit (e.g. kg)
          default: g
        length:
          type: number
          description: Length (longest side)
          default: 10
        width:
          type: number
          description: Width (second longest side)
          default: 10
        height:
          type: number
          description: Height (shortest side)
          default: 10
        dimensionUnit:
          type: string
          description: Dimension unit (e.g. cm)
          default: cm
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReturnShipmentItemPayload'
          description: List of items in the parcel
          default:
            - description: Test item
              weight: 10.5
              value: 100
              weightUom: g
              valueCurrencyCode: usd
      required:
        - weight
        - weightUnit
        - length
        - width
        - height
        - dimensionUnit
        - items
    ReturnShipmentItemPayload:
      type: object
      properties:
        description:
          type: string
          description: Item description
          default: Test item
        weight:
          type: number
          description: Item weight
          default: 10.5
        weightUom:
          type: string
          description: Weight unit of measure (e.g. kg, g)
          default: g
        value:
          type: number
          description: Declared value of the item
          default: 100
        valueCurrencyCode:
          type: string
          description: Currency code for the declared value (e.g. USD)
          default: usd
        sellerReferenceNumber:
          type: string
          description: Seller reference number for the item
        customFieldMap:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata
          default:
            sku: '1234567890'
            hsCode: '1234567890'
            countryOfOrigin: usa
      required:
        - description
        - weight
        - weightUom
        - value
        - valueCurrencyCode
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-rr-apikey
      description: Your API key
    ApiToken:
      type: apiKey
      in: header
      name: x-rr-apitoken
      description: Your API token — keep this private

````