Amazon SP-API

Amazon SP-API 是一个电商插件，以插件能力的形式出现在指令树「扩展能力」中。安装或内置加载后，可把插件里的节点拖到工作流画布使用。

插件标识：rpa-plugin-amazon-spapi
插件分类：电商插件
节点数量：6 个

先选使用方式

方式	怎么用	适合人群
可视化编排（推荐）	在「扩展能力」中找到 Amazon SP-API，拖入需要的节点并填写参数	大多数用户，适合按表单配置插件能力
代码编排（执行指令 XML）	通过「执行指令（XML）」调用节点的 `type` 与参数	需要动态拼装、循环调用或批量处理的用户

什么时候用？

Amazon Selling Partner API（SP-API）跨境卖家插件：6 个核心原子节点覆盖卖家自检 / 订单分页查询 / 订单详情合并行项目 / FBA 库存查询 / Listings PATCH 改价改库 / 异步报表三步串行。LWA refresh_token 鉴权（2023-11 起不再需要 AWS Sigv4）+ region 路由（NA/EU/FE）+ per-endpoint token bucket（防 429 雪崩）+ access_token 401 自动 refresh 重试。
需要在自动化流程中复用该插件提供的读取、写入、同步或处理能力。

使用前确认

需要先配置连接：amazon-spapi。
涉及订单、商品、库存、价格或平台数据时，建议先用测试数据跑通，再用于正式数据。
建议先运行连通性、查询或只读节点，确认权限和参数正确后再执行写入类节点。

连接配置

连接类型	名称	说明
`amazon-spapi`	amazon-spapi	Amazon SP-API 卖家凭据：LWA Client + Refresh Token + region 路由

节点总览

节点名称	节点标识	说明
连通性测试	`AmazonSPAPIPing`	调一次 /sellers/v1/marketplaceParticipations 同时验证 LWA token + region + 卖家授权
查询订单列表	`ListAmazonOrders`	GET /orders/v0/orders 按 marketplace + 时间窗 + 状态分页查询。⚠️ rate limit 极低（1 req/min），默认 maxPages=5
取订单详情（含行项目）	`GetAmazonOrder`	GET /orders/v0/orders/{id} + 自动合并 orderItems（可关闭）
查询 FBA 库存	`ListAmazonInventory`	GET /fba/inventory/v1/summaries 单 marketplace 库存查询（支持 SKU 过滤）
更新商品（改价 / 改库存 / 改属性）	`UpdateAmazonListing`	PATCH /listings/2021-08-01/items/{sellerId}/{sku}。支持「简化」(amount+currency 改价 / quantity 改库存) 和「原生 JSON Patch」两种用法注意：会直接影响 Amazon 线上 Listing 的价格、库存或属性；建议先在测试 SKU/单站点验证，并确认 marketplace/productType 无误。
异步报表（创建 + 等待 + 取下载链接）	`RequestAmazonReport`	三步串行：1) 创建报表 2) 轮询至 DONE 3) 取下载 URL。适合订单 / Listings / 广告报表等批量导出（实时接口限流太低跑不动的场景）

节点参数与输出

连通性测试

节点标识： AmazonSPAPIPing
节点说明： 调一次 /sellers/v1/marketplaceParticipations 同时验证 LWA token + region + 卖家授权
XML 示例：

<AmazonSPAPIPing connectionId="" outKey="pingResult" />

界面名称	代码属性名	类型	必填	默认值
Amazon SP-API 连接	`connectionId`	connection	是	-
输出变量名	`outKey`	output	否	`pingResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`pingResult`	object	{ ok:true, data:{ connected:true, region:‘NA’, marketplaces:[{ id, name, countryCode, currency, isParticipating }] } }

查询订单列表

节点标识： ListAmazonOrders
节点说明： GET /orders/v0/orders 按 marketplace + 时间窗 + 状态分页查询。⚠️ rate limit 极低（1 req/min），默认 maxPages=5
XML 示例：

<ListAmazonOrders connectionId="" marketplaceIds="" outKey="orders" />

界面名称	代码属性名	类型	必填	默认值	说明
Amazon SP-API 连接	`connectionId`	connection	是	-
Marketplace IDs	`marketplaceIds`	string	是	-	逗号分隔或 JSON 数组；US=ATVPDKIKX0DER, UK=A1F83G8C2ARO7P, DE=A1PA6795UKMFR9, JP=A1VC38T7YXB528
创建时间≥（ISO8601）	`createdAfter`	string	否	-	2026-05-01T00:00:00Z
创建时间<（ISO8601）	`createdBefore`	string	否	-
更新时间≥（ISO8601）	`lastUpdatedAfter`	string	否	-
更新时间<（ISO8601）	`lastUpdatedBefore`	string	否	-
订单状态过滤（逗号分隔）	`orderStatuses`	string	否	-	可选值：PendingAvailability / Pending / Unshipped / PartiallyShipped / Shipped / Canceled / Unfulfillable
履约渠道	`fulfillmentChannels`	string	否	-	AFN = 亚马逊物流（FBA）；MFN = 自发货
买家邮箱（高级，精确匹配）	`buyerEmail`	string	否	-
每页条数	`pageSize`	number	否	`100`	上限 100
自动翻页	`autoPaginate`	boolean	否	`true`
最多翻页数	`maxPages`	number	否	`5`	⚠️ list orders 限流 1 req/min；翻 5 页约需 5 min
记录数上限	`maxRecords`	number	否	-
输出变量名	`outKey`	output	否	`orders`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`orders`	object	{ ok:true, data:{ orders:[{…原始结构}], total, hasMore, nextToken? } }

取订单详情（含行项目）

节点标识： GetAmazonOrder
节点说明： GET /orders/v0/orders/{id} + 自动合并 orderItems（可关闭）
XML 示例：

<GetAmazonOrder connectionId="" orderId="" outKey="orderDetail" />

界面名称	代码属性名	类型	必填	默认值	说明
Amazon SP-API 连接	`connectionId`	connection	是	-
订单 ID	`orderId`	string	是	-	123-1234567-1234567
同时拉行项目	`includeItems`	boolean	否	`true`	默认 true，会自动调 /orderItems 接口（含翻页）
行项目最多翻页数	`itemMaxPages`	number	否	`20`	1-100；翻满后仍有 NextToken 时返回 hasMoreItems=true（不静默截断）。每页 ~20 SKU，默认 20 页 = 400 SKU
行项目续翻 Token	`itemPageStart`	string	否	-	上次返回的 itemsNextToken；用于从中断位置继续拉 orderItems。首次调用留空
输出变量名	`outKey`	output	否	`orderDetail`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`orderDetail`	object	{ ok:true, data:{ order:{…}, items:[…], hasMoreItems, itemsNextToken?, itemPagesFetched } }

查询 FBA 库存

节点标识： ListAmazonInventory
节点说明： GET /fba/inventory/v1/summaries 单 marketplace 库存查询（支持 SKU 过滤）
XML 示例：

<ListAmazonInventory connectionId="" marketplaceId="" outKey="inventory" />

界面名称	代码属性名	类型	必填	默认值	说明
Amazon SP-API 连接	`connectionId`	connection	是	-
Marketplace ID	`marketplaceId`	string	是	-	本接口必须单 marketplace（不支持多个）
Seller SKU 过滤	`sellerSkus`	string	否	-	最多 50 个；逗号分隔或 JSON 数组。不传则拉全量
包含分仓详情	`details`	boolean	否	-	勾选返回每个 FC 仓位的明细（响应体大很多）
起始时间（ISO8601，可选）	`startDateTime`	string	否	-	只拉该时间后改动过库存的 SKU
自动翻页	`autoPaginate`	boolean	否	`true`
最多翻页数	`maxPages`	number	否	`200`
记录数上限	`maxRecords`	number	否	`10000`
输出变量名	`outKey`	output	否	`inventory`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`inventory`	object	{ ok:true, data:{ inventorySummaries:[…], total, hasMore, nextToken?, granularityId } }

更新商品（改价 / 改库存 / 改属性）

节点标识： UpdateAmazonListing
节点说明： PATCH /listings/2021-08-01/items/{sellerId}/{sku}。支持「简化」(amount+currency 改价 / quantity 改库存) 和「原生 JSON Patch」两种用法注意：会直接影响 Amazon 线上 Listing 的价格、库存或属性；建议先在测试 SKU/单站点验证，并确认 marketplace/productType 无误。
XML 示例：

<UpdateAmazonListing connectionId="" sku="" marketplaceIds="" productType="PRODUCT" outKey="listingResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Amazon SP-API 连接	`connectionId`	connection	是	-
Seller SKU	`sku`	string	是	-
Marketplace IDs（逗号分隔）	`marketplaceIds`	string	是	-	ATVPDKIKX0DER
Product Type	`productType`	string	是	-	Amazon 商品类型，如 PRODUCT / SHOES / GROCERY。可在 Listings Items API 文档查到完整列表
改价：金额（简化用法）	`amount`	string	否	-	19.99
改价：货币（ISO 4217）	`currency`	string	否	-	USD
改库存：数量（简化用法）	`quantity`	number	否	-
改库存：履约渠道	`fulfillmentChannel`	select	否	`DEFAULT`
原生 JSON Patch（高级，覆盖简化用法）	`patches`	textarea	否	-	RFC 7396 JSON Patch；传了则忽略 amount/quantity 简化字段
Issue 提示语言	`issueLocale`	string	否	`en_US`
输出变量名	`outKey`	output	否	`listingResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`listingResult`	object	{ ok:true, data:{ sku, submissionId, status, issues:[{code,message,severity}], raw } }

异步报表（创建 + 等待 + 取下载链接）

节点标识： RequestAmazonReport
节点说明： 三步串行：1) 创建报表 2) 轮询至 DONE 3) 取下载 URL。适合订单 / Listings / 广告报表等批量导出（实时接口限流太低跑不动的场景）
XML 示例：

<RequestAmazonReport connectionId="" reportType="GET_FLAT_FILE_ORDERS_DATA" marketplaceIds="" outKey="reportResult" />

界面名称	代码属性名	类型	必填	默认值	说明
Amazon SP-API 连接	`connectionId`	connection	是	-
报表类型	`reportType`	string	是	-	如 GET_FLAT_FILE_ORDERS_DATA（订单）/ GET_MERCHANT_LISTINGS_ALL_DATA（全店 Listings）/ GET_FBA_INVENTORY_PLANNING_DATA。完整列表见 Reports API 文档
Marketplace IDs（逗号分隔）	`marketplaceIds`	string	是	-
数据起始时间（ISO8601，可选）	`dataStartTime`	string	否	-
数据结束时间（ISO8601，可选）	`dataEndTime`	string	否	-
reportOptions（JSON 对象，可选）	`reportOptions`	textarea	否	-	部分 reportType 支持额外参数，如 reservation 报表的 startDate / endDate
等待报表完成	`waitUntilDone`	boolean	否	`true`	true（默认）：阻塞至 DONE 并返回下载 URL；false：立刻返回 reportId 让后续节点轮询
轮询间隔（秒）	`pollIntervalSec`	number	否	`30`	默认 30s；下限 5s
轮询超时（秒）	`pollTimeoutSec`	number	否	`900`	默认 15 min；上限 2h
输出变量名	`outKey`	output	否	`reportResult`
失败时抛错	`failOnError`	boolean	否	`true`

输出字段：

字段	类型	说明
`reportResult`	object	waitUntilDone=true：{ ok:true, data:{ reportId, processingStatus:‘DONE’, reportDocumentId, url, compressionAlgorithm?:‘GZIP’, completedAt } }；waitUntilDone=false：{ ok:true, data:{ reportId, processingStatus:‘IN_QUEUE’, hint } }

成功标准

节点运行状态为成功。
输出变量中包含预期字段，且可被下游节点引用。
对外部系统有写入动作的节点，目标系统中的数据状态与配置一致。

失败排查

现象 / 报错	可能原因	处理建议
找不到插件分组	插件未安装、未加载或当前端不是桌面客户端	在「扩展能力」中刷新/重新扫描插件，必要时重启客户端。
连接或鉴权失败	连接配置缺失、令牌过期或权限不足	重新配置连接，确认账号具备对应资源权限。
查询结果为空	筛选条件过窄、目标资源为空或页面状态不正确	放宽条件，检查资源 ID、日期范围和页面登录态。
写入类操作失败	参数格式不符合平台要求或目标资源不可写	先用少量测试数据验证，再检查必填字段、ID 和权限。

Amazon SP-API

先选使用方式

什么时候用？

使用前确认

连接配置

节点总览

节点参数与输出

连通性测试

查询订单列表

取订单详情（含行项目）

查询 FBA 库存

更新商品（改价 / 改库存 / 改属性）

异步报表（创建 + 等待 + 取下载链接）

成功标准

失败排查

相关说明