通用问题

Q1：API密钥存在有效期吗？

在您与Spotter保持合作关系期间，都能持续调用开放接口。

Q2：Spotter能主动向其它系统推送数据吗？

暂不支持，但是可以通过其他方式实现这个效果。
Spotter如何与其它系统对接？简单来说，这是一个“您来取，而非我们推”的模式：

您来操作：您需要在您的系统中（如ERP、商家仓等）配置并调用我们提供的API接口。

您来控制：您可以根据业务需求，主动、按需地从我们平台拉取数据（如查询订单、库存），或创建数据（如提交发货信息）。

其他方式：尽管我们的开放平台目前暂不支持主动向您的系统推送数据，但是您可以通过在您的服务器上设置定时任务（Cron Job）或轮询机制（Polling），定期调用我们的API接口，来实现数据的准实时同步。

Q3：能对接ERP/商家仓/自研系统吗？

✅ 我们能做什么？
我们已经把目前的接口全部展示在开放平台了。包括您可能关心的创建订单、多渠道发货、查询库存等所有功能的接口，详见本开放平台「开放能力」模块：https://develops.spotterio.com/api-320134808

❌ 我们不能做什么？
目前是单向集成（即别人使用我们提供的API接口主动对接Spotter）。我们不是“ERP、商家仓”等第三方系统的开发方，因此：我们不知道那个系统有没“调用API”这个功能。我们不知道那个系统把这个功能放在哪里，怎么配置。

❓ 您应该怎么做？
请将我们的API文档发给您正在使用的第三方系统的客服或技术支持，向他们咨询：“你们的系统，能否对接这个开放平台的这些API？”只有他们才能给您最终的、准确的答案。
当然，需要Spotter协助的地方，我们也会全力配合。

Q4：ERP对接问题

4.1能否对接ERP，实现多渠道发货？
我们提供了「创建多渠道订单」接口，API文档详见：https://develops.spotterio.com/api-263320887
如果ERP系统集成了此接口，那么ERP中的多渠道订单就可以通过调用此接口自动创建到Spotter，从而避免手动创建/导入。但是，具体的集成工作需要由ERP系统开发团队来完成，建议您与ERP系统技术支持确认他们是否支持以及如何配置。

4.2用ERP给Spotter推入库单，使用什么接口？
使用「创建待发货入库单」接口，API文档详见：https://develops.spotterio.com/api-300694988

4.3自动同步Spotter的PO订单到ERP，方便在ERP发货，使用什么接口？
使用「查询订单」接口，API文档详见：https://develops.spotterio.com/api-214779296

Q5：商家仓对接问题

5.1能否对接商家仓，实现DF/PO订单自动下单仓库完成打包发货的操作？
可以使用「查询订单」接口在商家仓系统获取Spotter的DF/PO订单信息，API文档详见：https://develops.spotterio.com/api-214779296
获取DF/PO订单到商家仓后，后续的打包发货操作暂不支持。

5.2想要实时同步Spotter的库存数据到商家仓系统，使用什么接口？
可以使用「查询库存」接口，API文档详见：https://develops.spotterio.com/api-252921261

Q6：接口时间字段的时区问题

“传参时时间字段是使用哪个时区的时间戳？返回的时间是哪个时区的时间？”
Spotter的页面时间都是使用的对应站点的时区时间。因此任何接口的时间字段，不管是传参，还是返回响应的时间，都与站点时区保持一致。

示例：「查询订单」接口，想要查询上图中第一个预计提货时间为“2025-12-05 (周五)”的PO订单，传参时，ordered_on_ms_start下单时间这个字段，就是将美国太平洋时区时间“2025-11-18 18:50:18”转换为时间戳1763520618000，相对应的，返回的for_ready_day_ms预计提货日期字段，也是美国太平洋时区时间。

Q7：我想增加新的API接口找谁？

如果您有特定对接需求或功能建议，欢迎随时通过您的账号经理或提交「API接口咨询」工单与我们沟通，我们将积极评估并纳入迭代计划。

Q8：是否有提供SDK？

有的，详看：https://develops.spotterio.com/doc-5151477#2%E4%BD%BF%E7%94%A8sdk%E8%B0%83%E7%94%A8api

Q9：是否有提供测试环境用于联调？

目前测试环境还在规划中。在测试环境上线前，建议您：

对于查询类接口，可直接使用生产环境数据进行测试。

对于创建、更新等有写入操作的接口，建议先在您的本地或测试服务器进行Mock模拟，以避免产生脏数据。

Q10：不同站点，需要使用不同的密钥吗？密钥是通用的吗？

密钥的权限与范围可自定义配置。
每个密钥均可独立配置其允许访问的站点范围（如仅美国、仅欧洲，或全部）以及接口权限（哪些接口可以用）。因此，您可以为不同的业务申请和使用不同的密钥，以实现权限隔离。

Q11：在对接中出现“授权信息不正确”、“签名错误”或“密钥无效”等问题，应如何排查？

请您核对密钥信息：确认输入的 APP Key 和 APP Secret 完全正确，注意区分大小写，并检查前后是否误输入了空格或换行符（建议直接复制粘贴）。

Q12：鉴权信息只能通过SDK调用吗？能否使用Postman进行HTTP调试？

理论上可行，但是不推荐。SPOTTER API采用摘要签名认证，需要对请求内容进行复杂的签名计算。官方SDK已内置完整的签名实现，您只需配置密钥即可自动生成合法签名，能极大提升开发效率和安全性。

接口问题

商品

Q1：「查询Listing列表」返回数据的唯一标识是什么字段呢？如何确定数据的唯一性

一条Listing数据的全局唯一性，由 ssku (或 asin) + svc_code 组合确定。

ssku 是商品在Spotter系统的唯一标识。

asin 是商品在亚马逊平台的唯一标识。

svc_code 是亚马逊卖家账号的唯一标识。
原因：一个商品（对应一个ssku/asin）可以在多个不同的亚马逊卖家账号（svc_code）下销售。在每个账号下，它都会形成一个独立的Listing。因此，必须结合商品标识和账号标识，才能确定唯一性。

Q2：「查询Listing列表」接口中各字段的字符长度限制是多少？方便我们设计系统规范。

除商品名称(itemName)字段最大支持500字符外，其余字符串字段最大长度均不超过255字符。
特别说明：这些数字是我们系统为保障兼容性而设的技术上限，并非业务推荐值。建议您依据自身实际的业务规范和数据体量来设定更合理、更严格的设计长度。这样既能满足业务需求，也能为系统未来的迭代留出充足空间。

Q3：「查询报价协议」使用msku_list入参调用，为什么有时无法返回价格信息？

可能原因：您修改过msku。报价协议是历史快照，记录生成时的商品信息（包括当时的msku），一旦生成不会更新。如果您后来修改了商品的msku，再用新msku查询旧快照就会无法匹配。建议使用ssku（Spotter唯一标识）进行查询。

订单

Q1：如何通过API自动获取订单，替代手动处理邮件？

请使用「查询订单」接口。您可以通过参数筛选status特定状态的订单，实现订单数据的自动化拉取与同步。

Q2：「查询订单」如何获取订单的最晚发货时间？

最晚发货时间参考返回字段中的for_ready_day_ms 。该字段表示订单预计提货就绪的截止时间戳。

Q3：「查询订单」接口的实时性问题：如果实际已经发货，接口获取的数据还会是待取件状态吗？

当前接口的发货状态回传存在一定的延迟，即实际已发货，但系统状态更新可能会稍有滞后。为避免因状态延迟导致重复发货的风险，建议贵方在调用发货接口时做好幂等处理，不要重复发货。目前延迟时间存在一定波动，具体时长暂时无法完全确定，可能几天。

物流

Q1：「查询承运商」接口的承运商编码，是否区分“spotter打单”和“自供面单”模式，是通用的吗？

是通用的，承运商编码不区分打单模式。“Spotter打单”和“自供面单”，是订单的履约模式，决定由谁来生成面单和预约物流。两种模式可以共用相同的物流服务商。所以绑定的是同一个渠道编码。

报告

Q1：「查询VC销售诊断」为什么接口获取的数据与SEVC销售诊断页面的数据不一致？

最常见的原因是时间戳入参错误。
SEVC页面上显示的时间均为所选站点的当地时区时间。如果SEVC选的美国站点，那销售诊断页面上显示的日期全部都是美国太平洋时区时间。因此在调用接口获取数据时，要把美国太平洋时区的时间转换成时间戳入参。

Q2：「查询VC实时销量」如何确定返回数据的唯一性？

数据的唯一性由sale_date_ms（销售日期）与商品标识组合确定。您可以使用以下任一组合作为唯一标识：

ssku + sale_date_ms（ssku为Spotter系统唯一商品标识）

plt_sku+ sale_date_ms（plt_sku为亚马逊平台唯一商品标识）

Q3：「查询VC实时销量」入参query_date_ms填和不填有什么区别？

此参数决定了查询的数据范围：
不填写：默认查询当前时间点向前24小时内的实时销售数据。
填写具体时间戳：查询该时间戳所在自然日（0点至24点）的全天销售数据。

Q4：「查询VC实时销量」同一天内，不同时间点查询的数据会重复吗？

分情况。

对于已过去的日期，任何时间查询该日数据，结果都完全相同。

对于今天，由于数据持续产生，举例：6点查询的结果将包含 1点的结果，并额外增加 1点至6点之间新产生的销量。

Q5：「查询VC实时销量」返回的销售额字段使用什么货币单位？

销售额货币单位与您查询的站点所在国家/地区的法定货币完全一致。例如：美国站返回美元（USD），德国站返回欧元（EUR），日本站返回日元（JPY）。

仓储

Q1：「查询仓库列表」为什么使用接口对接后，没有同步到虚拟仓和退货仓的库存信息？

这是因为虚拟仓和退货仓属于不支持绑定的特殊仓库类型，并且接口的默认查询模式（不传参数）仅返回您已绑定的云仓。
解决方案：在调用接口时，请设置参数 customize_storage_query_type 为QUERY_HAS_INVENTORY_STORAGE，以查询所有有库存的云仓（包含部分符合条件的特殊仓库）。

Q2：「查询仓库列表」为什么在SEVC“实时库存查询”页面能看到的仓库（有库存），通过接口查询不到？

检查入参customize_storage_query_type，如果是QUERY_BIND_STORAGE或者没有填写。那说明您调用接口时，该仓库已经解绑，因而通过接口获取不到。而SEVC“实时库存查询”页面会显示所有历史入库过的仓库，所以SEVC能看到。

Q3：「创建入库单」接口和「创建待发货入库单」接口有什么区别？

Q4：「创建待发货入库单」怎么调用完接口之后直接“已收货”了？

「创建待发货入库单」接口“待发货入库单”的创建通过“入库预报”功能实现，适用于Spotter云仓与自营仓场景，如果入库仓库为商家仓，则创建成功后就直接为“已收货”状态。可查看商家百科入库预报说明
如需取消商家仓的入库预报，需通过SEVC系统进行库存调整。调整路径为：SEVC - 仓储 - 实时库存查询右侧「库存调整」按钮。

Q5：ssku在SEVC中是可以查到的，但是调用「创建待发货入库单」接口时提示“产品条码不存在”

需要在产品-产品管理-详情-规格与条码-条码信息中，把ssku信息添加进去才可以。

Q6：「分页查询出库单」接口与「查询订单」接口，用什么关联可以获取到订单的供货价？

使用「分页查询出库单」接口的“fulfillment_order_no”字段匹配「查询订单」接口的“fo_no_list”获取到供货价“spt_cost_price”

Q7：「出库单发货」接口中outbound_no出库单号对应的是「查询订单」接口里的哪个字段？订单在其他平台那边出库，没有spotter的出库单号

可以通过「查询订单」接口拿到履约单号fo_no，然后基于履约单号fo_no使用「查询VC物流」接口，拿到vc物流单号shipment_code，然后使用vc物流单号去确认发货，即vc物流单号就是出库单号。

常见问题

通用问题#

Q1：API密钥存在有效期吗？#

Q2：Spotter能主动向其它系统推送数据吗？#

Q3：能对接ERP/商家仓/自研系统吗？#

Q4：ERP对接问题#

Q5：商家仓对接问题#

Q6：接口时间字段的时区问题#

Q7：我想增加新的API接口找谁？#

Q8：是否有提供SDK？#

Q9：是否有提供测试环境用于联调？#

Q10：不同站点，需要使用不同的密钥吗？密钥是通用的吗？#

Q11：在对接中出现“授权信息不正确”、“签名错误”或“密钥无效”等问题，应如何排查？#

Q12：鉴权信息只能通过SDK调用吗？能否使用Postman进行HTTP调试？#

接口问题#

商品#

Q1：「查询Listing列表」返回数据的唯一标识是什么字段呢？如何确定数据的唯一性#

Q2：「查询Listing列表」接口中各字段的字符长度限制是多少？方便我们设计系统规范。#

Q3：「查询报价协议」使用msku_list入参调用，为什么有时无法返回价格信息？#

订单#

Q1：如何通过API自动获取订单，替代手动处理邮件？#

Q2：「查询订单」如何获取订单的最晚发货时间？#

Q3：「查询订单」接口的实时性问题：如果实际已经发货，接口获取的数据还会是待取件状态吗？#

物流#

Q1：「查询承运商」接口的承运商编码，是否区分“spotter打单”和“自供面单”模式，是通用的吗？#

报告#

Q1：「查询VC销售诊断」为什么接口获取的数据与SEVC销售诊断页面的数据不一致？#

Q2：「查询VC实时销量」如何确定返回数据的唯一性？#

Q3：「查询VC实时销量」入参query_date_ms填和不填有什么区别？#

Q4：「查询VC实时销量」同一天内，不同时间点查询的数据会重复吗？#

Q5：「查询VC实时销量」返回的销售额字段使用什么货币单位？#

仓储#

Q1：「查询仓库列表」为什么使用接口对接后，没有同步到虚拟仓和退货仓的库存信息？#

Q2：「查询仓库列表」为什么在SEVC“实时库存查询”页面能看到的仓库（有库存），通过接口查询不到？#

Q3：「创建入库单」接口和「创建待发货入库单」接口有什么区别？#

Q4：「创建待发货入库单」怎么调用完接口之后直接“已收货”了？#

Q5：ssku在SEVC中是可以查到的，但是调用「创建待发货入库单」接口时提示“产品条码不存在”#

Q6：「分页查询出库单」接口与「查询订单」接口，用什么关联可以获取到订单的供货价？#

Q7：「出库单发货」接口中outbound_no出库单号对应的是「查询订单」接口里的哪个字段？订单在其他平台那边出库，没有spotter的出库单号#

广告#

Q1：如何确定「查询SP/SD推广商品」「查询SB广告」三个接口返回数据的唯一性？#