API文档（采集对接 · SaaS 多租户版）

鉴权：所有采集接口统一用请求头 X-Api-Key: <采集密钥>（也兼容 ?api_key= 参数）。 密钥由运营方发放，请勿写入前端代码或公开仓库。
返回格式：所有接口返回 {code, msg, data}，code=0 表示成功。 401=密钥缺失或失效，403=无权限（用户被禁 / 授权无效 / IP 被封 / 该密钥未授权此平台），429=触发频率限制。
任务归属：平台级密钥（scope=platform）可一次领取全部用户的任务，返回行带 user_id 与 shop_id， 回传时按店铺 / 链接自动归属到对应用户，一般无需关心 user_id；
任务可能少于"待采总数"：同一件商品 / 同一个店铺 / 同一个关键词被多个用户同时追踪时， 系统只会下发一条任务（跨用户去重），采集结果由系统自动分发给他们。 计费口径：只向"需要采集数据"的用户计费 —— 对方本轮也在自己的采集周期内则照常扣费， 不在采集周期内则数据照给、免费共享。这是预期行为，不是漏发。
批次号：claim=1 时系统生成批次号并返回（详情 B / 评论 R / 关键词 K 前缀）， 回传时带上 collect_batch 便于对账。
平台权限（按密钥配置）：一个密钥可以被限定为只能采某几个平台（如只会采虾皮、只会采亚马逊， 由运营方在后台勾选）。
  · 拉取：只返回该密钥被授权平台的任务，返回体里的 platforms 字段就是你的平台范围 （"all" 表示不限）；可用 platform=shopee 进一步只拉某一个平台 （多平台采集机可以分流，互不抢其它平台的任务）。
  · 回推：非授权平台的数据会被 403 拒绝，且不入库、不扣费。 这种拒绝是"用错密钥"，不要自动重试，请改用对应平台的密钥或联系运营方调整权限。
  · 每个平台各有一条独立的任务批次，互不影响 —— 虾皮采集方与亚马逊采集方可以同时跑同一个用户的任务。

1. 拉到的任务数比"待采总数"少？ 同一件商品 / 同一个店铺 / 同一个关键词被多个用户同时追踪时只下发一条任务（跨用户去重）， 回推后系统自动分发给所有订阅用户，属预期行为。
2. 返回空列表并提示积分不足 / 授权到期？ 该用户侧的前置条件不满足，任务会被临时扣住，用户充值或续费后自动恢复，采集方无需处理。
3. 同一条链接需要重复采吗？ 不需要。按 claim=1 返回的批次，用 batch=<批次号> 继续拉取未完成部分即可，已完成的行不会再下发。
4. 回推重复提交会怎样？ 店铺回推是字段覆盖，重复提交无副作用； 关键词回推的链接按「店铺 + 链接」去重，已存在的会跳过（响应里计入 skipped）； 链接详情回推与评论回推现在也带判重：同一条链接的同一个 collect_batch 已经成功回推过，第二次会返回 code:0 + accepted:false + skip_reason:duplicate_retry， 不会重复入库、更不会重复扣费——这种响应说明"已收到，不需要重试"，直接跳过即可。 所以：请务必带上 collect_batch，它是判重的凭据。
若响应超时不确定是否写入成功，也可以先用 api/collect.php?action=history&link_id=xxx 核对最近采集时间。
5. 采不到数据（商品下架 / 超时 / 遇到验证码）该怎么回推？ 照实把错误回推上来，不要回推空壳或占位数据。系统会把该链接标成「采集失败」， 记录失败原因，并进入冷却窗口（默认 30 分钟）后自动重新排入任务；这期间不写数据、不扣费。 若推的是空壳数据，系统同样会拒收（skip_reason=collect_failed）—— 但失败状态与原因就记不下来了，运营方也无从判断是哪一类失败。 响应里的 reason 字段会写明这次为什么被判为失败。
6. 怎么拿到「店铺名」，按店铺把整店链接一次抓回来？ 店铺名 = username（店铺账号名），例如 mrsexshop，用它打开 https://shopee.tw/{username} 即可枚举该店所有外显链接。获取途径（按优先级）：
① 详情任务的每一行已直接带 shop_username / username_known / shop_url（collect.php，2026-09-29 起）； ② shop_collect.php?action=shops&link_id=<link_id> 按商品链接反查店铺（只读、不计费）； ③ shop_collect.php?action=shops&shop_id=<平台店铺ID> 单店查询； ④ shop_collect.php?action=list 只返回"还缺用户名"的店 —— 那些店本来就是需要你去采集店铺名的任务。
若 username_known=false 且任务里也没有这家店，说明店铺名还没采到， 此时用 shop_url（数字ID版店铺主页）同样能打开店铺。
7. 回推一直失败怎么办？ 请把响应里的 code / msg、请求时间与批次号反馈给运营方，便于按批次对账。
8. 一次能回传多少个商品？ 可以一次回传 4~50 条。把这一批的条目放进数组即可，以下写法都支持：
  · {"channel":"rpa","payload":[条目1,条目2,...]}（推荐）
  · {"results":[...]} / items / list / data / tasks / records / details
  · 顶层直接是数组 [条目1,条目2,...]；或 {"payload":{"results":[...]}}
返回体：data.total / accepted / skipped / failed / credit_deducted / items[]， items 里每条带 index 与自己的 accepted（失败条目还有 skip_reason 或 error）。
每条独立处理：第 3 条坏了不影响第 4 条入库与计费。个别条目失败请不要整批重推 —— 重推会命中判重闸门（不会重复计费），但白跑一趟。
9. 什么是「主动触发」？ 如果某个平台的某种数据被运营方配成了主动触发， 它不会出现在普通拉取的结果里；需要带 mode=push 领取。 push 链路返回的每一行会多带 collect_mode=push 与 trigger （触发渠道：name / handler / endpoint / auth_type / has_auth / params）， 你按 handler 决定走哪套接口去采。若该平台没配触发器，会返回 trigger=null 且带 trigger_hint 说明原因。
  注意：触发器里的凭证不会随任务下发（只回 auth_type 与 has_auth）， 需要凭证时请写进触发器的「参数模板」，或在你自己程序里配置。
  采集完的回传接口与普通链路完全相同，无需另做一套。
10. 回传的原始 JSON 存在哪？ 会按 json/{用户名}/{日期}/{批次}/{记录ID}_{字段}.json 落盘，方便按用户与批次整体导出。