Sage X3 接続：folder の Sync API 接続を確認する

テナントのオンボーディングで発行される 7 つの値（環境、Sync API ベース URL、folder、テナント API キー、Sage ID の OAuth ペア）を揃え、Integration に入力してテストします。テストはトークンを交換し、folder を確認します。この接続は接続確認専用で、注文・在庫・顧客の同期は行いません。

Sage X3 接続は、このシステムがお客様のテナント上のある Sage X3 folder の Sync API に到達できるかを確認します。Sage ID のトークンを交換し、その folder の変更フィードを 1 回読み取ります。範囲を明確にしてください。接続確認が、この接続が現在行うすべてです。注文、顧客、在庫の取込は行わず、在庫の返送も行いません。Sync API は汎用のテーブル単位の同期インターフェースであり、注文・在庫・顧客のテーブル名と列マッピングは、お客様自身の folder のメタデータで、導入環境ごとに確認する必要があるためです。テスト合格は、以下の 7 つの値がその folder に対して一緒に機能することの証明であり、それ以上ではありません。

前提条件#

• Sync API が利用できるテナントを持つ Sage X3 導入環境と、確認したい X3 folder が 1 つあること。例：SEED。
• その導入環境のテナント・オンボーディング資料一式：Sync API ベース URL、テナント API キー、正確な folder 名。folder 名は大文字小文字を区別するため、発行された通りの表記を保持してください。
• 同じオンボーディングで、このテナント向けに発行された Sage ID の OAuth クライアント認証情報ペア（client ID と client secret）。
• 接続先の環境が production か test か分かっていること。入力する単語によって、テストが使う Sage のトークンアドレスが決まります。

認証情報の取得#

1. Sage X3 管理者、またはテナントのオンボーディングを担当したチームに、この導入環境のオンボーディング資料一式を依頼してください。この接続の 7 つの値はすべてそのオンボーディングから来ます。このガイドに別の登録ページはなく、値を創作したり、別のテナントの値を借用したりしないでください。
2. 資料一式から、テナントの Sync API ベース URL を控えます。形式は https://tenant-host/syncapi で、ホスト部分は自社のテナントのものです。
3. folder 名を資料一式の表記通り、大文字小文字も含めて控えます。例：SEED。後のテストでは、この正確な名前でその folder を問い合わせます。
4. 資料一式のテナント API キーを控え、秘密に保管してください。テスト時には、トークンとともに X-API-KEY ヘッダーとして送信されます。
5. 同じ資料一式の Sage ID OAuth client ID と client secret を控えます。この 2 つは 1 組のペアです。別のペアの secret を混ぜないでください。
6. 資料一式で token audience が求められているか確認してください。オンボーディング文書で明示されている場合にのみ必要な値です。そうでなければ、入力時に空欄にします。

Integration への入力#

1. Integration → コネクタマーケットプレイス → Sage X3 → 新規接続を開きます。
2. environment、必須、環境：本番テナントには文字通り production、テストテナントには test と入力します。production は Sage のトークンアドレス https://id.sage.com/oauth/token を、test は https://id-shadow.sage.com/oauth/token を使います。
3. tenant_base_url、必須、テナント Sync API ベース URL：オンボーディングで発行された Sync API ベース URL（例：https://tenant-host/syncapi）を貼り付けます。ホスト部分は自社のテナントのものにしてください。
4. folder、必須、X3 folder：発行された通りの folder 名（例：SEED）を入力します。このフィールドは大文字小文字を区別します。ここでは seed と SEED は別の名前です。
5. tenant_api_key、必須、テナント API キー：オンボーディング資料一式のテナント API キーを貼り付けます。パスワード型のフィールドで、秘密情報として保存され、テスト時に X-API-KEY ヘッダーとして送信されます。
6. client_id、必須、OAuth client ID：同じ資料一式の Sage ID OAuth ペアの client ID を貼り付けます。パスワード型のフィールドで、秘密情報として保存されます。
7. client_secret、必須、OAuth client secret：同じ OAuth ペアの client secret を貼り付けます。パスワード型のフィールドで、秘密情報として保存されます。ID と secret は同じペアのものでなければなりません。
8. audience、任意、Token audience：テナントのオンボーディング文書で token audience が明示されている場合にのみ入力します。そうでなければ空欄にしてください。その場合、テストは audience なしでトークンを要求します。

接続テスト#

接続テストをクリックします。テストはまず 5 つの必須の認証情報の値を確認し、いずれかが未入力なら名前付きの結果で止まります：MISSING_TENANT_BASE_URL、MISSING_FOLDER、MISSING_TENANT_API_KEY、MISSING_CLIENT_ID、MISSING_CLIENT_SECRET。その後、共有の 12 秒制限の中で 2 つの実際の手順を実行します。まず、environment で選択されるアドレスで client_id と client_secret を Sage ID のトークンと交換し、audience を入力した場合はそれも加えます。次に、テナントの Sync API に folder の変更を問い合わせ、トークンを Authorization: Bearer として、テナント API キーを X-API-KEY として同時に送信します。200 の応答で合格となり、結果には到達した folder が表示されます。401 は INVALID_TOKEN、403 は MISSING_SCOPE、404 は NOT_FOUND として報告されます。各意味は下の FAQ をご覧ください。

Mapping / テンプレート選択#

この接続には設定する標準 Mapping も、選ぶテンプレートもありません。Sync API はテーブル単位で動作し、注文・在庫・顧客のテーブル名と列は folder ごとに異なるため、導入環境向けにデータ接続を準備する際に folder のメタデータで確認します。ここで推測したり入力したりするものではありません。その導入ごとの確認が folder について完了するまでは、この接続はテスト手順で行う接続確認にとどまります。推測したマッピングに合わせるために、Sage X3 のテーブル名や項目名を変更しないでください。

有効化#

テスト合格後、接続を有効化すると、確認済みの値で Integration に保存され、後で同じ認証情報で同じ folder を再確認できます。有効化でデータフローが始まることはありません。この接続では注文、顧客、在庫はどちらの方向にも移動しません。後にオンボーディングで新しいテナント API キーや新しい OAuth ペアが発行された場合は、ここのフィールドを更新し、接続を信頼する前に再テストしてください。

よくある質問#

テストが INVALID_TOKEN（401）で失敗する

確認のトークン側が拒否されました。トークン交換自体が client_id と client secret のペアを拒否したか、返されたトークンがテナントの Sync API に受け入れられなかったかのどちらかです。よくある原因は、コピーした値に余分なスペースが含まれていること、ある OAuth ペアの secret を別のペアの ID と組み合わせたこと、または environment の単語によって、ペアが発行された環境とは別の Sage トークンアドレスへ交換が送られたことです。

同じオンボーディング資料一式から、余分なスペースなしで client_id と client secret をコピーし直し、environment がそのペアの発行先テナントと一致することを確認してください。本番テナントは production、テストテナントは test です。audience を入力した場合は、オンボーディング文書で必要な場合を除き削除して、再テストしてください。

テストが MISSING_SCOPE（403）で失敗する

トークンは受け入れられましたが、テナント API キーに、folder フィールドに記された folder への権限がありません。リクエストはテナントの Sync API に到達しています。制限しているのはアドレスでも OAuth ペアでもなく、キー自体です。

Sage X3 管理者に、そのテナント API キーへこの folder へのアクセス権を付与してもらうか、その folder をカバーするキーを発行してもらってください。その際に folder 名も確認し、更新されたキーで再テストしてください。

テストが NOT_FOUND（404）で失敗する

folder フィールドに記された folder が、このテナントで Sync API に対して有効化されていないか、その名前がそこの folder と一致していません。folder 名は大文字小文字を区別するため、正しい名前でも表記が違えば別の folder として扱われます。

folder の値をオンボーディング資料一式と 1 文字ずつ、大文字も含めて比較してください。表記が完全に一致している場合は、Sage X3 管理者にその folder を Sync API 向けに有効化してもらい、再テストしてください。

テストが MISSING_TENANT_BASE_URL、MISSING_FOLDER、MISSING_TENANT_API_KEY、MISSING_CLIENT_ID、MISSING_CLIENT_SECRET で止まる

結果には、空になっているフィールドが正確に表示されます。テストはまずフィールドを確認し、5 つすべてが揃うまで何も送信しません。folder の確認にはトークンと API キーが両方必要だからです。

オンボーディング資料一式から、結果に表示されたフィールド（ベース URL、folder、テナント API キー、OAuth client ID、OAuth client secret）を入力し、保存して再テストしてください。不足の結果が出なくなるまで繰り返してください。

environment にサーバーアドレスや完全な URL を入力してテストが失敗する

environment はアドレスのフィールドではありません。2 つの文字通りの単語のどちらかだけを受け付け、その単語によってテストが使う Sage のトークンアドレスが選択されます。それ以外の内容を入れると、トークン交換が間違った場所、または使えない場所へ送られます。

environment の値を 1 単語に置き換えてください。この接続が本番テナント用なら production、テストテナント用なら test です。サーバーアドレスは代わりに tenant_base_url に入力し、再テストしてください。

テストは合格したが、注文・在庫・顧客が同期されない

これは値の入力ミスではなく、この接続の現在の範囲です。テストは、トークン交換と folder の確認が機能することだけを証明します。データの移動はまだこの接続の一部ではありません。Sync API はテーブル単位であり、folder の注文・在庫・顧客のテーブルと列は、導入環境について folder のメタデータでまず確認する必要があるためです。

テスト合格は、この folder について接続が確認済みであるとして扱い、注文・在庫・顧客の作業は当面 Sage X3 自体で続けてください。導入環境向けにデータ接続が準備される際は、この確認済みの値から開始します。認証情報を集め直す必要はありません。