接 ReturnGO：经 API 拉 RMA 进来，带退货面单

在 ReturnGO 后台 Settings → API 里生成 API 密钥，从官方 API 文档的 Servers 一栏复制 API 服务器地址，把密钥、店铺域名与服务器地址填进 Integration，通过真实只读探针测试，再激活——RMA 经 API 拉进来，并支持退货面单。

ReturnGO 连接器经 ReturnGO API 把退货（RMA）拉进退货系统（RMS）：它读 RMA 列表与 RMA 详情，本连接支持退货面单。它靠 API 按计划拉取工作——本连接没有 webhook，所以 ReturnGO 里的新退货在下一次拉取时才出现在这里，不是创建那一刻。本连接有四个字段：API 密钥、您的店铺域名、从官方 API 文档复制的 API 服务器地址，以及一个可选的头名。

前置条件#

• 一个能登录的 ReturnGO 账号，能进后台的 Settings → API 页面。
• 您知道要接的店铺在 ReturnGO 里登记的店铺域名——形如 demo-store.myshopify.com 的域名，不是买家看到的店铺显示名。
• 您能打开 ReturnGO 官方 API 文档并找到 Servers 一栏——本连接的 API 服务器地址要由您从那里复制，没有内置默认值可兜底。
• 一个 ReturnGO API 密钥可管理多个店铺，所以要记清每个连接对应哪个店铺——店铺域名字段就是告诉本连接它在拉哪个店铺的东西。

拿凭证#

1. 登录 ReturnGO 后台，打开 Settings → API。
2. 在那里生成 API 密钥并完整复制。一个密钥可管理多个店铺，所以同一个密钥可用于不止一个店铺连接。
3. 按 ReturnGO 里登记的样子原样记下店铺域名，例如 demo-store.myshopify.com。请求时这个值放在 x-shop-name 头里发送，所以要复制域名本身，不要写显示名。
4. 打开 ReturnGO 官方 API 文档，找到 Servers 一栏，复制那里显示的 API 服务器地址。这个地址是必填的、必须来自那一栏——不要猜，也不要借用其他文档里的地址。
5. 只有 ReturnGO 在对接时给了您另一个 API key 头名，才把那个名字也记下来。多数情况下头名是 x-api-key，没有额外的东西要拿。

填进 Integration#

1. 打开 Integration → 连接器市场 → ReturnGO → 新建连接。
2. api_key——必填，ReturnGO API 密钥：粘贴在 ReturnGO 后台 Settings → API 里生成的密钥，完整粘贴。这是密码类型字段，作为秘密保存。
3. shop_name——必填，店铺域名：填 ReturnGO 里登记的店铺域名，例如 demo-store.myshopify.com。填域名本身，不要填店铺显示名——请求时这个值放在 x-shop-name 头里携带。
4. base_url——必填，API 服务器地址：粘贴您从 ReturnGO 官方 API 文档 Servers 一栏复制的 API 服务器地址，按那里显示的样子填成 https://… 形态。这个字段没有默认值：留空的话，测试在发出任何请求之前就会停下。
5. api_key_header——可选，API key 头名：一般情况保持 x-api-key。只有 ReturnGO 在对接时给了您另一个头名时才填，并按给的样子原样填。

测试连接#

点测试连接。填了凭证时，测试跑真实只读探针：它向您填的 API 服务器地址发 GET {base_url}/rmas?pagesize=1，API 密钥放在它的头里（默认 x-api-key，或您填的头名），店铺域名放在 x-shop-name 头里，并给应答留 12 秒。应答成功——即 GET /rmas 探针成功的消息——才算测通，因为探针证明了服务器地址能应答、密钥被接受、店铺域名被认出，且不改任何数据。base_url 缺失时，测试以 MISSING_BASE_URL 停下、根本不发请求；密钥或店铺域名缺失时，它会明确按缺失的凭证失败，不会假报通过。如果您完全没填凭证就测，结果只是模拟检查、并会标注为模拟——把三个必填字段补齐再测，才是真实探针。

配 Mapping / 选模板#

选 ReturnGO 标准 Mapping。它按 API 返回的内容工作：RMA 列表与每笔 RMA 的详情成为这里的退货记录，找单笔退货时可用订单号把拉取范围收窄。测试通过后先拉一次，把一笔真实 RMA 和 ReturnGO 并排对照——RMA 单号、订单引用、商品与数量——再走一遍该退货的面单流程，确认后再激活。如果 ReturnGO 里某个字段和您预期不同，在 Mapping 里调整那个字段，不要去改 ReturnGO 里的东西。

激活#

激活后，连接按您设的频率把 ReturnGO 的 RMA 拉进退货系统——列表与详情一起——仓库在这里处理这些退货，本连接支持退货面单。先在 运行监控 / 日志里盯头几次拉取、和 ReturnGO 对照无误，再放手跑。

这个连接不做的事：它不经 webhook 接收退货，所以 ReturnGO 里新建的退货不会在发生那一刻被推到这里——它在下一次计划拉取时才到。退货着急时，用它的订单号收窄范围手动拉一次，不要干等计划。

常见问题#

测试以 MISSING_BASE_URL 停下

base_url 字段是空的。本连接没有内置服务器地址：探针需要 API 服务器地址才知道把 GET /rmas 发到哪里，所以没有地址时它在发任何请求之前就停下、报告 MISSING_BASE_URL。

打开 ReturnGO 官方 API 文档，从 Servers 一栏按显示的样子原样复制服务器地址，粘贴进 base_url 填成 https://… 形态，保存后重新测试。

API 密钥是对的，但探针还是失败

探针查的不只是密钥：它还把您的店铺域名放在 x-shop-name 头里发送，并和 base_url 里的地址通讯。常见原因是 shop_name：里面填的是店铺显示名而不是登记的域名，所以即使密钥本身有效，ReturnGO 也不认这个店铺。base_url 抄错地方也会这样失败。

把 shop_name 改成 ReturnGO 里登记的域名，形如 demo-store.myshopify.com，并从官方 API 文档的 Servers 一栏重新复制 base_url。密钥保持不动，保存后重新测试。

api_key_header 要填吗？

多数情况下不用。携带 API 密钥的头默认是 x-api-key，连接用的已经是这个默认值。这个字段只为对接时 ReturnGO 给了另一个头名的店铺存在——自己编一个名字填进去、或没被告知就改它，会让好好的密钥看起来像坏了。

除非 ReturnGO 在对接时书面给了您另一个名字，否则 api_key_header 保持 x-api-key。如果给了，就原样填那个名字；如果您排查时改过它，改回 x-api-key 再测。

没填任何凭证测试就通过了——我是连上了吗？

没有。完全没填凭证时，测试只跑模拟检查、并把结果标注为模拟。它从不到达 ReturnGO，所以对您的密钥、店铺域名或服务器地址什么都不证明。

把三个必填字段补齐——api_key 从 Settings → API 拿、shop_name 填登记的域名、base_url 从官方 API 文档 Servers 一栏复制——保存后重新测试。只有 GET /rmas 探针的结果才算真实测通。

连接成功，但 ReturnGO 里的新退货没出现在这里

本连接靠 API 按计划拉取、没有 webhook，所以一分钟前创建的退货正确地要等下一次拉取。另一个常见原因是店铺：一个 API 密钥可管理多个店铺，本连接只拉它 shop_name 域名所指的那个店铺——同一个密钥下另一个店铺里创建的退货不会出现在这里。

确认这笔退货属于 shop_name 里域名所指的店铺，然后手动拉一次——找单笔时用订单号收窄范围——再看 运行监控 / 日志。如果手动拉能进来，连接就是好的，后面的会由计划拉取带进来。

探针超时、没有应答

探针等 base_url 的服务器应答 GET /rmas 等 12 秒，那段时间里什么都没回来。这指向地址本身：服务器地址抄错了栏、打字缺了一截或多了一截、或是与您店铺所用不同的环境，都不会应答这个店铺探针。

从 ReturnGO 官方 API 文档的 Servers 一栏重新复制 base_url，按显示的样子原样粘贴、什么都不加不减，保存后重新测试。修地址时不要同时改密钥或店铺域名——一次只改一个值。