メインコンテンツへスキップ
このページはAIによって自動翻訳されています。不明点や相違がある場合は、英語版を正式版として参照してください。

​
Return Helper API

Return Helper は、返品リクエストの作成から、配送追跡、ラベル生成、倉庫処理まで、Eコマースの商品返品をエンドツーエンドで管理するAPIスイートを提供しています。
このAPIはサーバー間連携専用です。クライアントサイドのコードからこれらのエンドポイントを直接呼び出さないでください。

​
利用可能なAPI

User API — 返品リクエスト、配送、ラベル、在庫、アカウント設定を管理するための、マーチャントおよびパートナー向け認証済みエンドポイントです。 Public API — サービスタイプ、倉庫一覧、ステータスコード、対応国などのルックアップ値を公開する参照データエンドポイントです。

​
認証

すべてのAPIリクエストには、リクエストヘッダーとしてAPIキーとトークンが必要です： 
x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
認証情報の取得方法：
  1. Return Helper ユーザーポータルにログインします。
  2. 設定 → 署名キーとAPIトークン に移動します。
  3. 既存のキーとトークンのペアが一覧表示されます。新しいペアを生成することもできます。
ユーザーポータルの署名キー、APIトークン、APIキー
APIトークンは秘密情報です。他者と共有したり、クライアントサイドのコードに公開しないでください。

​
ベースURL

​
サンドボックス

エンドポイントベースURL
User APIhttps://api.returnshelper.com/uat/user/api
Public APIhttps://api.returnshelper.com/uat/public/api

​
本番環境

エンドポイントベースURL
User APIhttps://api.returnhelpercentre.com/v1/user/api
User API（中国）https://api.returnhelperchina.com/user/
Public APIhttps://api.returnhelpercentre.com/v1/public/api

​
冪等性(Idempotency)

状態変更リクエスト（返品配送(Return Shipment)や在庫の作成など）では、ネットワーク再試行時に重複操作が発生しないよう、冪等性キー(Idempotency Key)を含めてください。 
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
各トランザクションリクエストに対して、新しいUUID（または同様にユニークな文字列）を生成してください。サーバーは同じキーの再送信を認識し、操作を一度だけ実行してデータの整合性を維持します。

​
User-Agentヘッダー

問題を調査する際にReturn Helperサポートがあなたの連携を識別できるよう、User-Agentヘッダーを含めてください： 
User-Agent: {app name}/{app version} (Platform={os version}; Runtime={runtime version}; Language={language})
例： 
User-Agent: CompanyABCApi/2024.16.0 (Platform=Unix/13.4.0; Runtime=8.0.2; Language=CSharp12)
完全なリクエストヘッダーの例： 
x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
User-Agent: YourApp/1.0.0 (Platform=Linux/5.15; Runtime=8.0.2; Language=CSharp12)

​
OpenAPI仕様

完全なAPI仕様はOpenAPI 3.1ドキュメントとして提供されています。PostmanやInsomniaなどのAPIクライアントに直接インポートしたり、OpenAPI Generatorなどのツールを使用してクライアントSDKを生成したりするために使用できます。

OpenAPI仕様をダウンロード

openapi.json — OpenAPI 3.1

​
エラーハンドリング

すべてのレスポンス（成功・失敗を問わず）は共通のエンベロープにラップされます： 
{
  "correlationId": "0HNL9S3BA31VM:00000001",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  }
}
成功レスポンスでは、ビジネスペイロードが correlationId および meta と同じトップレベルに追加フィールドとして含まれます（例：getAllCountries は { correlationId, meta, countries: [...] } を返します）。ペイロードを読み取る前に必ず meta.errorCode を確認してください。本 API はソフトエラー方式を採用しており、バリデーション失敗時には HTTP 200 が返され、meta.status: 400 と meta.errorCode が設定されます。

​
失敗パターン

失敗実際の HTTPボディ
x-rr-apikey / x-rr-apitoken が不正または欠落401meta.status: 401、meta.error.message が認証失敗の理由を示します
バリデーション失敗（必須項目欠落、型不一致、業務ルール違反）200meta.status: 400、meta.errorCode: "VALIDATION_FAILED"、meta.error はリクエスト項目をキーとして格納されます
成功200meta.status: 200、meta.errorCode: null、ペイロードはトップレベルに配置

​
バリデーション失敗の例

{
  "correlationId": "0HNLB2U6T1QG1:00000001",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "returnInventoryId": "'return Inventory Id' must not be empty."
    }
  }
}
実際の HTTP ステータスコードだけで成否を判定しないでください。200 OK でも論理的には失敗の場合があります。必ず meta.status と meta.errorCode を確認してください。
統合時には、レスポンスごとに correlationId をログに記録してください。Return Helper サポートが問題調査の際にこの ID を用いてリクエストを追跡します。

​
一般的な注意事項

  • すべてのdateTimeパラメーターはISO 8601形式でなければなりません。そうでない場合、APIはパースできません。
  • 日付文字列パラメーター（例：createToStr、createFromStr）もISO 8601形式である必要があります；時刻部分は無視されます。
  • APIから返されるすべてのタイムスタンプはUTCです。

​
Webhook

ラベル結果および倉庫イベント（配送到着、在庫作成、画像アップロードなど）は、Webhook通知を通じて非同期で配信されます。これらのイベントを受信するには、通知エンドポイントを登録する必要があります。 通知イベントタイプとそのペイロードの完全な一覧については、Webhookセクションを参照してください。