ReturnGO 接続：API で RMA を取り込み、返品ラベルに対応

ReturnGO ダッシュボードの Settings → API で API キーを生成し、公式 API ドキュメントの Servers 欄から API サーバーの URL をコピーします。キー、ショップドメイン、サーバー URL を Integration に入力し、実際の読み取り専用プローブに合格してから有効化してください。

ReturnGO コネクタは、ReturnGO API を通じて ReturnGO の返品（RMA）を返品システム（RMS）に取り込みます。RMA 一覧と RMA 詳細を読み取り、この接続は返品ラベルに対応します。スケジュールに従った API 取得で動作します。この接続には webhook がないため、ReturnGO の新しい返品は作成された瞬間ではなく、次回の取得時にここに表示されます。接続のフィールドは 4 つです：API キー、ショップドメイン、公式 API ドキュメントからコピーする API サーバーの URL、そして任意のヘッダー名です。

前提条件#

• ログインできる ReturnGO アカウントがあり、ダッシュボードの Settings → API ページにアクセスできること。
• 接続するショップについて ReturnGO に登録されているショップドメインが分かっていること。demo-store.myshopify.com のようなドメインであり、購入者に表示されるショップ名ではありません。
• ReturnGO の公式 API ドキュメントを開き、Servers 欄を見つけられること。この接続の API サーバー URL はそこから自分でコピーするもので、代わりになる組み込みのデフォルトはありません。
• ReturnGO の API キー 1 つで複数のショップを管理できます。そのため、各接続がどのショップ向けかを把握してください。ショップドメインのフィールドが、この接続がどのショップから取得するかを示します。

認証情報の取得#

1. ReturnGO ダッシュボードにログインし、Settings → API を開きます。
2. そこで API キーを生成し、全文コピーします。1 つのキーで複数のショップを管理できるため、同じキーを複数のショップ接続に使うことができます。
3. ReturnGO に登録されているとおりにショップドメインを正確に控えます。例：demo-store.myshopify.com。リクエスト時、この値は x-shop-name ヘッダーで送信されるため、表示名ではなくドメイン自体をコピーしてください。
4. ReturnGO の公式 API ドキュメントを開き、Servers 欄を見つけて、そこに表示されている API サーバーのアドレスをコピーします。このアドレスは必須で、その欄から取得しなければなりません。推測したり、別のドキュメントのアドレスを流用したりしないでください。
5. 導入時に ReturnGO から別の API キーのヘッダー名が提示された場合に限り、その名前も控えてください。ほとんどの場合、ヘッダー名は x-api-key で、他に用意するものはありません。

Integration への入力#

1. Integration → コネクタマーケットプレイス → ReturnGO → 新規接続 を開きます。
2. api_key、必須、ReturnGO API Key：ReturnGO ダッシュボードの Settings → API で生成したキーを全文貼り付けます。パスワード型のフィールドで、秘密情報として保存されます。
3. shop_name、必須、ショップドメイン：ReturnGO に登録されているショップドメイン（例：demo-store.myshopify.com）を入力します。ショップの表示名ではなくドメイン自体を入力してください。リクエストではこの値が x-shop-name ヘッダーに入ります。
4. base_url、必須、API サーバー URL：ReturnGO 公式 API ドキュメントの Servers 欄からコピーした API サーバーのアドレスを、そこに表示されているとおり https://… の形式で貼り付けます。このフィールドにデフォルトはありません。空欄のままだと、テストは何も送信する前に止まります。
5. api_key_header、任意、API キーのヘッダー名：通常は x-api-key のままにします。入力するのは、導入時に ReturnGO から別のヘッダー名が提示された場合のみで、その場合はその名前を正確に入力してください。

接続テスト#

接続テストをクリックします。認証情報を入力した場合、テストは実際の読み取り専用プローブを実行します。入力した API サーバーのアドレスへ GET {base_url}/rmas?pagesize=1 を送信し、API キーをそのヘッダー（デフォルトは x-api-key、または入力したヘッダー名）に、ショップドメインを x-shop-name ヘッダーに入れ、応答に 12 秒を許可します。成功した応答、つまり GET /rmas のプローブ成功メッセージが合格となります。プローブは、サーバーのアドレスが応答すること、キーが受け入れられること、ショップドメインが認識されることを、何も変更せずに証明するからです。base_url が未入力の場合、テストは MISSING_BASE_URL で止まり、リクエストは一切送信しません。キーまたはショップドメインが未入力の場合は、偽の合格を報告せず、不足している認証情報により明確に失敗します。認証情報をまったく入力せずにテストした場合、結果はシミュレーションによるチェックのみで、シミュレーションと表示されます。必須の 3 フィールドを入力して再テストすると、実際のプローブが行われます。

Mapping / テンプレート選択#

ReturnGO 標準の Mapping を選択します。API が返す内容に対応します。RMA 一覧と各 RMA の詳細がこちらの返品レコードになり、1 件の返品を探すときは注文番号で取得範囲を絞ることができます。テスト合格後、1 回取得を実行し、実 RMA を ReturnGO と並べて比較してください（RMA 参照、注文参照、商品、数量）。さらに、その返品のラベルの流れを確認してから有効化します。ReturnGO の項目が想定と異なる場合は、ReturnGO 側を変更せず、Mapping でその項目を調整してください。

有効化#

有効化後、接続は設定した頻度で ReturnGO の RMA を返品システムに取り込みます（一覧と詳細を一緒に）。倉庫はここでそれらの返品を処理し、この接続は返品ラベルに対応します。最初は Runs / Logs で取得を確認し、ReturnGO と照合してから無人運用に移してください。

この接続が行わないこと：webhook で返品を受け取ることはしません。そのため、ReturnGO で作成された返品が発生した瞬間にここへプッシュされることはなく、次回の定期取得で届きます。急ぎの返品については、スケジュールを待たず、注文番号で絞り込んで手動取得を実行してください。

よくある質問#

テストが MISSING_BASE_URL で止まる

base_url フィールドが空です。この接続にはサーバーアドレスが組み込まれていません。プローブは GET /rmas の送信先を知るために API サーバーの URL が必要なため、アドレスがないとリクエストを送信する前に止まり、MISSING_BASE_URL を報告します。

ReturnGO の公式 API ドキュメントを開き、Servers 欄から表示どおりにサーバーアドレスをコピーし、base_url に https://… の形式で貼り付けて保存し、再テストしてください。

API キーが正しいのにプローブが失敗する

プローブはキーだけを確認するのではありません。ショップドメインを x-shop-name ヘッダーで送信し、base_url のアドレスとも通信します。よくある原因は shop_name です。登録済みドメインではなくショップの表示名が入っているため、キー自体が有効でも ReturnGO がショップを認識しません。base_url を間違った場所からコピーした場合も同じように失敗します。

shop_name を ReturnGO に登録されているドメイン（demo-store.myshopify.com の形式）に設定し、公式 API ドキュメントの Servers 欄から base_url をコピーし直してください。キーはそのままにして、保存して再テストしてください。

api_key_header は入力すべきですか？

ほとんどの場合は不要です。API キーを運ぶヘッダーはデフォルトで x-api-key であり、接続はすでにそのデフォルトを使っています。このフィールドは、導入時に ReturnGO から別のヘッダー名を提示されたショップのためにだけ存在します。作り出した名前を入力したり、指示なく変更したりすると、機能しているキーが壊れているように見えてしまいます。

導入時に ReturnGO から書面で別の名前が提示された場合を除き、api_key_header は x-api-key のままにしてください。提示された場合はその名前を正確に入力します。トラブルシューティング中に変更した場合は、x-api-key に戻して再テストしてください。

認証情報を入力していないのにテストが合格した — 接続できていますか？

いいえ。認証情報がまったくない場合、テストはシミュレーションによるチェックのみを実行し、結果をシミュレーションと表示します。ReturnGO には決して到達しないため、キー、ショップドメイン、サーバーアドレスについては何も証明しません。

必須の 3 フィールドをすべて入力してください。api_key は Settings → API から、shop_name は登録済みドメイン、base_url は公式 API ドキュメントの Servers 欄からコピーします。保存して再テストしてください。GET /rmas プローブの結果だけが実際の合格となります。

接続済みだが ReturnGO の新しい返品がここに表示されない

この接続はスケジュールに従って API で取得し、webhook がないため、1 分前に作成された返品は正しく次回の取得を待ちます。もう 1 つのよくある原因はショップです。1 つの API キーで複数のショップを管理でき、この接続は shop_name ドメインが指すショップからのみ取得します。同じキーの下で別のショップに作成された返品はここに表示されません。

その返品が shop_name のドメインが指すショップのものか確認し、手動取得を実行してください。その返品を探す場合は注文番号で絞り込み、Runs / Logs を確認してください。手動取得で届けば接続は正常で、次回以降は定期取得で届きます。

プローブが応答なくタイムアウトする

プローブは base_url のサーバーが GET /rmas に応答するのを 12 秒待ちますが、その間に何も返ってきませんでした。これはアドレス自体を指しています。間違った欄からコピーしたサーバー URL、入力時に一部が欠けたり余分だったりするもの、またはショップが使う環境とは異なる環境のものは、このショッププローブには応答しません。

ReturnGO 公式 API ドキュメントの Servers 欄から base_url をコピーし直し、表示どおりに何も加減せず貼り付けて保存し、再テストしてください。アドレスを修正している間はキーやショップドメインを変更しないでください。一度に変更するのは 1 つの値だけにしてください。