linkfox-amazon-store-fulfillment-inbound

Amazon ストアの Fulfillment Inbound

この Skill では、Amazon Fulfillment Inbound v2024-03-20 の 45 個の operation と、新しいフローと併用する必要がある 6 個の v0 クエリ／ドキュメント operation を扱います。すべてのリクエストで、引き続き Amazon Store シリーズの本番経路 POST /spApi/developerProxy を使用します。サーバー側で sellerId + region によって認可情報を解決します。

前提条件（必ず先にお読みください）

1. この Skill は linkfox-amazon-store-auth に依存します。まず python scripts/check_auth_dependency.py を実行してください。exit code が 42 で、stderr に DEPENDENCY_MISSING: が含まれている場合は、先にその依存関係をインストールまたは読み込んでください。
2. auth Skill で店舗を選択し、sellerId と region を取得してください。region に指定できるのは NA、EU、FE のみです。
3. amzAccessToken、accessToken、refreshToken は受け取り、保存、転送しないでください。呼び出し元が Amazon の path、method、またはゲートウェイの queryString を上書きできないようにしてください。
4. タスクに対応するグループのドキュメントを先にお読みください。完全な仕様は references/api.md を参照してください。

呼び出し方法

• 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-inbound-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリ、<session> は環境変数 SESSION_ID から取得します。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が 8 KB 以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が 8 KB を超える場合：ファイルに保存した後、stdout には要約（トップレベルのフィールド、一般的な件数、最も長いリストフィールドの長さと先頭 3 件のサンプル）のみを出力します
• --inline を付けると、ファイルにも保存したうえで stdout に全量を出力します
• --no-cache を付けると、今回の読み取り／生成操作でゲートウェイにアクセスします。ユーザーが更新を求めた場合、または外部の状態変化が確認された場合にのみ使用してください

データの読み取りに関する推奨事項：まず要約を確認し、それで十分か判断してください。具体的なフィールドが必要な場合は、保存された JSON ファイルから jq または ConvertFrom-Json を使って必要なデータだけを抽出し、JSON 全体がコンテキストに入らないようにしてください。

動作方式

公開スクリプトはそれぞれ 1 つの固定 operation を表し、1 回の実行でゲートウェイを呼び出す回数は最大 1 回です。共通実行器は次を担当します。

• 共通フィールド、path/query/body、列挙値、ページネーション上限、重要なネスト構造の制約を検証します。
• path segment と query パラメーターをパーセントエンコードします。
• v0 CLI の lowerCamelCase パラメーターを、Amazon が要求する PascalCase の wire 名にマッピングします。
• 200/201/202/204 の成功レスポンスを識別し、JSON を解析します。
• 非同期レスポンスでは明示的な nextAction を返しますが、自動でポーリングは行いません。
• 完全なレスポンスを保存し、レスポンスが大きい場合は stdout に要約のみを表示します。

呼び出し形式：

python scripts/<operation_script>.py '<JSON parameters>' [--inline] [--no-cache]

共通パラメーター：

パラメーター	必須	説明
sellerId	はい	認可済み Seller ID
region	はい	NA ／ EU ／ FE
path/query パラメーター	条件付き	各 operation のドキュメントに記載されている lowerCamelCase 名を使用します
requestBody	条件付き	Amazon JSON body。このオブジェクトを明示的に渡すことを推奨します。body のフィールドをトップレベルに置く形式にも対応しています
confirmWrite	書き込み操作では必須	対象と選択内容をユーザーが明確に確認した後、ブール値 true を渡します。確定的な書き込み操作 8 件では、この値がない場合、ゲートウェイを呼び出す前にスクリプトが拒否します
skipDepCheck	いいえ	ローカルでのデバッグ時のみ使用します

例：

python scripts/get_inbound_plan.py '{"sellerId":"A1...","region":"NA","inboundPlanId":"wf12345678-1234-1234-1234-123456789012"}'

python scripts/create_inbound_plan.py '{"sellerId":"A1...","region":"NA","requestBody":{"destinationMarketplaces":["ATVPDKIKX0DER"],"items":[{"labelOwner":"AMAZON","msku":"SKU-1","prepOwner":"SELLER","quantity":10}],"sourceAddress":{"name":"Warehouse","addressLine1":"1 Main St","city":"Seattle","countryCode":"US","phoneNumber":"+1-206-555-0100","postalCode":"98101","stateOrProvinceCode":"WA"}}}'

python scripts/get_labels.py '{"sellerId":"A1...","region":"NA","shipmentConfirmationId":"FBA...","pageType":"PackageLabel_Letter_2","labelType":"UNIQUE"}'

operation の選択

グループ	用途	詳細なパラメーターとスクリプト
Inbound Plans	プランの作成、読み取り、キャンセル、名前変更、内容の確認	inbound-plans.md
Packing	梱包プランの生成／確認、箱の仕様の送信、packing group の確認	packing.md
Placement	配置プランの生成、一覧表示、確認	placement.md
Shipments	貨物、箱／商品／パレット、名称と住所、追跡情報の読み取り	shipments.md
Content Updates	作成済みの貨物内容の変更をプレビューして確認	shipment-content-updates.md
Delivery	delivery window と delivery challan	delivery-windows-and-documents.md
Self-Ship	India の自社配送用予約枠と予約	self-ship-appointments.md
Transportation	輸送プランの生成、比較、確認	transportation.md
Prep / Compliance / Labels	前処理、コンプライアンス、商品ラベル	prep-compliance-labels.md
Async Status	operationId の実行状況の確認	asynchronous-operations.md
Retained v0	prep instructions、箱ラベル、BOL、旧貨物の照会	legacy-v0.md

执行规则

1. 先确认当前工作流阶段及已有 ID；ID 的来源和跨版本映射见 references/identifiers.md。已有 plan/shipment 时优先只读恢复，不重复创建。
2. 写操作前确认用户意图和目标店铺。以下 8 个确定性提交操作必须在执行前向用户展示关键选择并取得明确确认：cancelInboundPlan、confirmPackingOption、confirmPlacementOption、confirmShipmentContentUpdatePreview、confirmDeliveryWindowOptions、cancelSelfShipAppointment、scheduleSelfShipAppointment、confirmTransportationOptions。
3. confirmTransportationOptions 可能接受运输费用；确认前展示每个 shipment 的 option、费用、币种、时效与 expiration。不得替用户默认选择收费项。
4. 19 个异步发起 operation 返回 operationId 后，只调用 get_inbound_operation_status.py 查询。IN_PROGRESS 时停止并告知稍后再查；FAILED 时展示 operationProblems，不得进入下游写步骤；仅 SUCCESS 可继续。
5. 脚本层不自动翻页、轮询、换参数试探或重放 POST/PUT。现有网关仅在识别到 token 过期时会刷新 token 并透明重试一次；429/500/503 或超时造成结果不确定时，优先通过 status/read operation 恢复状态。
6. updateInboundPlanName、updateShipmentName 的 204 空 body 是成功，不当作解析失败。
7. getLabels / getBillOfLading 必须使用 getShipment 返回的 shipmentConfirmationId；脚本同时接受该别名。下载 URL 可能很快过期，应在取得后立即下载，不要长期保存 URL。

完整标准路径、Pack Later、India、自有承运人和 shipment content update 流程见 references/workflows.md。市场限制见 references/marketplace-constraints.md。

输出与错误处理

• 完整响应保存到 linkfox/<YYYY-MM-DD>/<session>/data/linkfox-amazon-store-fulfillment-inbound-<timestamp>.json；stdout 会打印实际路径。
• 响应不超过 8 KB 时打印完整 JSON；更大时打印摘要；--inline 强制打印完整 JSON。
• 始终先判断 developerProxy.errcode，再判断 httpStatus，最后读取 operation 结果字段。
• 401/402、API Key、授权、算力或余额问题按 references/onboarding.md 处理。
• Amazon 返回 400/403/404/409/413/415/422 时，修正输入或流程状态后由用户决定是否再次调用。

参考路由

• 字段、响应、分页、错误语义：读 references/api.md。
• 业务流程选择：读 references/workflows.md。
• ID 产生和 v2024/v0 映射：读 references/identifiers.md。
• 国家/市场差异：读 references/marketplace-constraints.md。
• 某个 operation 的 method/path/body/script：只读对应的 references/apis/*.md 分组文档。

问题反馈使用 skillName: linkfox-amazon-store-fulfillment-inbound，并附脱敏后的 operation、关联 ID 与 developerProxy 响应。

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