关于本视频

本视频中的响应是真实的 API 响应，已做缩短。API 密钥和文件验证需要付费账号。

视频文字稿

1. 00:00上传文件

   把 CSV 上传到 /verify/file，然后让 webhook 在任务完成时通知你。Bulk 最多只能处理 50 个地址。更大的名单，就把整个文件作为 multipart 表单数据发送。接受 CSV、TXT 和 XLSX。email_column 指定要读取的列。省略它，系统会自动识别。这是测试文件。四行，外加一个我们想在结果里保留的 source 列。上传不会等待检查完成。它会返回一个任务 ID 和 pending 状态。它还会告诉你读取了哪一列，以及找到多少行和多少个唯一地址。和 API 密钥本身一样，文件任务只对付费账号开放。

2. 00:43跟踪任务

   要查看进度，对同一路径加上任务 ID 发送 GET。请求头相同，没有请求体。刚一询问，这个小文件已经在合并了。运行期间，状态会依次经过 preparing、pending、processing 和 merging 这样的步骤。看到 completed、completed with warning、failed 或 cancelled 就不用再询问了。这是已完成的任务。计数按状态拆分文件：一个无效、一个角色、一个 Catch-all 和一个一次性。credits_used 是 1，cache_hit_not_charged 是 3。三行是复查。这些地址在过去 24 小时内已经在这个账号上检查过，24 小时内的复查不收费。随结果附带两个链接。download_url 是稳定的 API 路径，所以应该保存这个。direct_download_url 是带签名的存储链接，到所示的过期时间就会失效。

3. 01:35获取结果

   调用 results 并把输出保存到文件。不带筛选时，API 会重定向到完整的结果文件，-L 参数会跟随这次重定向。你自己的列在最前面，保持不变。然后每一行后面跟着 ev_ 列，比如 status、score 和 reason。只需要要移除的行？加上筛选。多个筛选之间是 OR 关系，所以这里请求的是无效或一次性。带筛选时，CSV 会直接生成并返回。返回两行，也就是要移除的那两行。

4. 02:04使用 webhook

   轮询可以用，但长任务意味着大量请求。webhook 把方向反过来：文件任务完成或失败时，BillionVerify 会调用你的服务器。用 POST 向 /webhooks 注册一个。给它一个 HTTPS 网址和你想要的事件。有两个：file.completed 和 file.failed。响应里带着一个签名密钥，而且只会显示这一次。立刻保存好。你需要用它来检查每一次推送。每次推送都是一个 JSON POST，带三个请求头：事件、时间戳和签名。请求体写明事件和时间。它的 data 里有任务 ID、计数、已用积分和下载链接。

5. 02:44检查签名

   在处理推送之前先检查签名。把时间戳请求头、一个点和原始请求体拼在一起。用你的密钥对它运行 HMAC-SHA256，再和签名请求头比较。要对收到时的原始请求体做哈希。解析后再重新编码的 JSON 是对不上的。还要拒绝过期的时间戳，这样旧请求就无法被重放。所以整个流程很短：上传，保存任务 ID，等待 webhook，然后从稳定链接获取结果。

6. 03:11下一步

   状态值、筛选条件和每个 webhook 字段都在 API 参考里，地址是 billionverify.com/docs/api-reference。每天使用账号可获得 20 个免费积分，每月最多 600 个，无需信用卡。访问 billionverify.com 开始使用。