linkfox-amazon-store-fulfillment-outbound

Amazon 店舗 Fulfillment Outbound

Fulfillment Outbound v2026-07-04 の Amazon Multi-Channel Fulfillment ワークフローには、この Skill を使用してください。Amazon の現行 Outbound モデルの 9 つの操作すべてに加え、Invoices v2026-06-25 の概要ページに関連付けられた getInvoiceHeaders 操作も利用できます。既存の本番環境向け linkfox-amazon-store-fba および linkfox-amazon-store-external-fulfillment の実装には変更を加えません。

前提条件

1. linkfox-amazon-store-auth が必要です。python scripts/check_auth_dependency.py を実行してください。終了コード 42 は、先に依存関係をインストールするか読み込む必要があることを示します。
2. 認証済みの店舗を 1 つ選択し、その sellerId と region を取得します。NA、EU、FE のみを受け付けます。
3. amzAccessToken、accessToken、refreshToken は受け付けたり転送したりしないでください。サーバーは sellerId + region から認証情報を解決します。
4. 操作の仕様については references/api.md を、作成、更新、キャンセルの操作を行う前に references/workflows.md を参照してください。
5. ユーザーの明示的な確認後、createOrder、updateOrder、cancelOrder、updateOrderStatus、updatePackage にブール値の confirmWrite: true を渡してください。ラッパーはこの指定がない書き込みを拒否します。
6. Amazon がマルチテナントサービス識別子を割り当てている場合は、トップレベルの fulfillmentServiceId（1～40 文字）としてのみ渡してください。プロキシはこれを x-amzn-fulfillment-service-id にマッピングします。生のヘッダー名をクエリや本文に入れないでください。

呼び出し方法

• API エンドポイント：POST /spApi/developerProxy（パラメーター／レスポンス／エラーコードの詳細は references/api.md を参照）
• Python スクリプト：python scripts/<operation_script>.py '<JSON 参数>' [--inline] [--no-cache]
• 呼び出し制約：このツールは Amazon Store Skill の共通無料設定を引き継ぎます。同一セッション内で同じパラメーターの組み合わせによる呼び出しは、デフォルトで 1 回のみです。スクリプトには 24h のローカルキャッシュがあります。失敗や空の結果が返っても、パラメーターの変更、ページ送り、連続した試行を自動で行ってはいけません。呼び出しを続ける場合は、先にユーザーの同意を得てください。

出力ポリシー（スクリプトのデフォルト動作）：

• 常に完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-fulfillment-outbound-<timestamp>.json に書き込みます（<session> は SESSION_ID から取得します。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存し、stdout には要約のみを出力します（トップレベルのフィールド、一般的な件数、最も長いリストフィールドの長さと先頭 3 件のサンプル）
• --inline を追加すると、stdout にすべて出力します（同様にファイルにも保存します）
• --no-cache を追加すると、今回の読み取り／プレビュー操作でゲートウェイにアクセスします。ユーザーが更新を求めた場合、または外部の状態変化を確認済みの場合にのみ使用してください

データ読み取りの推奨事項：まず要約を確認してください。具体的なフィールドが必要な場合は、保存したファイルから jq または ConvertFrom-Json を使って必要な項目を抽出してください。

操作ガイド

Stage	Operation	Script	Availability
見積もり	getOffers	get_offers.py	本番
プレビュー	getOrderPreview	get_order_preview.py	本番
作成	createOrder	create_order.py	本番
読み取り	getOrder	get_order.py	本番
一覧表示	listOrders	list_orders.py	本番
保留解除／更新	updateOrder	update_order.py	本番
キャンセル	cancelOrder	cancel_order.py	本番
注文ステータスのシミュレーション	updateOrderStatus	update_order_status.py	Amazon の動的サンドボックスのみ
パッケージステータスのシミュレーション	updatePackage	update_package.py	Amazon の動的サンドボックスのみ
請求書ヘッダーの一覧表示	getInvoiceHeaders	get_invoice_headers.py	本番、Invoices v2026-06-25

ワークフロールール

1. 複数SKUの配送オプションと有効期限にはgetOffersを使用し、予定されている出荷、手数料、制約、履行可能性にはgetOrderPreviewを使用します。
2. createOrderを実行する前に、選択した店舗、配送先、明細、サービス階層、手数料、保留／出荷のアクション、orderIdを提示します。
3. orderIdとすべてのlineItemIdは、販売者が管理する冪等性識別子として扱います。タイムアウトが不確かな場合、代わりのIDを決して作成しないでください。
4. createOrderの応答はHTTP 200または202の場合があります。202の場合は、返された／リクエストしたorderIdを使ってgetOrderを実行します。自動的にポーリングしないでください。
5. updateOrderは、現在は保留／出荷のアクションである、サポート対象のフルフィルメント設定を更新する場合にのみ使用します。保留中の注文をリリースする前に確認を得てください。
6. cancelOrderを実行する前に確認を得てください。Amazonはキャンセルがまだ可能な場合にのみフルフィルメントを停止します。202をキャンセル完了として提示しないでください。
7. パッケージと追跡の詳細が必要な場合は、getOrderまたはlistOrdersにshipments: "INCLUDE"を追加します。
8. 429、500、503、またはタイムアウトの後に、POST／PUTを自動的に再実行しないでください。可能な場合はgetOrderで復旧します。
9. ヘッダーレベルの請求書検索にはgetInvoiceHeadersのみを使用します。marketplaceIdを必須とし、発行日の範囲は両方を指定するか、どちらも指定しないでください。範囲は90日以内に収め、ユーザーの承認後にのみnextTokenでページングします。

重要な制限事項

• AmazonではupdateOrderStatusとupdatePackageにx-amzn-api-sandbox-only: trueが指定されています。既存のFBAスキルと同様に、これらのラッパーは他のすべての操作と同じ/spApi/developerProxyリクエスト形式を使用し、別個のsandbox制御フィールドを受け付けたり送信したりしません。サンドボックスのテストデータでのみ使用してください。利用可否は、統合ゲートウェイ／上流ルートによって異なります。
• オプションのx-amzn-fulfillment-service-idマルチテナントヘッダーは、型付きのトップレベルfulfillmentServiceIdパラメーターを通じてのみ公開されます。生のヘッダー名、ネストされた別名、空白値、40文字を超える値、改行文字は、ゲートウェイを呼び出す前に拒否されます。
• AmazonのOutbound概要にあるロール一覧にはgetInvoiceHeadersが記載されていますが、Referenceのパスは/finances/invoices/2026-06-25/invoicesです。このスキルでは、関連する請求書操作として明示的にラベル付けして公開しています。これは9つのOutbound OpenAPI操作には含まれず、fulfillmentServiceIdも受け付けません。
• 従来のv2020-07-01の返品、機能、パッケージ追跡操作は本番環境のFBAスキルに残されており、この現行バージョンのスキルには含まれていません。移行する場合はreferences/migration.mdをお読みください。

表示ルール

• 内部ツール名やアクセストークンを公開せずに、Amazonのデータと識別子を提示します。
• 操作の成功と業務上の完了を区別します。ゲートウェイのerrcode、AmazonのhttpStatus、注文のstatus、制約、次のアクションを提示します。
• オファーとプレビューでは、有効期限、サービス階層、配送期間、通貨、価格、商品制約をまとめて提示します。
• 注文では、orderId、ステータス、明細、出荷、パッケージ、追跡、配達証明、持ち込み／ロッカーの詳細、商品単位の識別子、ページネーショントークンを、存在する場合にのみ提示します。

ユーザーの依頼

依頼：「これらのAmazon SKUについて、この郵便番号へのMCF配送オプションを確認してください。」

対応：getOffersを使用します。注文は作成しないでください。

依頼：「このMCF注文をプレビューしてから作成してください。」

対応：getOrderPreviewを実行し、制約と手数料を提示して確認を得た後、createOrderを1回実行します。

依頼：「MCF注文を追跡してください。」

対応：shipments: "INCLUDE"を指定してgetOrderを実行します。従来の追跡操作は呼び出さないでください。

フィードバック

問題を報告する際は、skillName: linkfox-amazon-store-fulfillment-outbound、操作、マスキング済みID、解決済みパス、ゲートウェイのステータス、Amazonの応答概要を含めてください。認証情報は決して含めないでください。

Amazon SP-API 接口保护与重试指引

同一店铺连续收到 Amazon SP-API 的 400、403、404 或 429 时，网关会返回 450、453、454 或 459 并短暂冷却。这些自定义状态码不是 Amazon 原生状态，也不表示封号；目的是避免持续异常或高频调用扩大店铺风险。

状态与 message	范围	触发与冷却	处理
450：400，请求异常，请优化您的参数	店铺+接口	60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：20 分钟	停止原参数重试，检查必填字段、marketplace、ID、日期和请求体
453：403，店铺未授权，请先授权	店铺全部接口	60 秒内超过 2 次：5 分钟；10 分钟内超过 4 次：30 分钟	停止该店铺调用，检查授权、权限、店铺归属和区域
454：404，资源不存在，请优化您的参数	店铺+接口	60 秒内超过 3 次：5 分钟；10 分钟内超过 4 次：30 分钟	确认资源 ID、所属店铺/站点、资源状态和接口路径
459：429限流中，请降低频率	店铺+接口	首次：15 秒；2 分钟内超过 2 次：30 秒；3 分钟内超过 4 次：2 分钟	降低并发、分页和轮询频率并逐级退避

• 立即停止自动或并发重试，不得通过换脚本或重复创建任务绕过保护；优先遵循 retryAfter、blockedUntil，没有时按表中时长说明。
• 450/453/454 必须先修正参数、授权或资源标识，冷却后最多谨慎重试一次；再次触发则停止调用。453 期间停止该店铺全部 SP-API。
• 保留已有 reportId、feedId 等任务 ID；写操作结果不确定时先查询状态，不直接重放。
• 向用户先说明店铺保护，再给原因、处理和等待时间。可回复：“为保护您的亚马逊店铺安全，检测到 Amazon SP-API 连续返回{原因}，当前已进入短暂保护。请先{处理动作}，预计{等待时间}后再试；这不代表封号，也不是套餐或算力限制。”不要只说“LinkFox 限流”或“服务器繁忙”。

算力消耗规则

不消耗算力（以网关实际计费为准）。

---

更多跨境 Skill：LinkFox Skills