原 PRD 路由继续保留，与新接口使用相同数据引擎、权限和响应信封。下面路径为 API 服务路由；浏览器同源访问统一在前面添加/api。
| 接口 | 参数 / 请求体 | 语义 |
|---|---|---|
GET /v1/country/lookup | keyword | 国家名称、ISO 或国家码查询；可能多地区。 |
GET /v1/country/number-ranges | country_code | 对应国家码的 MSISDN 号段目录。 |
POST /v1/number/validate | {phone_number:string} | 返回 NumberLookup；号码保留在请求体中。 |
GET /v1/number/ranges | keyword | 按地区名称、ISO 或国家码查询号段。 |
GET /v1/operator/lookup | keyword,country | 运营商/网络查找，多个条件为 AND。 |
GET /v1/currency/lookup | keyword | 币种与地区查找。 |
GET /v1/exchange-rate/lookup | keyword,date | 参考汇率查找；保留单位与日期。 |
POST /v1/number/validate · 合成格式示例
curl 'https://YOUR_CELRYN_HOST/api/v1/number/validate' \
-H "X-API-Key: $CELRYN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"phone_number":"+12025550123"}'原 PRD 的不可靠默认逻辑已修订。未命中不返回默认国家或运营商，未查携转保持 null / false（portability_checked）。汇率采用正确的参考价机制，不称为 12 点报价。
成功 data 的字段语义分别参见号码归属、号段目录、目录与汇率文档。兼容路由不恢复旧版脱敏绕过或虚构默认值。
响应、鉴权与错误
数据接口支持X-API-Key 或同源 Cookie 会话。匿名访问为受限公共投影，完整字段权限由 API 服务执行。JSON 成功响应统一为{code:0,data,meta}；文件导出直接返回文件。
| 字段 | 说明 |
|---|---|
meta.request_id | 本次请求标识，用于排查错误，不包含密钥。 |
meta.dataset_version / source_mode | 当前数据版本与 demo / ir21 / reference / mixed 来源模式。 |
meta.source_published_at | 源发布时间；未知为 null。 |
meta.ingested_at | 平台导入时间，ISO 格式 UTC。 |
400 表示参数不符，401 表示需要有效凭证，403 表示权限不足，429 表示调用限制，503 表示服务或数据源暂不可用。请读取错误响应的 code、message、request_id，详见错误与重试。
ERROR / 示意结构
{
"code": "EXAMPLE_ERROR_CODE",
"message": "具体错误原因由服务端返回",
"request_id": "example-request-id"
}