| name | linkfox-amazon-store-fulfillment-inbound |
| description | 亚马逊 FBA 入仓与 Fulfillment Inbound SP-API 能力，经 LinkFox /spApi/developerProxy 管理 inbound plan、装箱、placement、shipment、shipment content update、delivery window、自配送预约、运输方案、合规、预处理、标签及 BOL。用户提到 createInboundPlan、packing option、placement option、transportation option、FBA 入库计划、货件箱唛、入仓标签、送仓预约、shipmentConfirmationId、Fulfillment Inbound API 或 v2024-03-20/v0 时触发。 |
Amazon 店铺 Fulfillment Inbound
本 Skill 覆盖 Amazon Fulfillment Inbound v2024-03-20 的 45 个 operation，以及仍需配合新流程使用的 6 个 v0 查询/文档 operation。所有请求继续使用 Amazon Store 系列的生产链路：POST /spApi/developerProxy，由服务端通过 sellerId + region 解析授权。
Prerequisites（必须先读）
- 本 Skill 依赖
linkfox-amazon-store-auth。先运行 python scripts/check_auth_dependency.py；若 exit code 为 42 且 stderr 含 DEPENDENCY_MISSING:，先安装或加载该依赖。
- 通过 auth Skill 选定店铺，取得
sellerId 与 region。region 仅允许 NA、EU、FE。
- 不接收、存储或透传
amzAccessToken、accessToken、refreshToken。不要让调用方覆盖 Amazon path、method 或网关 queryString。
- 先读与任务匹配的分组文档；完整契约入口见 references/api.md。
调用方式
- API 端点：
POST /spApi/developerProxy（完整参数/响应/错误码见 references/api.md）
- Python 脚本：
python scripts/<operation_script>.py '<JSON 参数>' [--inline] [--no-cache]
- 调用约束：本工具沿用 Amazon Store Skill 的统一免费配置；同一会话同一参数组合默认只调用一次，脚本带 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 强制本次读/生成操作访问网关；只在用户要求刷新或已确认外部状态变化时使用
读数据建议：先看摘要判断是否足够；需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 JSON 文件按需抽取，避免整份 JSON 进入上下文。
工作方式
每个公开脚本只代表一个固定 operation，并且一次执行最多调用一次网关。统一执行器负责：
- 校验公共字段、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
执行规则
- 先确认当前工作流阶段及已有 ID；ID 的来源和跨版本映射见 references/identifiers.md。已有 plan/shipment 时优先只读恢复，不重复创建。
- 写操作前确认用户意图和目标店铺。以下 8 个确定性提交操作必须在执行前向用户展示关键选择并取得明确确认：
cancelInboundPlan、confirmPackingOption、confirmPlacementOption、confirmShipmentContentUpdatePreview、confirmDeliveryWindowOptions、cancelSelfShipAppointment、scheduleSelfShipAppointment、confirmTransportationOptions。
confirmTransportationOptions 可能接受运输费用；确认前展示每个 shipment 的 option、费用、币种、时效与 expiration。不得替用户默认选择收费项。- 19 个异步发起 operation 返回
operationId 后，只调用 get_inbound_operation_status.py 查询。IN_PROGRESS 时停止并告知稍后再查；FAILED 时展示 operationProblems，不得进入下游写步骤；仅 SUCCESS 可继续。
- 脚本层不自动翻页、轮询、换参数试探或重放 POST/PUT。现有网关仅在识别到 token 过期时会刷新 token 并透明重试一次；429/500/503 或超时造成结果不确定时，优先通过 status/read operation 恢复状态。
updateInboundPlanName、updateShipmentName 的 204 空 body 是成功，不当作解析失败。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 时，修正输入或流程状态后由用户决定是否再次调用。
参考路由
问题反馈使用 skillName: linkfox-amazon-store-fulfillment-inbound，并附脱敏后的 operation、关联 ID 与 developerProxy 响应。
积分消耗规则
不消耗积分（以网关实际计费为准）。
更多跨境 Skill：LinkFox Skills
