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

GET/v1/changes

用途与边界

先用 /v1/catalog/snapshot 建立同一版本的全量基线并保存 checkpoint，再以 since=checkpoint 补拉增量。分页中的 snapshot_version 标记本批固定快照；全部页消费成功后才提交 next_since 为新 checkpoint，不能使用 meta.dataset_version 替代。以事件 ID 去重。未来生效事件不能立即作为当前归属。未配置上游时不宣称实时更新。

建立完整基线并持续恢复

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，再继续增量同步，不能仅应用当前筛选下的局部记录。

请求参数

参数	类型 / 位置	说明
`since`	string · 选填	来自完整快照 checkpoint 或上次完成批次 next_since 的恢复点；也支持已知版本或 ISO 时间。
`cursor / limit`	string / number · 选填	稳定分页游标与单页数量。
`country / operator`	string · 选填	地区、运营商筛选。
`category`	string · 选填	number_range、operator、network 或 capability。

请求示例

cURL / 合成示例

curl 'https://YOUR_CELRYN_HOST/api/v1/changes?since=example-v1&category=number_range&limit=20' \
  -H "X-API-Key: $CELRYN_API_KEY"

成功响应示例

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

JSON

{
  "code": 0,
  "data": {
    "items": [],
    "total": 0,
    "next_cursor": null,
    "snapshot_version": "example-v2",
    "next_since": "example-v2"
  },
  "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 字段语义

字段	类型	说明
`snapshot_version / next_since`	string / string	snapshot_version 固定本批目录；next_since 仅在全部页面成功应用后提交，不能提前使用 meta.dataset_version。
`id / type`	string	稳定事件 ID 与事件类型；重投保持同一 ID。
`occurred_at / effective_at`	string / string \| null	事件生成时间与数据实际生效时间。
`dataset_version / previous_version`	string / string \| null	当前版本与上一个版本。
`country_iso2 / operator_id`	string \| null	事件关联的地区与运营商。
`data.before / data.after / data.summary`	unknown / unknown / string	前后记录与摘要；具体字段随事件类型变化。

响应、鉴权与错误

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