数据调用

提交调用

将 SORIT_URL 设置为 Sorit 的访问地址。先通过 GET /api/tools 发现可用工具；未接入的工具无法调用。

curl "$SORIT_URL/api/jobs" \
  -H "Authorization: Bearer $SELLERTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-request-001" \
  -d '{"kind":"amazon-search","input":{"query":"travel mug","market":"US"}}'

新调用返回 HTTP 202，包含 jobId、charged 与 replayed: false。身份、输入和费用由服务端校验。输入错误返回 400，余额不足返回 409，数据服务不可用返回 503。

原生 endpoint 参数

通过 GET /api/tools 浏览平台工具，再通过 GET /api/endpoints?provider=dataforseo&page=1 检索 API，读取 GET /api/tools/{endpointId} 的 Schema。使用 API 的 endpoint id 作为 kind；参数按 Schema 放入 body、query 或 path，例如字典查询使用 input.query。未声明的位置不要发送。上述 amazon-search 是保留的精选查询兼容入口。

目录每页 24 项，使用响应的 total 和 pageSize 翻页。只有 status=available 的工具可调用，未定价或未配置时不扣积分。

安全重试

每个逻辑请求使用唯一的 Idempotency-Key，支持 1–128 位字母、数字、点、下划线、冒号或连字符。相同密钥和规范化输入会返回原 jobId、charged: 0 与 replayed: true，状态码为 200。相同密钥携带不同输入返回 409 idempotency_conflict。不同账户之间相互隔离；网络超时后重试应保留原密钥。

读取与导出

GET /api/jobs/{id} 返回状态与产物，轮询至 done 或 failed。原生 endpoint 的 artifacts 包含 endpoint-json，字段为 provider、endpoint、fetchedAt 和 result。精选查询保留 data-table，字段为 source、market、query、columns 和 rows。失败按记录的费用退款。GET /api/jobs/{id}/export 下载原生 JSON 或表格 CSV，不会再次请求供应商或扣费。所有结果均校验账户归属。