版本与弃用

版本在哪里

版本是路径中的一段，也是它唯一出现的地方：

https://api.zelnum.com/api/v1

只有一个在线版本。它在 OpenAPI 文档中的标识是 1.0.0；你实际请求的是路径段 v1。响应体刻意不重复版本号，所以不存在第二个需要保持同步的字段。

变更如何分类

类别	例子	对你的影响
增量	新接口、新的可选请求字段、新的响应字段、目录里新增产品	无。不升版本，无需动作。
行为	已有枚举（如 `error_code`、`billing_status`）里新增取值；默认值变化	通常无影响，但可能破坏穷举匹配。
破坏性	删除或重命名字段、改变类型、改变状态含义、新增必需请求头	需要新版本。
契约	文档对接口行为的描述本来就是错的	无 —— 但请看下节。

文档本身变更时

当接口行为被错误描述时，文档会就地更正。那是文档变更，不是契约变更：接口没动，描述动了。正因为”什么都没变”这类变更日志条目恰恰会让你看不到更正，更正会被变更日志单独列出。

如果某次更正改掉的是你已经据以开发的内容，它会以说明条目出现，而不是悄悄改掉。

弃用政策

一个接口被弃用时，会在 OpenAPI 文档里标记 deprecated: true，本站也会写明替代方案。该接口在通知期内继续可用，通知期长度在宣布弃用的地方写明。

弃用永远不会与其替代方案在同一次发布中发生。两者同时在线，你可以按自己的节奏迁移，而不是在一次故障中被迫迁移。

当前唯一一处弃用

POST /v1/realtime/detect 为早期客户端保留，并已在契约中标记为弃用。新接入请使用按系列区分的接口。

这是一次改名，不是重新设计 —— 请求体与响应形状完全相同：

	兼容接口	当前接口
地址	`POST /v1/realtime/detect`	`POST /v1/realtime/check/phone` 或 `POST /v1/realtime/check/email`
系列	由所传产品隐含	显式写在路径里，且必须与产品一致
产品字段	`products`（别名）	`product_ids`
`Idempotency-Key`	必需	必需

迁移就是改两行：

# 之前
curl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","products":[47]}'

# 之后 —— 系列移进路径，字段改名
curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","product_ids":[47]}'

同一个请求里同时传 product_ids 和 products 会被拒为 400 invalid_realtime_request，所以灰度期间两者不能混用。

下一步

OpenAPI —— 机器可读契约，包括 deprecated 标记
变更日志 —— 改了什么、什么时候改的