晰联 CELRYN · 通信数据，清晰可循

状态表达

状态	含义	处理建议
`matched`	匹配原始号段声明	不能据此断言当前运营商或号码可达。
`unknown`	当前数据未覆盖	保留未知，不归为 invalid，不选择默认值。
`ambiguous`	多个候选需要确认	展示完整候选列表，不静默选择其中一条。
`invalid`	编号格式或规则不符	检查输入、国家码与编号长度。
`scheduled`	尚未到生效时间	检查 effective_at，不能提前作为当前规则。
`stale`	源发布时间较早	显示来源时间，不仅因资料较旧判定失效。
`demo`	合成演示数据	只能用于验证接口结构与交互。
`unavailable`	数据源或服务不可用	保留已知时间并提供重试，不构造成功数据。
`not_checked`	未查询携转或可达性	current_carrier/is_ported 为 null；portability_checked 为 false。

号码有效性的判断依据

validation_basis 区分 numbering_metadata（编号库规则）、range_declaration（已生效号段声明）与 unconfirmed（未确认）。numbering_metadata_valid 独立表示编号库是否匹配。已生效的明确运营商号段可能早于编号库更新，因此 valid 可为 true 而 numbering_metadata_valid 为 false；这不是编号库已校验或在网证明。

未来声明仍为 scheduled，尚不能依据该声明认定 valid。无论判断依据为何，当前运营商、携转、活跃性与可达性仍未核验。旧响应未提供依据字段时不补造编号库匹配结果。

API 时间字段与页面展示

页面仅以平台导入时间显示“数据更新时间”，格式为 YYYY-MM-DD HH:mm:ss，保持 UTC 数值、不添加时区后缀。源发布时间不在数据页面展示，API 响应仍保留以下字段；生效时间用于判断声明是否生效，不作为数据更新时间。

字段	含义
`source_published_at`	数据源发布资料的时间。未知允许 null。
`effective_at`	声明实际开始生效的时间，可晚于发布时间。
`ingested_at`	平台实际导入资料的时间。不是源更新时间。

覆盖接口

GET/v1/coverage

无需鉴权。返回当前 dataset_version,source_mode,country_count,operator_count,network_count,range_count,last_updated_at,source_published_at,covered_countries,limitations。所有数字是当前目录统计，不能据此声称全球完整覆盖。

服务状态

GET/health

只用于探测服务状态，不含个人数据；在线服务不等同于上游数据已接入或最新。

字段与权限

号码、MCC、MNC、TADIG、号段均保持字符串，避免丢失前导零与精度。公共投影由服务端执行，浏览器不得直接读取真实数据文件。GT、MSRN、测试号码不参与用户号码原始归属。

响应、鉴权与错误

数据接口支持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"
}