API 文档

开通 API

1. 先联系客服开户。
2. 把需要的服务、账号和服务器出口 IP 发给客服。
3. 运营开通后发放 API 密钥和完整接入文档。密钥有效期 1–730 天，每个密钥最多绑定 32 个出口 IP。

基本约定

认证

每个请求带 Authorization: Bearer <API 密钥>

User-Agent

必须带，缺少时会被 Cloudflare 拦截（error 1010）

格式

请求和响应都是 JSON（上传文件除外），编码 UTF-8

时间

UTC Unix 毫秒时间戳

金额

最多八位小数，请用十进制定点类型处理，不要四舍五入成两位

接入流程

1. 查询服务列表和余额，保存要用的 productId。
2. 查询数据使用声明；未确认时由你阅读后确认。
3. 上传号码文件，保存返回的 fileId。
4. 用 productId 和 fileId 报价，核对条数、单价和总价。
5. 生成并保存幂等键，再按报价下单。下单会真实扣费。
6. 设置 Webhook 接收订单状态推送；同时每 5–10 分钟用 updatedSince 对账一次，防止漏收。
7. 订单完成后列出结果文件，逐个下载并用 sha256 校验。成功和未成功的文件都要下载。

curl 示例

把占位符换成真实值。报价和下单的完整参数见开通时提供的接入文档。

1. 设置密钥，查询服务

   复制

   export CHECKIM_TOKEN='替换为运营提供的 API 密钥'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. 上传号码文件

   复制

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. 报价

   复制

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. 下单

   复制

   # 真实扣费。重试时保持幂等键和请求体完全不变。
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. 查询订单，或按变化时间对账

   复制

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. 列出并下载结果，校验 sha256

   复制

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

接口清单

查询订单与对账

• 订单列表默认按创建时间倒序。每页带 nextCursor 时，把它作为下一次的 cursor 继续取；游标翻页在持续新增订单时不会漏、不会重。
• 可按 status 和创建时间（createdFrom、createdTo，UTC 毫秒）筛选，也可以用 clientOrderId 查回某一笔订单。
• updatedSince 只返回该时间之后状态变化过的订单，按变化时间升序。定期用它补拉，Webhook 漏收也不会丢状态。

下载结果

• 结果列表里每个文件都有 sha256。下载响应的 ETag 是同一个值，下载完请比对。
• 支持 Range 断点续传。续传前先确认 sha256 没变；变了说明文件重新生成过，需要整份重下。
• 已有完整文件时，带 If-None-Match 请求，内容没变会返回 304，不再传输。
• 开启分批交付的大订单，执行中会先列出已完成批次的文件；订单完成后的最终文件是权威版本。
• 含头像的服务（TG/WS 高级检查、性别年龄检查）在结果 CSV 的 avatar 列给出带签名的图片链接，在结果保存期内可直接 GET 访问图片（无需带 Authorization 头，支持 If-None-Match）。

Webhook 推送

• 通过 API 下的订单状态变化时，平台向你的 HTTPS 地址 POST 一条事件。需要 webhook:manage 权限。
• 每条事件带 CheckIM-Signature 签名头（t=时间戳,v1=签名）。用签名密钥对“t.原始请求体”做 HMAC-SHA256 校验。
• 2xx 视为送达；失败会在约 2 天内重试 9 次。同一事件可能收到多次，请按事件 id 去重。
• 请求来自固定出口 IP 34.21.195.36，可以只放行这个地址。

订单状态

限流与注意事项

• 默认每分钟最多：同一出口 IP 1,200 次，同一账号 240 次，同一密钥 120 次。响应头 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 告诉你本分钟还剩多少次。
• 报价和上传较慢，同一账号同时进行中的最多 3 个，超出返回 429 TOO_MANY_CONCURRENT_REQUESTS。
• 收到 429 或 503 时，按 Retry-After 给出的秒数等待后用原请求重试。
• 没有测试环境，下单即真实扣费。
• 查询等待超时不代表下单失败。请先用 orderId 或 clientOrderId 查回订单，不要重新下单。

常见错误

错误响应带 code、requestId、message 和可选的 detail.field。程序按 code 处理；message 按 Accept-Language 返回 9 种语言之一，只用于展示。