Return Helper API
Return Helper は、返品リクエストの作成から、配送追跡、ラベル生成、倉庫処理まで、Eコマースの商品返品をエンドツーエンドで管理するAPIスイートを提供しています。このAPIはサーバー間連携専用です。クライアントサイドのコードからこれらのエンドポイントを直接呼び出さないでください。
利用可能なAPI
User API — 返品リクエスト、配送、ラベル、在庫、アカウント設定を管理するための、マーチャントおよびパートナー向け認証済みエンドポイントです。 Public API — サービスタイプ、倉庫一覧、ステータスコード、対応国などのルックアップ値を公開する参照データエンドポイントです。認証
すべてのAPIリクエストには、リクエストヘッダーとしてAPIキーとトークンが必要です：- Return Helper ユーザーポータルにログインします。
- 設定 → 署名キーとAPIトークン に移動します。
- 既存のキーとトークンのペアが一覧表示されます。新しいペアを生成することもできます。
ユーザーポータルの署名キー、APIトークン、APIキー
ベースURL
サンドボックス
本番環境
冪等性(Idempotency)
状態変更リクエスト（返品配送(Return Shipment)や在庫の作成など）では、ネットワーク再試行時に重複操作が発生しないよう、冪等性キー(Idempotency Key)を含めてください。User-Agentヘッダー
問題を調査する際にReturn Helperサポートがあなたの連携を識別できるよう、User-Agentヘッダーを含めてください：
OpenAPI仕様
完全なAPI仕様はOpenAPI 3.1ドキュメントとして提供されています。PostmanやInsomniaなどのAPIクライアントに直接インポートしたり、OpenAPI Generatorなどのツールを使用してクライアントSDKを生成したりするために使用できます。OpenAPI仕様をダウンロード
openapi.json — OpenAPI 3.1エラーハンドリング
すべてのレスポンス（成功・失敗を問わず）は共通のエンベロープにラップされます：correlationId および meta と同じトップレベルに追加フィールドとして含まれます（例：getAllCountries は { correlationId, meta, countries: [...] } を返します）。ペイロードを読み取る前に必ず meta.errorCode を確認してください。本 API はソフトエラー方式を採用しており、バリデーション失敗時には HTTP 200 が返され、meta.status: 400 と meta.errorCode が設定されます。
失敗パターン
バリデーション失敗の例
correlationId をログに記録してください。Return Helper サポートが問題調査の際にこの ID を用いてリクエストを追跡します。
一般的な注意事項
- すべての
dateTimeパラメーターはISO 8601形式でなければなりません。そうでない場合、APIはパースできません。 - 日付文字列パラメーター（例：
createToStr、createFromStr）もISO 8601形式である必要があります；時刻部分は無視されます。 - APIから返されるすべてのタイムスタンプはUTCです。