任务
创建任务
POST
/api/open/v1/tasks创建检测任务提交后立即扣费并开始执行。计费数量为系统归一去重、按国家过滤后的有效数量。
字段
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| type | integer | 必填 | 产品 ID，取自 /products 接口 |
| file_path | string | 必填 | 上传地址接口返回的 file_path |
| file_name | string | 必填 | 原始文件名，用于任务展示与结果文件命名 |
| country | string | 可选 | ISO2 国家码。号码类产品必填（见 /products 的 country_required），邮箱与用户名类不需要 |
| description | string | 可选 | 任务备注，不填则用文件名 |
| follow_up_types | integer[] | 可选 | 后续检测链，有序产品 ID 列表，每步单独扣费 |
| notifications | object[] | 可选 | 完成通知，如 [{"channel":"email","lang":"en"}] |
请求体示例
{
"type": 19,
"file_path": "portal/upload/1/20260918/ab12cd_numbers.txt",
"file_name": "numbers.txt",
"country": "US"
}以下字段不接受
数量由服务端依据文件实际内容计算；记账主体由签名密钥决定。传入这些字段会被忽略。
| 字段 | 类型 | 说明 |
|---|---|---|
| line_count | — | 数量由服务端按文件实际内容计算，申报值不影响计费 |
| api_key_id | — | 记账主体由请求签名所用的密钥决定 |
查询任务
GET
/api/open/v1/tasks任务列表GET
/api/open/v1/tasks/{id}任务详情（轮询判断完成）轮询任务详情判断是否完成，再去取结果。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id | integer | 任务 ID，后续查询与下载结果都用它 |
| status | integer | 任务状态，取值见下表 |
| type | integer | 对外产品 ID |
| country | string | ISO-2 国家码；邮箱 / 用户名类任务为 "N/A" |
| file_name | string | 创建时提交的原始文件名 |
| total | integer | 本次实际计费的条数 —— 归一去重、按国家过滤后的有效条数，通常小于文件行数 |
| success | integer | 已处理完成的条数，可据此估算进度 |
| activated | integer | 命中（已激活 / 已注册）的条数，即最终有价值的结果量 |
| cost | integer | 本次扣费，单位微美元（1 USD = 1,000,000）。整数避免浮点误差 |
| created_at | integer | 创建时间，Unix 秒 |
| finished_at | integer | 结束时间，Unix 秒；0 = 尚未结束 |
| error_code | string | 失败时的稳定错误码，空串表示无错误 |
| parent_task_id | integer | 后续检测链中指向上一步任务；0 = 非派生任务 |
status 取值
轮询任务详情直到进入终态：6 表示完成、结果可下载，8 表示失败并已退款。其余为过程态，继续等待即可。
1Created已创建，等待排队
2Pending排队中
3Processing检测进行中
4Processed检测完成，正在整理结果
5Exporting结果导出中
6Exported已完成，结果可下载终态
7Unknown状态未知，请稍后重试
8Error失败，见 error_code；失败任务会退款终态
后续检测链
可选。每一步用上一步的有效结果作为输入自动创建下一个任务，并在创建时各自扣费。任一步有效结果不足或余额不足则静默终止。
{ "type": 19, "follow_up_types": [22, 31], "...": "..." }