API Guide

/api/v1/candidates 标准增量调用

这页只解释标准调用流程，不会在浏览器里自动发送带 token 的请求。这里提到的 since 语义，当前统一映射成 updated_after。

标准规则

since = updated_after，表示“从这个更新时间之后开始拉增量”。
增量拉取固定使用 sort=updated_time_asc。
如果响应里还有 meta.next_cursor，继续沿用同一组筛选参数，再补 cursor=<meta.next_cursor>。
一旦改了 platform / goods_type / search / updated_after 这类筛选条件，就不能复用旧 cursor。

标准 endpoint 形态：/api/v1/candidates?platform=facebook&updated_after=2026-04-01T00:00:00.000Z&sort=updated_time_asc&page_size=50

标准续拉终止条件：meta.next_cursor == null。

第一次增量请求

curl -H "Authorization: Bearer $CUSTOMER_API_TOKEN" \
  "https://productsdev.com/api/v1/candidates?platform=facebook&updated_after=2026-04-01T00:00:00.000Z&sort=updated_time_asc&page_size=50"

继续下一页

curl -H "Authorization: Bearer $CUSTOMER_API_TOKEN" \
  "https://productsdev.com/api/v1/candidates?platform=facebook&updated_after=2026-04-01T00:00:00.000Z&sort=updated_time_asc&page_size=50&cursor=<meta.next_cursor>"

关键返回字段

meta.next_cursor：下一页游标；为空表示当前窗口已经拉完。
meta.has_more：是否还有后续页。
filters.updated_time_start：服务端实际采用的增量起点。
items[*].updated_time：用于 ERP 持久化同步位点。

什么时候再读 detail

列表只负责增量发现；如果要做 AI 深度分析，再按候选 ID 读取 detail。detail 路由仍然是 https://productsdev.com/api/v1/candidates/:candidateId。

curl -H "Authorization: Bearer $CUSTOMER_API_TOKEN" \
  "https://productsdev.com/api/v1/candidates/<candidate-id>?include=raw_html"