原始归属运营商查询 API：为注册后端添加运营商与线路类型上下文

本指南旨在说明如何在电话注册流程后调用运营商查询 API，将原始运营商和号码类型存储为审核上下文，并安全地处理故障。

在电话注册流程中，运营商查询 API 是一项服务器端调用，它接收提交的号码，并返回该号码段最初分配的运营商、号码类型以及分配地理位置。通过 CarrierLookup，后端将号码标准化为 E.164 格式，将其发送至 POST /api/v1/check（使用存储在服务器上的 API 密钥），并将结果作为审核上下文存储在账户旁边。最佳调用时机是在表单被接受之后、任何路由或人工审核决策之前，这样缓慢或无法判定的查询就不会阻止用户完成注册。

电话号码查询与基于 IP 的运营商检测之对比

搜索运营商查询 API 时会得到两种不同类型的服务，选择错误会导致集成工作浪费。

希望了解用户所填电话号码的注册后端需要的是第二种。IP 查询无法提供关于号码的任何信息，而号码查询也无法提供关于浏览会话的信息。有些团队会同时存储这两者，但它们回答的是不同的问题，应存放在名称不同的独立字段中。

运营商查询 API 在注册流程中的位置

请将查询置于后端，即在您自己的表单验证之后、任何使用其输出的决策之前。以下流程适用于大多数产品：

1. 接受表单。 检查电话字段是否存在且格式合理。
2. 标准化为 E.164。 将输入转换为包含加号、国家代码和用户号码的格式，且不含空格，具体定义见 ITU-T Recommendation E.164。同步查询无需单独选择国家/地区，因为号码内的国家代码已包含该信息。
3. 创建处于待处理上下文状态的账户。 如果您的注册页面有严格的延迟限制，请勿在等待查询结果时保持 HTTP 响应处于打开状态。
4. 调用 POST /api/v1/check，通过作业或工作进程处理单个号码。
5. 存储结果，包括查询时间以及状态（如已完成、为空或无法判定）。
6. 应用您的规则。 对账户进行路由、将其加入人工审核队列或不采取任何操作。

在队列中运行调用可保持注册流程的响应速度，并为重试提供自然的处理方式。

每次查询应存储的内容

已完成的检查会以通俗易懂的术语描述号码的分配情况：原始运营商、品牌在其他网络上运营时的底层运营商、号码类型（如移动电话或固定电话）、国家代码，以及与该号码段关联的地区和城市。请将这些信息存储在名称明确的字段中，例如使用 original_carrier 而非 carrier，使用 allocation_region 而非 location。地区和城市描述的是号码段的分配地，而非注册用户当前的所在地。

此外，请保留以下三个值：

• 查询时间戳，以便审核人员了解上下文的时效性。
• 结果：已完成（有值）、已完成（空值）或无法判定。
• 发送的输入，即确切的 E.164 字符串，这使得后续的审计和重新检查变得简单。

已完成的结果可能返回所有运营商字段均为空的情况。请将其保存为“已完成-空值”，不要将其视为失败，也不要将其作为账户任何信息的证据。当有人基于这些字段构建仪表板时，这种区分非常重要。

处理超时、无法判定的结果和被拒绝的输入

三种故障情况需要不同的代码路径，将它们合并是集成中最常见的错误。

公共 API 文档中记录了单次和多次请求的超时上限，以及每个账户共享的同步并发槽位数量。请将您的工作进程并发数保持在该共享预算之内，而不是在流量高峰期并行触发每个注册请求。失败或无法判定的查询不会扣费，因此重试策略无需担心重复计费，但仍应限制尝试次数（例如在一小时内分散尝试三次），之后将账户留给审核人员处理，并标记为无法判定状态。

将 API 密钥保存在服务器上

REST API 通过 X-API-Key 标头进行身份验证，该标头必须仅从受信任的服务器发送。切勿从浏览器 JavaScript 或移动应用包中调用查询；任何人都可能提取发送到客户端的密钥并消耗您的余额。

根据 OWASP Secrets Management Cheat Sheet 采取以下实用控制措施：

• 从密钥管理器或部署平台的密钥存储中加载密钥，而不是从源代码中加载。
• 仅授予查询工作进程读取权限。
• 按计划轮换密钥，并在怀疑泄露后立即更换。
• 切勿将密钥或完整的请求标头写入应用程序日志。
• 使用 GET /api/v1/balance 监控账户余额（该操作读取余额但不扣费），并对与注册量不符的余额骤降发出警报。

同时保护触发器本身。对您自己的注册端点进行速率限制，以防止自动表单提交演变成持续的付费查询。

在路由和审核中使用结果

将运营商和号码类型视为您团队所拥有的规则的输入，而非最终裁决。以下是团队使用的一些示例：

• 路由测试。 按原始运营商对新账户进行分组，并在您自己的指标中比较不同消息服务提供商在各组中的表现。
• 审核队列。 将号码类型超出产品预期（例如移动优先应用中的固定电话号码）的账户发送给审核人员，并附上上下文。
• 数据质量。 标记号码的国家代码与表单中选择的国家不一致的注册，以便支持团队要求用户更正。

将规则记录下来并确保其可逆。审核人员在查看被标记的账户时，应能看到查询值、查询时间和触发规则。由于运营商反映的是原始分配情况，因此结果绝不能单独作为电话能否接收验证码或属于注册本人的证明；请将其与您现有的验证步骤结合使用。

常见问题解答

团队如何检查集成前已注册的现有账户？

对于存量数据，请使用 POST /api/v1/batch-check，每组最多可包含 100 个 E.164 号码。结果将按输入顺序返回，每行都会说明是否存在正常结果。没有正常结果的行应标记为稍后重试，而不是记录为空。对于非常大的历史列表，最好作为按国家/地区提交的异步批量文件任务来处理。

后端如何避免为同一个号码付费两次？

维护一个以标准化 E.164 字符串为键、包含查询时间的缓存。当号码已有近期检查的已完成结果时，请复用该结果，而不是再次调用 API。分配上下文变化缓慢，因此许多团队仅在记录被编辑或存储的结果超过选定时间（例如几个月）时才进行刷新。

开发人员如何在上线前测试集成？

将工作进程指向具有独立 API 密钥和少量余额的测试配置，然后运行一组脚本化案例：有效的移动号码、固定电话号码、无法通过 E.164 标准化的输入以及强制超时。在切换生产流量之前，确认每条路径都写入了预期的结果状态，并且日志中没有出现任何密钥或标头。

了解更多

选择符合您工作流下一步的产品信息。

• 查看产品文档 →
• 联系团队 →