Amazon SP-API 接入指南：权限、数据流程与卖家上线验收清单

快速结论：先验证一条获得授权的数据流程，再扩大范围

先确定一项运营产出，找到支持它的 API 操作和版本，再申请必要权限。完成对应应用的注册与授权，在受控服务端建立连接，然后用指定卖家、指定站点的小范围数据验证结果。把“请求成功”“报表处理完成”和“下游数据验收通过”分开记录，不要合并成一个含糊的同步状态。

建议按六项标准判断接入质量：应用类型是否合适、权限是否准确、站点与版本范围是否清楚、数据是否完整、失败后能否恢复、交付是否有人负责。第一轮只做不改变商品、价格或订单的数据获取试点。确认系统能够发现缺失、在授权失效时停止，并且不会因重跑重复交付之后，再扩展用途。整体分工可结合面向 Amazon 卖家的 AI Agent 选型指南理解。

先选路线：手动导出、现成连接器还是自建接入

用一次手动导出把需求说清楚

如果团队还没有确定需要哪些列，立即开发 API 客户端往往为时过早。先准备一份已获授权的导出文件，让真正使用数据的人完成一次分析，记录卖家、站点、统计周期、行粒度，以及这份数据支持的业务决定。每周一次的选品讨论与订单履约流程，对时效、权限和失败恢复的要求并不相同。

任务偶发、产出尚未定型时，手动试点有助于明确需求。它的短板在于可重复性：需要有人取对文件、标明范围、发现遗漏。试点应沉淀成数据说明，而不是演变成个人账户之间长期传递、没人知道最新版本是哪份的表格链条。

购买连接器不等于把验收责任一起买走

当现成连接器有明确的接口覆盖、数据目标和刷新方式，而且与实际任务匹配时，可以评估采用。要求供应方说明具体支持哪个报表或操作、覆盖哪些站点、怎样展示错误、如何控制留存，以及能否导出数据。集成列表上出现 Amazon 标识，不代表你的账户一定能够获得某个字段。

卖家仍需了解申请了什么权限、数据将交给谁，以及重新授权、账户移除、部分同步和版本变化如何处理。给供应方的验收用例，应当与给内部开发团队的要求一致。购买软件可以减少开发工作，但不能替代对实际结果的核对。

自建接入必须有人长期维护

自建适合确实需要控制数据映射和下游行为的团队，但凭证、数据结构、重试逻辑与运行支持都需要负责人。评估时应把开发、托管、适用的平台或服务收费，以及持续维护工作一起算进去。旧教程中一句“免费调用”，不能作为当前应用类别的完整预算依据。

合理的演进顺序通常是：手动导出验证需求、脚本或连接器重复获取、人工核对分析，再考虑受限的 Agent 辅助执行。可靠的数据约定应先于智能分析。如果问题只是把已知格式的文件送入数据库，常规采集服务就可能足够，没有必要为搬运文件额外引入 Agent。

根据真实使用对象选择私有或公有应用

注册路径要与组织和用途一致

Amazon 要求先完成开发者注册，再注册应用。当前说明区分私有卖家应用、私有供应商应用和公有应用。其中，在 Seller Central 开发私有卖家应用要求使用专业销售账户，个人销售账户不适用于这一路径；注册说明还列出了主账户用户和相关政策要求。应核对自己组织对应的流程，不要直接照搬别人的账户配置。Amazon 开发者注册概览

先写清应用归谁所有、访问谁的数据、发生故障后由谁支持。为多个无关联卖家服务的机构，不应把面向单一组织的私有应用当成绕过公有应用流程的捷径。开发者注册、角色获批和卖家同意是不同环节，一个环节完成不能替代其他环节。

两类应用的授权与续期方式不同

左右滑动表格，查看完整内容。

上述区别依据 Amazon 的应用授权说明。这张表不能替代对注册和分发要求的检查。授权页面能打开、卖家也点过同意，不代表应用已经具备全部目标操作的访问权。

先把角色映射到操作，再申请权限

准备一份简短的访问清单，逐项列出业务目的、API 与版本、操作或报表类型、所需角色、账户范围和责任人。注册时对照当前角色映射核实。如果产出只需要汇总经营数据，就应追问为什么还需要买家级个人信息。

功能变化时也要重做这一检查。增加一列数据，可能改变权限要求，也可能让下游数据的敏感程度发生变化。新增访问范围应当作为明确的变更单独审阅，而不是在原有试点的授权说明之外悄悄扩张。

建立服务端授权，同时避免凭证泄露

卖家同意与运行时换取令牌是两件事

对于需要卖家授权的操作，应用使用授权获得的刷新令牌及客户端凭证，换取短期 LWA 访问令牌。Amazon 文档说明访问令牌有效期为一小时，并为 grantless 操作定义了不同的授权类型。Grantless 并不意味着可以任意读取卖家信息，实际连接应遵循对应操作的官方接入说明。

凭证交换应放在受控服务端。运营审核者需要看到连接状态和数据范围，不需要拿到客户端密钥或刷新令牌。日志应保留定位问题所需的请求上下文，同时排除令牌、个人信息和敏感下载链接。不要把生产凭证放进文章、共享截图，或能被浏览器访问的示例代码。

把续期失败和撤销授权纳入运行设计

令牌刷新失败时，系统应明确显示连接异常，而不是把旧报表包装成刚更新的数据。分别记录最近一次成功获取的时间和最近一次尝试运行的时间。为重新授权指定负责人，并说明权限恢复前哪些下游工作必须暂停。

账户退出或授权被撤销时，也要有可执行的处理路径：停止计划请求，并按照批准的数据处理规则管理已有数据。不能让 Agent 持续把最后一次成功快照当成当前状态。这些是需要安全负责人审阅的实施控制，并不表示任意一种存储方案都已满足 Amazon 的所有要求。

识别旧教程中的 IAM 和签名步骤

自 2023 年 10 月 2 日起，Amazon 已不再要求 SP-API 请求使用 AWS IAM 或 Signature Version 4。旧教程可能因此多出不再必要的注册或签名步骤。但这一变化没有取消 LWA 授权，也没有取消你自行使用其他 AWS 基础设施时所需的独立权限。Amazon 关于 IAM 与 SigV4 的变更公告

选择示例客户端前，核对它采用的认证假设与 API 模型是否仍然适用。第一次连接检查使用最小的不修改业务状态的请求即可。例如，目录查询成功，只能证明相应请求可用，不能顺带证明受限订单信息或另一类报表也能够访问。

明确站点、API 版本和下游数据约定

不能只记录一把密钥就认为范围明确

记录卖家上下文、区域端点、站点 ID、API 版本、操作和请求时间范围。同时约定输出的时区、涉及金额时的币种、实体标识与行粒度。其中有些属于接口参数，有些属于团队自己的下游数据约定，不能把它们写成适用于所有 SP-API 的统一请求结构。

空结果可能是真的没有数据，也可能是请求范围错了。先用正确来源和周期的小样本核对，再把“为空”解释成经营结论。即使最终报表会合并多个站点，原始记录仍应保留站点区别；仅凭一个相同的 SKU 字符串，也不能可靠区分不同卖家账户的数据。

RDT 要求必须结合具体 API 版本判断

不要笼统写成“所有个人信息请求都必须申请 RDT”。Amazon 的 Orders API v2026-01-01 使用相应角色权限访问个人身份信息，不要求 RDT；迁移指南也说明了通过 includedData 选择额外数据的方式。这是特定版本的规则，不代表整个 SP-API 都取消了受限数据要求。Orders API 迁移指南

实施前仍要检查目标操作和报表类型。减少申请字段能够减少下游处理范围，但不能单凭这一点判定合规。如果分析只需要站点级汇总数据，就应先判断个人信息是否有必要进入分析环境，而不是默认取回越多越好。

版本迁移不只是替换 URL 中的版本号

升级接口时，字段名称、状态值、分页行为和可选数据都可能变化。不能只替换版本字符串，就假设原来的解析逻辑仍然正确。先准备一小组业务记录，比较新旧版本的表示方式，再改变下游消费逻辑。

为每份验收后的数据记录来源版本。某个字段消失时，应触发相应校验，而不是自动填零。金额缺失、属性不适用和真实数值为零，是不同事实；它们对报表和建议的影响，需要由数据负责人作出明确约定。

走通一份报表：从请求到可用数据

报表处理状态不等于内部交付状态

对于请求生成的报表，IN_QUEUE 与 IN_PROGRESS 表示处理尚未结束；DONE、CANCELLED 和 FATAL 是结束状态，但不都代表成功。取消可能来自主动取消，也可能是没有数据；严重错误可能附带诊断文档。应检查实际结果，而不是把所有结束状态都转换成“看板刷新完成”。Amazon 报表处理状态说明

处理成功后，还要获取文档信息并实际下载内容。Amazon 的获取说明涉及短时有效的签名下载地址、可选压缩信息以及静态加密要求。返回文档信息，不等于已经返回报表内容；保存一个下载 URL，也不等于保存了可持续使用的数据集。Amazon 报表获取说明

用一个中断示例检查“完成”的定义

假设某卖家的试点只读取一个站点的非受限经营报表。内部任务拿到报表 ID，观察到 DONE，下载文件并开始校验，但工作进程在提交已验收数据之前停止。这里是用于说明问题的虚构流程，不是 Amazon 事故记录，也不是已经验证的 OpenMax 功能。

如果调度器在看到 DONE 时就推进完成标记，下次运行可能直接跳过尚未交付的区间。更合理的设计是分别保留来源处理状态和内部交付状态；根据已知报表上下文恢复，必要时重新获取可用下载信息，完成数据校验后再标记内部交付完成。

可以按以下顺序设计验收：

1. 将卖家、站点、报表类型和请求周期，与来源报表引用一起记录。
2. 检查来源结束状态，区分可用输出、取消和失败。
3. 在获准环境中获取并解析文档，按照实际格式和压缩信息处理。
4. 校验必要字段、范围、周期及一组对账样本；无法解释的差异先隔离。
5. 提交验收通过的数据与交付记录之后，再推进内部检查点。

重跑去重应依据业务身份，而不是只看内容相同

来源引用需要结合卖家上下文使用，记录主键则要适合报表的行粒度。重复下载同一份来源，不应产生两次已验收交付；但两行金额相同，不一定是重复，它们可能对应不同订单或商品。

检查点和去重规则是应用自己的设计，不是对 Amazon 提供“恰好一次交付”语义的承诺。应主动测试中断恢复和重复输入。数据接入后的解释工作，可以结合Amazon 卖家业务报表分析指南以及具体来源的指标定义开展。

先定位失败环节，不要对所有错误反复重试

保留足够上下文，区分不同原因

有用的故障记录应包含操作与版本、卖家范围、请求时间、响应状态和可用请求引用，同时避免暴露凭证。把令牌交换、SP-API 请求、报表生成、文档下载、内容解析分开看待；某一处失败，不代表其他环节全部不可用。

左右滑动表格，查看完整内容。

这张表是排查起点，不是完整错误码手册。尤其不能把所有访问拒绝都判断为令牌过期。保留实际错误详情，并参考目标操作的说明再决定处理办法，通常比不停更换凭证或追加权限更有帮助。

限流要按操作和调用上下文处理

Amazon 会根据操作和调用上下文应用使用限额。返回的 x-amzn-RateLimit-Limit 头可作为参考，但它不一定出现，也不是全部适用限额的完整说明。持续收到 429 时需要退避；提高请求频率，并不会自动换来更高容量。SP-API 使用计划与限流说明

实施中可以采用有上限的重试、受控并发和可见的积压时长；支持事件或批量方式的地方，按业务需要评估采用，而不是假设每个操作都具备这些能力。当延迟已经让业务产出失去价值时，应触发升级处理。技术上最终完成的任务，也可能已经错过运营需要它的时间。

扩大试点前，完成六类接入验收

沙箱通过有明确的证明范围

Amazon 文档列出了托管的静态、动态沙箱，以及本地 Sample AI Sandbox，不同 API 的支持情况不同。这些工具可以检验支持范围内的请求和响应行为，但不能复现每个卖家的生产数据，也不能证明生产环境扩展能力。根据目标 API 选择适用方式，并把模拟数据与真实账户证据分开。SP-API 沙箱说明

沙箱无法重现的失败，可以使用受控模拟输入测试处理逻辑。随后，在账户负责人明确授权下，用小范围生产数据获取检查真实范围和内容。不能为了证明通用连接器“能用”，就创建真实订单、调整价格或给买家发送消息。

测试之前先写清需要留下的证据

左右滑动表格，查看完整内容。

以上是建议的验收方案。模拟测试通过只能说明自己的处理逻辑表现，不能证明 Amazon 可用性或卖家生产权限。每条测试记录都应注明环境、输入、实际观察结果和审核者，避免把不同层级的证据混在一起。

获取数据和执行业务动作应分别批准

获得采集权限，不等于可以按分析建议直接行动。后续如果增加商品修改等写入操作，应重新验收请求内容、授权、影响和未知结果的处理方式。只读试点无法证明这条执行路径已经可靠。

每次最好只增加一个有意义的维度，例如一个站点、一种数据集，或更严格的时效目标，便于定位扩展后出现的问题。保留之前已通过的范围说明，即使新范围失败，团队也知道哪些已有产出仍然可信。

看清证据、局限与运行指标

统计可用交付，不只统计接口成功率

可关注的内部指标包括：最近一次验收数据的来源周期距今多久、还有多少校验异常未解决、哪些授权问题待处理、哪些交付尚未结束。先明确指标定义，再设目标。即使请求成功率很好，业务数据仍可能过期，或缺少一个站点。

让报表负责人说明多长的延迟就不可接受，以及到时必须停止什么工作。不要直接把供应商页面上的刷新宣传写进自己的验收合同。实际要求取决于具体决策、来源行为和正在运行的负载。

本指南没有证明哪些事情

本文是基于文档的工作流指南，不是在线接入性能测试。官方资料支持相关平台规则，故障案例和验收控制属于建议的工程实践。这里没有承诺审批耗时、生产吞吐量、固定费用，或适用于所有情况的安全认证。

发布实施方案前，责任人仍需审阅真实角色配置、数据处理设计和适用协议。上线后也要有人跟踪文档及版本变化。2026 年 9 月 10 日进行过资料核对，不代表未来任何时候、任何配置都持续正确。

OpenMax 的切入点：接住已验收数据，组织受限审核

协作层需要可信输入，而不是被假定的接口能力

数据能稳定获取之后，团队常出现另一个瓶颈：谁解释异常、补齐背景、决定下一步。OpenMax 将自身定位为人类与智能体协作平台，可以围绕这种审核协作需求评估它，而不能由此推断已经内置 SP-API 连接。实际支持的数据输入方式和工具配置，需要与实施团队逐项确认。OpenMax 官网

建议交给协作流程的是已授权、经过必要最小化的数据，以及来源和校验状态。审核简报里不应包含令牌、原始个人信息或签名下载链接。如果数据没有通过校验，应先调查失败原因，而不是让 Agent 根据残缺信息给出看似确定的销量或库存建议。

交接记录应写明允许产出和停止条件

下面是内部交接的说明示例，不是 SP-API 请求参数，也不是 OpenMax 产品功能截图：

任务：审核已验收的卖家数据试点
范围：已批准的卖家与一个站点
输入：受控数据引用、来源周期与结构版本
证据：来源报表引用及校验摘要
允许产出：解释、待确认问题、建议的下一项任务
停止条件：范围不符、数据过期、校验失败或缺少证据
负责人：指定的运营审核者
Amazon 业务修改：本审核任务不授权执行
关闭方式：审核者记录接受结果，或退回具体问题

只有在输入和输出权限完成配置与检查后，才考虑让 Agent 辅助起草解释。审核者应能沿着结论找到对应已验收数据。如果任务确实需要直接操作 Amazon，就另外验证执行器与授权路径，不要把一段文字被批准，等同于业务动作已经获准执行。

确定性的搬运工作不必复杂化

需求只是确定的数据获取与交付时，常规连接器或脚本通常更直接；持续瓶颈是解释和跨人员跟进时，再考虑协作层。两种路线都不能容忍输入不可靠。Amazon 卖家工作流自动化指南进一步说明如何分开这些阶段，而不是一次性委托整个运营流程。

常见问题：Amazon SP-API 接入

什么人可以开发 Amazon SP-API 接入？

需要按照组织用途完成适用的开发者和应用注册流程。当前注册概览要求在 Seller Central 开发私有卖家应用时使用专业销售账户；私有供应商和公有应用路径不同。所需角色和卖家授权也必须到位，拥有一个卖家登录账户本身，并不能证明应用已获得目标访问权限。

私有应用与公有应用有什么区别？

私有应用服务单一组织，采用自我授权；公有应用支持多个销售伙伴，需要相应的卖家侧 LWA 授权流程。Amazon 说明公有应用需要年度重新授权，并为新增角色获得授权；私有应用在新增角色时重新自我授权。应按真实使用对象选择，而不是仅看哪个流程更短。

接入 SP-API 还需要 AWS IAM 或 SigV4 吗？

按照 Amazon 自 2023 年 10 月 2 日生效的变更，SP-API 请求不再需要这两项要求。但 LWA 授权仍然相关，另外使用的 AWS 服务也可能需要各自的基础设施权限。删除配置前，先判断旧教程讲的是过时的 SP-API 签名，还是另一个服务的独立配置。

读取个人信息都必须使用 RDT 吗？

不能脱离 API 版本作统一判断。Orders v2026-01-01 迁移指南说明该版本按角色访问个人身份信息，不需要 RDT；其他受限操作或报表类型可能有不同要求。应核对目标版本，并尽量减少请求数据。不要求 RDT，不等于可以不受限制地使用个人信息。

遇到 SP-API 限流应该怎么处理？

按具体操作和实际调用上下文核对限额，对 429 做退避并减少重复请求。限流响应头在可用时有参考价值，但可能没有列出所有适用限制。重试次数应有边界，数据延迟应对运营负责人可见，不能靠隐藏积压来维持“正常运行”的表象。

沙箱测试通过就能上线吗？

不能。沙箱或模拟输入能够证明支持范围内的响应处理，却不能证明卖家生产权限、数据完整性和生产吞吐量。之后仍需在明确授权下检查小范围实际获取结果。批准数据获取试点，也不等于允许测试真实业务修改。

SP-API 接入需要多少费用？

预算取决于应用路径、当前适用收费、可能存在的连接器订阅，以及开发、托管和持续维护。应获取与自己情况对应的最新条款，不能默认接入和运行普遍免费。费用评估还应包括重新授权支持、结构升级和失败交付排查，而不只是第一次请求成功的开发成本。

OpenMax 已经有原生 SP-API 连接器吗？

本文没有确认原生连接器或生产 Amazon 执行器。围绕这类能力规划方案前，需要核实实际功能及适用范围。这里描述的是把已授权、已校验的数据交给人类与 Agent 协作审核的建议流程，数据获取与 Amazon 业务修改仍然分别受控。

下一步：用一份数据和一份明确验收结论开始

选择一个卖家、一个站点和一个运营问题。由技术负责人依据当前注册与操作文档，把所需数据映射到正确 API 和应用路径。第一次运行之前，就与实际使用者约定：看到什么证据，才算这次接入有用。

随后在合适的受控环境完成六类验收，检查小范围获准生产样本，记录通过事项和未解决问题。范围清楚之后再扩展。第一份交付不只是令牌或漂亮看板，而是一份负责人可以追溯、能够使用的数据，以及在不能使用时清晰可见的停止信号。