变更日志
本页记录接口与本文档的变更。条目从 2026-09-19 开始：在本页存在之前的变更不做追溯记录，所以没有条目应当理解为「未记录」，而不是「未变更」。
| 类别 | 含义 |
|---|---|
| API | 服务变了 —— 接口、字段、限额。 |
| 契约 | 发布的 OpenAPI 文档变了。 |
| 文档 | 文档变了。接口没动。 |
| 更正 | 文档此前对接口的描述是错的。 |
更正被单独标出来是有意的。它描述的是「你会读到的东西」变了，而不是「接口做了什么」变了 —— 所以你的集成不会因此中断，但任何照着旧描述搭出来的东西可能是错的。
2026-10-27 —— 国家代码参考表
Section titled “2026-10-27 —— 国家代码参考表”文档 · 新增
- 新增可搜索的国家代码列表，收录全部正式分配的 ISO 3166-1 alpha-2 代码，并从所有接收
country字段的接口页链接至此。country一直是电话类任务的必填字段，但接口从未公布过合法取值——它只在不支持时返回422 invalid_country——代码本身就是这份契约缺失的另一半。
2026-09-19 —— 文档重构、契约发布
Section titled “2026-09-19 —— 文档重构、契约发布”文档 · 新增
- 新增参考分组：OpenAPI、版本与弃用、状态与支持、安全、术语表。
- OpenAPI 3.1 文档现在发布于
https://docs.zelnum.com/openapi.yaml，与平台副本逐字节一致，可导入 Postman、Insomnia 和各类客户端生成器。 - 两种检测模式各自新增 Python、Node.js、PHP、Go 客户端示例。此前导航承诺了 SDK 示例，实际只有 cURL。
- 实时检测、批量提交、任务状态、结果下载四个接口都补上了逐字段说明表。
- 新增两道构建守卫：任一语言里出现列数不齐的表格，构建即失败；本文档提到的每个接口都会与随包保存的 OpenAPI 文档做双向核对 —— 文档里写了而契约里没有的接口，以及契约里定义了却无人记录的路径，都算失败。
契约 · 新增
- OpenAPI 文档本身：10 条路径、9 个 schema，以及兼容接口
POST /v1/realtime/detect上的deprecated: true。
文档 · 更正
- 批量的
country被写成所有提交都必填。 实际上电话类产品必填、邮件类产品必须省略。按原文，九个批量邮件产品根本无法提交 —— 每个请求都会校验失败。 - 批量的数量规则是错的。 原文写「每次请求 1,000 到 2,000,000 个号码」。真实规则是所选产品自身的最低数量 —— 500、1,000 或 2,000 —— 上限为平台最大值 2,000,000。旧数字把十一个最低数量为 500 的产品挡在门外。
- 错误码表列出了接口永远不会返回的四个码。 平台的历史文档页写有
not_found、result_not_ready、result_expired、validation_failed，但实现里一个都不存在，这些响应根本没有code字段。该表现在只列接口实际返回的 22 个码，并用第二张表说明那几种不带码的情况 —— 同时给照搬过那四个分支的人留了提醒。 - 响应示例缺少接口实际会返回的字段。 实时响应缺
series、charged_amount、refunded_amount；批量提交响应缺idempotent_replay、recovery_pending；任务进度缺十个计数器，包括submitted、prefiltered、deduped、stage、last_progress_at、failure_message。 - 限流页面写错了接口。 实时那一行写的是
POST /v1/realtime/check/phone；该限额实际适用于POST /v1/realtime/check/{series}，含邮件系列。 - 响应头被描述错了。 限流页此前暗示每个响应都带全套响应头。事实并非如此：实时令牌桶在成功时只报
X-RateLimit-Remaining，从不报X-RateLimit-Limit；X-RateLimit-Reset只出现在通用组或检测组的429上。页面现在逐项说明每个响应头出现在哪里。 - key 模型被描述错了。 安全页此前称账户同时只持有一个 key。实际上账户可以同时持有多个启用中的 key，控制台对它们逐个创建、重新生成或删除 —— 因此可以做到零停机分段轮换，而原地重新生成才是有空档的那一种。
GET /v1/api-key报的是最近签发的启用 key，不是一份清单；它的last_used最多每五分钟写一次。 - ID 与 slug 的失败方式被描述错了。 术语表此前称 ID/slug 混用会被拒为
product_mode_not_supported。在实时接口上product_ids按整数数组校验，所以 slug 会更早地被拒为400 invalid_realtime_request；422 product_mode_not_supported是批量接口对实时产品的回答。 - 响应格式页与余额页对币种的说法互相矛盾。 一个说「账户的计费币种」，另一个说 USD。现在两处都写明 USD，这也是契约与余额接口的说法。
- 一处计价单位没有出处。 批量被描述为「按每 10,000 次检测计价」。产品目录并不暴露价格，所以该说法被删除而不是保留。
- 有两处更正只落到了手写页。 币种表述与「按每 10,000 次计价」的说法已在英文与简中页面上改掉，但生成其余七种语言所用的字符串表仍带着它们，于是那七种语言继续发布旧说法。字符串表也已更正。
/examples/在各语言里根本不是同一个页面。 英文页是一个简短的导航枢纽，而其余八种语言渲染的是五步批量走查。英文现已与走查对齐，九种语言承载同一份内容。
文档 · 修复
- 生成语言的参数表静默丢掉了「说明」列。 一个共用的表格辅助函数给四单元格的行输出了三列表头，而 GFM 会丢弃超出表头宽度的单元格 —— 于是在西班牙语等语言里，「必填」的值渲染到了「说明」表头之下，真正的说明则完全消失，七种语言各三页受影响。该辅助函数现在要求显式声明列结构，并在行内单元格数不齐时让构建失败；dist 阶段的守卫还会在每种语言里独立复核每一张渲染出来的表格。
- 生成语言里的产品表表头、说明和同步提示渲染成了英文，且说明中的反引号原样输出到了浏览器。组件文案现在来自翻译串表，缺失翻译会让构建失败，而不是静默回退。
暂时还没有 feed。在有之前，可靠的信号是契约本身：
npm run openapi:check放进定时任务即可 —— 一旦发布的文档与你随包保存的副本不一致，它就会以非零码退出。两个地址见 OpenAPI。