先核验数据覆盖，再接入业务。默认未配置真实目录时为合成演示数据，所有响应附带 source_mode。演示数据不能作为真实路由依据。
晰联提供通信数据 API 服务。接口中的 ir21 事件前缀、请求头与来源模式值是保留的技术标识，不是公司或品牌名称。
1. 创建账户与密钥
注册试用账户后，前往API Keys创建凭证。完整密钥只显示一次，保存在服务器的安全环境变量中，不放入前端代码或 URL。
2. 发起第一个请求
当前 API 基础地址：https://YOUR_CELRYN_HOST/api。默认使用当前站点的 /api 入口。部署时可通过 NEXT_PUBLIC_API_BASE_URL 配置公开地址；服务器调用可设置 CELRYN_API_BASE_URL 覆盖。
SHELL / 使用自己的密钥
# 在安全环境中设置 CELRYN_API_KEY，勿提交到仓库
curl 'https://YOUR_CELRYN_HOST/api/v1/countries?q=China&limit=20' \
-H "X-API-Key: $CELRYN_API_KEY"3. 检查响应上下文
读取meta.source_mode、版本与时间，判断数据是否适用于业务。未知和多候选结果是正常数据状态，不应自动改为默认运营商。
JAVASCRIPT / 服务端示例
const base = process.env.CELRYN_API_BASE_URL ?? "https://YOUR_CELRYN_HOST/api";
const response = await fetch(base + '/v1/countries?q=China', {
headers: { 'X-API-Key': process.env.CELRYN_API_KEY },
});
const body = await response.json();
if (!response.ok) throw new Error(body.message);
if (body.meta.source_mode === 'demo') {
// 仅做集成验证，不用于真实业务判断
}
const { items, next_cursor } = body.data;4. 选择接入方式
| 目标 | 接口 / 文档 |
|---|---|
查询号码 | /v1/e164/:number/range-owner；浏览器可用 POST /v1/number/validate。 |
关联网络身份 | /v1/plmn/:mccmnc 与 /v1/tadig/:code。 |
建立目录基线 | /v1/number-ranges，记录 dataset_version 并按 next_cursor 分页。 |
持续更新 | /v1/changes 补拉增量；Webhook 用于主动通知。 |
补全参考数据 | /v1/countries、/v1/operators、/v1/currencies、/v1/exchange-rates。 |
响应、鉴权与错误
数据接口支持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"
}