规划批量电话验证 API 工作流

本技术指南旨在介绍如何使用 TG Validator 设计同步批量电话验证 API 工作流，内容涵盖速率限制、E.164 格式化以及信号解读。

要使用 TG Validator 实现批量电话验证 API 工作流，请将您的应用程序设计为同步处理电话号码，并遵守每分钟 200 次请求的速率限制和 3 个并发检查的限制。通过向 API 提交 E.164 格式的号码，您将收到即时的注册状态信号，该信号有助于您的内部审核流程，且无需复杂的批量处理基础设施。

理解同步验证模型

TG Validator 仅在 Telegram 注册检查的同步请求-响应模型下运行。您的应用程序无需上传文件进行异步批量处理，而是在同一个 HTTP 响应周期内发送单个请求并接收单个结果。这种架构要求客户端逻辑遍历联系人列表，按顺序或以受控的并发方式发送单个检查请求。

准备验证数据

在发起请求之前，请确保数据集中的所有电话号码均符合 E.164 国际编号计划。API 要求发送包含 X-API-Key 标头和 Content-Type: application/json 标头的 POST /api/v1/check 请求。JSON 正文必须将服务类型指定为 tg，并包含作为标识符的 E.164 号码。由于 TG Validator 是专注于 Telegram 的单一平台产品，因此服务类型必须始终设置为 tg。

构建批量电话验证 API 工作流

管理吞吐量是批量电话验证 API 工作流中最关键的部分。TG Validator API 强制执行每分钟 200 次请求的严格速率限制，并允许每个用户最多进行 3 个并发检查。您的客户端应用程序必须对请求进行限流，以保持在这些边界之内。如果您的系统超过这些阈值，API 将拒绝请求。速率和并发限制导致的拒绝不会扣费，也不会产生检查结果，这意味着您的应用程序应设计为能够安全地暂停并重试这些特定请求。

解读注册信号

API 会返回一个包含代码、消息和数据响应的封装。在此封装中，Telegram 注册状态位于 data.registered 字段中。该结果仅作为检查时的账户存在信号。本产品不返回头像或业务字段，从而使负载完全集中在注册状态上。

监控与错误处理

通过 TG Validator 仪表板可以实现运营监督，该仪表板提供 API 密钥、检查历史记录、使用报告、近期检查、余额支出和 7 天趋势的可视化。在设计错误处理逻辑时，请考虑特定的 API 错误代码，例如无效的 JSON 正文、无效的电话号码、缺失的 API 密钥、余额不足或验证服务维护。计费采用按次付费模式，任何失败或未确定的检查都会自动退款。如需测试初始集成，新账户可联系支持团队领取 0.10 美元的试用余额。

常见问题解答

API 的同步特性如何影响批量处理？

批量处理必须在客户端通过遍历记录并发送单个请求来管理，同时需遵守并发和速率限制。

如果我达到了并发限制该怎么办？

API 最多允许 3 个并发检查。如果超过此限制，API 将拒绝请求，且不会扣除余额或产生结果。您的应用程序应捕获并发错误代码，短暂暂停，然后重试请求。

“已注册”状态是否确认用户可达？

否。注册信号仅表示在检查那一刻 Telegram 账户的存在情况。

失败的检查在计费方面如何处理？

TG Validator 使用按次付费的计费模式。如果检查失败或返回未确定的结果，费用将自动退还至您的账户余额。