エラーレスポンス#

検証エラーでは、次の形式が使用される場合があります。

{
  "message": ["shopId should not be empty"],
  "error": "Bad Request",
  "statusCode": 400
}

message のテキストは変わる場合があります。プログラムの判定処理には、HTTP ステータスコードと、仕様に記載されたレスポンスフィールドを使用してください。

再試行と復旧の指針#

• ジョブが pending または running の間は、2～5 秒ごとにポーリングしてください。
• 429、500、502、503 のレスポンスには、待機時間を指数関数的に延ばしてランダムな揺らぎを加え、再試行回数に上限を設定してください。
• 400、401、403 のレスポンスは、リクエストまたは認証情報を修正せずに自動再試行しないでください。
• 409 の後は、実行中のジョブが completed または failed に達するまで待ってください。
• レスポンスを受け取る前に送信がタイムアウトした場合は、バッチを再送信する前にステータスエンドポイントを照会してください。
• インポートは作成または更新の動作を行うため、同じ商品を同じ SKU で安全に再試行できます。
• 商品ごとの失敗があるジョブが完了した後は、失敗した商品だけを含む新しいバッチを送信してください。
• ジョブ全体の失敗が起きても、successCount に数えられた商品はすでに更新されている場合があります。同じ SKUs で元のバッチを安全に再送信できます。
• リクエストが 503 を返しても、削除はすでに実行されている場合があります。同じ削除リクエストを安全に再試行できます。

ステータスエンドポイントは、実行中または最新のジョブを追跡するためのもので、恒久的なインポート履歴用ではありません。照合とサポートのため、送信したバッチ、jobId、ステータスのレスポンス、最終結果を自身のシステムに保存してください。

本番運用チェックリスト#

• Client Secret はシークレット管理サービス、または保護されたサーバー環境に保存してください。
• 各商品に固定の一意な SKU を使用してください。
• リクエストごとの商品数を 500 件以下にしてください。
• 画像の URLs が公開アクセス可能であり、処理中も利用可能な状態を保つことを確認してください。
• 画像の前処理が必要で、画像ごとの処理料金 1 クレジットを了承する場合にのみ、processImages: true を明示的に設定してください。それ以外は省略するか false に設定してください。
• 床材画像の分割を有効にするには、processImages と processFloorImages の両方を true に設定してください。
• すべての商品に name、imageUrl、productUrl、width、height、対応する productType を指定してください。
• status を指定する場合は、active、inactive、out_of_stock、invalid のいずれかに設定してください。
• 寸法は対応する単位付きの正の値として送信してください。単位を省略するとインチを使用します。保存時に値はインチに統一されます。
• 返された jobId を保存し、後続のステータスレスポンスと比較してください。
• completed で failedCount > 0 の場合は部分的な成功として扱ってください。
• 上限なしのカタログを要求せず、商品一覧をページ単位で取得してください。
• 削除操作では productId または sku のどちらか一方だけを指定してください。
• 待機時間を指数関数的に延ばし、ランダムな揺らぎを加えた、上限のある再試行を実装してください。

認証情報、導入時に提供される値、商品タイプの対応付け、継続する連携の問題については、Ideal House の連携担当者に連絡してください。