规划 Telegram 实时电话验证 API 工作流

本技术指南介绍如何使用 TG Validator 设计实时电话验证 API 工作流，内容涵盖同步单号与多号接口、并发限制、E.164 格式化以及信号解读。

TG Validator 的验证工作流以实时检测为基础：单个 E.164 号码提交到 POST /api/v1/check，最多 100 个号码提交到同步多号接口 POST /api/v1/batch-check，完成的注册结果都在发起请求的同一个 HTTP 响应中返回。请按照 API 文档在客户端控制并发。远超一次实时请求的整份名单，另有异步批量任务可作为补充。

理解同步验证模型

TG Validator 的主模型是同步的。单个号码使用 POST /api/v1/check，最多 100 个号码使用同步多号接口 POST /api/v1/batch-check，完成结果在同一个 HTTP 响应中返回，没有任务提交、轮询、回调或下载步骤，也没有同一国家的要求。作为整份大名单的兜底，另有异步批量任务（/api/v1/bulk-tasks）可用：上传文件、获得任务 id、轮询任务状态并在完成后下载结果文件；提交任务时要选定号码所属的国家或地区，一份名单应基本属于这一个国家。本文后续内容聚焦同步路径。

准备验证数据

在发起请求之前，请确保数据集中的所有电话号码均符合 E.164 国际编号计划。API 要求使用 X-API-Key 和 Content-Type: application/json 标头。单号请求使用 POST /api/v1/check，请求体包含 service_type=tg 和一个 E.164 格式的 identifier；多号请求使用同步多号接口 POST /api/v1/batch-check，请求体包含 service_type=tg 和最多 100 个 E.164 号码组成的 identifiers 数组。由于 TG Validator 专注于 Telegram，服务类型必须始终设置为 tg。

构建实时电话验证 API 工作流

管理吞吐量是实时电话验证 API 工作流中最关键的部分。TG Validator API 会限制单个账号同时在途的检查数量，当前上限见 API 文档。您的客户端应用程序必须对请求进行限流，以保持在该边界之内。如果您的系统超过这些阈值，API 将拒绝请求。并发限制拒绝与超时不会扣费，也不会产生检查结果，这意味着您的应用程序应设计为能够安全地暂停并重试这些特定请求。

解读注册信号

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

监控与错误处理

使用 API 响应代码处理可重试的失败；当前错误代码与限制请以 API 文档为准。

常见问题解答

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

API 只允许每个账号进行有限数量的并发检查，具体上限见 API 文档。如果超过此限制，API 将拒绝请求，且不会扣除余额或产生结果。您的应用程序应捕获并发错误代码，短暂暂停，然后重试请求。

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

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

名单超过一次请求的上限时，工作流应如何处理？

以同步多号接口为主路径，每次最多 100 个号码，并保持在文档规定的并发上限内。远超这一规模的整份名单，另有异步批量任务可用（上传、等待、下载）；提交时要选定号码所属的国家或地区，一份名单应基本属于这一个国家，每个产品的最小与最大号码数见 API 文档。

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

失败、超时或无法判定的检测不会保留扣费；具体计费规则请以价格页和 API 文档为准。