开发文档 · 快速开始

先核验数据覆盖，再接入业务。默认未配置真实目录时为合成演示数据，所有响应附带 source_mode。演示数据不能作为真实路由依据。

IR21Data提供通信数据 API 服务。接口中的 ir21 事件前缀、请求头与来源模式值是保留的技术标识，不是公司或品牌名称。

1. 创建账户与密钥

注册试用账户后，前往API Keys创建凭证。完整密钥只显示一次，保存在服务器的安全环境变量中，不放入前端代码或 URL。

2. 发起第一个请求

当前 API 基础地址：https://YOUR_IR21DATA_HOST/api。默认使用当前站点的 /api 入口。部署时可通过 NEXT_PUBLIC_API_BASE_URL 配置公开地址；服务器调用可设置 IR21DATA_API_BASE_URL 覆盖。

SHELL / 使用自己的密钥

# 在安全环境中设置 IR21DATA_API_KEY，勿提交到仓库
curl 'https://YOUR_IR21DATA_HOST/api/v1/countries?q=China&limit=20' \
  -H "X-API-Key: $IR21DATA_API_KEY"

3. 检查响应上下文

读取meta.source_mode、版本与时间，判断数据是否适用于业务。未知和多候选结果是正常数据状态，不应自动改为默认运营商。

JAVASCRIPT / 服务端示例

const base = process.env.IR21DATA_API_BASE_URL ?? "https://YOUR_IR21DATA_HOST/api";
const response = await fetch(base + '/v1/countries?q=China', {
  headers: { 'X-API-Key': process.env.IR21DATA_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 API 为准。匿名可有限预览，登录或 API Key 可试用完整授权字段；当前不接支付。

进阶接入与旧链接

网络身份与 E.214 请结合 TADIG、PLMN 和运营商网络能力文档；目录同步先建立一致快照，再消费增量与 Webhook。现有路径和旧文档链接继续有效。

响应、鉴权与错误

数据接口支持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 表示权限不足，409 表示目录或游标版本冲突，429 表示调用限制，503 表示服务或数据源暂不可用。请读取错误响应的 code、message、request_id，详见错误与重试。

ERROR / 示意结构

{
  "code": "EXAMPLE_ERROR_CODE",
  "message": "具体错误原因由服务端返回",
  "request_id": "example-request-id"
}