接 Loop Returns：退货经 webhook 进来，在仓库里标记与处理

在 Loop 后台 Returns Management → Tools & integrations → Developer Tools 里创建带 returns scope 的 API key，把这一个 key 填进 Integration，理解测试为什么停在待核实，再激活——退货经 webhook 进来，仓库可标记与处理。

Loop Returns 连接器把您的 Loop 退货门户接到退货系统（RMS）。退货不是经 API 拉进来的：买家在 Loop 里发起退货时，退货经 webhook 进来。退货进来后仓库在本系统里作业——本连接提供两个动作：标记退货（flag）与处理退货（process）。它不出退货面单。本连接只有一个字段：Loop API Key。

前置条件#

• 一个能以管理员登录的 Loop 账号，能进 Returns Management → Tools & integrations → Developer Tools。
• 退货先在 Loop 里发生：买家在 Loop 发起退货，本连接负责接收——这里不是从零新建退货的地方。
• 开始前先清楚进单方式：退货只经 webhook 进来，没有定时 API 拉取可等，本连接也不提供退货面单。

拿凭证#

1. 登录 Loop 后台。
2. 进入 Returns Management → Tools & integrations → Developer Tools。
3. 在那里新建一个 API key，务必带上 returns scope。returns scope 是硬要求：没有它，后面标记与处理退货的动作会失败。
4. 完整复制这个 key。本系统与 Loop 通讯时，key 放在 X-Authorization 头里发送——您不用自己填这个头，只填 key。

填进 Integration#

1. 打开 Integration → 连接器市场 → Loop Returns → 新建连接。
2. api_key——必填，Loop API 密钥：粘贴您在 Loop 后台 Returns Management → Tools & integrations → Developer Tools 里创建的 key，完整粘贴，并确认带 returns scope。这是密码类型字段，作为秘密保存。本连接没有其他字段：没有店铺地址、没有服务器地址，没有别的要填。
3. 保存连接，然后运行测试——先看下一节，因为这个渠道的测试结果和其他渠道长得不一样。

测试连接#

点测试连接，请预期这个结果：填了真实 key 时，测试不会返回通过——它返回未通过、待核实，而且完全不向 Loop 发请求。这是这个渠道的预期行为，不是 key 填错的信号。原因很简单：Loop 没有已核实的只读探针能在不改数据的前提下证明 key 可用。已知的 Loop 动作 flag 与 process 都会改变一笔退货，不能拿来当无害测试；退货详情的读取路径也尚未从官方文档确认。所以测试只检查 key 是否存在、发零个请求、报告待核实。不要为了追求绿色结果反复重建 key——带 returns scope 的正确 key 显示的就是这个结果。如果 key 留空去测，结果只是模拟检查、并会标注为模拟；它不证明任何真实 Loop 账号的情况。

配 Mapping / 选模板#

选 Loop Returns 标准 Mapping。它把经 webhook 进来的退货记录为退货系统里的一笔退货，带 Loop 发来的退货单号、订单引用、商品与数量。激活前先走通一笔真实退货：在 Loop 里发起一笔退货、让它进来，再把本系统里的这笔和 Loop 并排对照——单号、商品、数量。如果有对不上的，在 Mapping 里调整那个字段，不要去改 Loop 里的东西。

激活#

激活后，在 Loop 里创建的退货经 webhook 进来，成为可以作业的退货。仓库在这里打开一笔退货、需要关注时标记它、处理完成时处理它——这两个动作会就该笔退货发到 Loop。先在 运行监控 / 日志里盯头几笔真实退货、和 Loop 对照无误，再放手跑。

这个连接不做的事：它不按计划经 API 从 Loop 拉退货，所以没有同步按钮可等；它也不出退货面单，买家的面单继续按 Loop 本身的方式提供。退货在 Loop 发起、经 webhook 进来、在这里标记与处理。

常见问题#

我填了真实 key，但测试显示未通过、待核实

这是 Loop Returns 的预期结果，key 完全正确时也是这样。Loop 没有已核实的只读探针能在不改数据的前提下证明 key 可用，所以测试根本不发请求、报告待核实。这个结果只说明 key 存在——它并不说明 key 是错的。

不要再反复重建 key。确认保存的 key 是在 Loop 后台 Returns Management → Tools & integrations → Developer Tools 里带 returns scope 创建的那个，然后继续配 Mapping 与激活，用第一笔真实退货经 webhook 进来与否来判断连接。

没填 key 时测试看着没问题，但真实业务一直没动静

key 留空时，测试只跑模拟检查，并把结果标注为模拟。那个结果从不和您的 Loop 账号通讯，所以它既带不进退货，也发不出标记与处理动作。

在 Loop 后台 Returns Management → Tools & integrations → Developer Tools 里创建带 returns scope 的真实 API key，粘贴进 api_key 字段并保存。之后测试会显示待核实——对这个渠道来说，这正是真实 key 的样子。

标记或处理一笔退货失败

最可能的原因就在 API key 本身：标记与处理是真正和 Loop 通讯的动作，它们需要带 returns scope 创建的 key。没有这个 scope 的 key 可以好好地躺在连接里看着完整，但对退货的每个真实动作都会被 Loop 拒绝。

在 Loop 后台 Returns Management → Tools & integrations → Developer Tools 里重新建一个 key，这次带上 returns scope，把保存的 api_key 换成它，再对同一笔退货重试标记或处理动作。

连接已激活，但没有退货进来

这个连接上退货只有一种进法：买家在 Loop 里创建退货的那一刻，经 webhook 进来。它背后没有 API 拉取，所以连接激活后 Loop 里没有新退货时，这里正确地什么都不显示——激活之前创建的退货也不会事后被拉进来。

在 Loop 里发起一笔真实退货，在这里和 运行监控 / 日志里等它。如果它进来了，连接就是好的，之前的安静只是没有新退货。如果一直不来，确认连接已激活且保存的是正确的 key，再查那个时间段的 运行监控 / 日志。

买家问他们的退货面单在哪里

这个连接根本不提供退货面单。它负责接收退货、发出标记与处理动作；买家打印的面单来自 Loop 本身、按您在 Loop 里已有的面单安排走。

买家面单流程留在 Loop 里，去查 Loop 里的面单设置。本连接用它做的事：把退货接收到这里，让仓库标记与处理它。

我有好几个 Loop API key，该用哪个？

只有一个 key 适合本连接：在 Returns Management → Tools & integrations → Developer Tools 下带 returns scope 创建的 key。为其他用途建的 key、或没带这个 scope 的 key，能填进字段，但标记与处理退货的动作没法用它们工作。

选带 returns scope 的那个 key，或按上面的拿凭证步骤新建一个，完整粘贴进 api_key 并保存。本连接只有一个字段，错误的 key 没有第二个地方可藏。