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

GET/v1/number-ranges

用途与边界

记录本次 meta.dataset_version，在相同筛选下逐页使用 next_cursor。版本变化或游标失效时重新获取一致快照，不将两个版本直接拼接。导出文件同样保留版本与来源。

建立完整基线并持续恢复

GET /v1/catalog/snapshot 需要有效 API Key 或登录会话，一次返回相同版本的 countries、operators、networks、ranges、currencies、exchange_rates 与 checkpoint。完整关系基线应使用此接口；号段 CSV 只包含号段，不等于全部关联实体。

HTTP

GET https://YOUR_CELRYN_HOST/api/v1/catalog/snapshot
X-API-Key: YOUR_API_KEY

原子保存完整基线及响应中的 checkpoint。不要把部分下载或单页号段当作完整快照。
使用 since=checkpoint 查询 /v1/changes，limit 可设 500（允许 1–500）。按 next_cursor 遍历，保持筛选不变，每页核对 snapshot_version。
全部页成功处理后，再原子提交数据和 next_since 为新的 checkpoint。meta.dataset_version 不是分页完成标志，不应用来提前推进 checkpoint。
以事件 ID 去重；游标或历史版本不可用时重新获取完整快照。Webhook 触发补拉，未生效声明按实际生效时间使用，不能按通知到达顺序覆盖当前归属。

可运行示例位于源码仓库的 examples/sync-catalog.mjs。先取得源码，再在服务端设置凭证并运行；状态文件包含目录数据，请保存在仓库之外的私有目录。

SHELL / 完整同步示例

export CELRYN_API_BASE_URL='https://YOUR_CELRYN_HOST/api'
# 通过安全方式设置 CELRYN_API_KEY，勿提交或记录密钥
umask 077
mkdir -p "$HOME/.local/share/celryn"
node examples/sync-catalog.mjs --state "$HOME/.local/share/celryn/catalog-state.json"

# 持续轮询（60 秒间隔）
node examples/sync-catalog.mjs --state "$HOME/.local/share/celryn/catalog-state.json" --watch --interval-ms 60000

脚本默认执行一轮，状态文件保存 checkpoint 而不保存 API Key。它的文件落库示例不替代你的业务数据库验收；请在演示或已授权范围内验证同步结果后再用于生产。

ir21.catalog.updated 是全局重置事件，country、operator 和 category 筛选不会屏蔽它。来源元数据变化也可能触发此事件；收到后应重新获取完整快照和 checkpoint，再继续增量同步，不能仅应用当前筛选下的局部记录。

请求参数

参数	类型 / 位置	说明
`country / operator`	string · 选填	地区标识或名称 / 运营商 ID。
`q / calling_code`	string · 选填	目录关键词 / 国家码，保留字符串。
`cursor / limit`	string / number · 选填	使用上一页 next_cursor；limit 为 1–500，批量同步建议 500。
`at`	string · 选填	ISO 时间，用于目录生效时间筛选。
`format`	json \| csv	默认 json。完整号段导出需要会话或 API Key。

请求示例

cURL / 合成示例

curl 'https://YOUR_CELRYN_HOST/api/v1/number-ranges?country=CN&limit=500' \
  -H "X-API-Key: $CELRYN_API_KEY"

# 文件导出使用相同筛选
curl 'https://YOUR_CELRYN_HOST/api/v1/number-ranges?country=CN&format=csv' \
  -H "X-API-Key: $CELRYN_API_KEY" -o number-ranges.csv

成功响应示例

以下是结构示例，不是当前在线目录的查询结果。

JSON

{
  "code": 0,
  "data": {
    "items": [],
    "total": 0,
    "next_cursor": null
  },
  "meta": {
    "request_id": "example-request-id",
    "dataset_version": "example-v1",
    "source_mode": "demo",
    "source_published_at": null,
    "ingested_at": "2026-09-08T00:00:00Z"
  }
}

data 字段语义

字段	类型	说明
`items / total / next_cursor`	array / number / string \| null	分页内容、总数和下一游标。
`id / country_iso2 / operator_id / network_id`	string	稳定记录标识与关联字段。
`kind`	msisdn	只包括实际用户号码，不混入 GT、MSRN 或测试号码。
`prefix / start / end`	string / string \| null	前缀与起止号码，始终保留字符串。
`number_length / owner_type`	number \| null / string \| null	长度约束与归属类型。
`source`	SourceInfo	来源、源发布时间、生效时间和导入时间。

响应、鉴权与错误

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