如何实时验证 CSV 中的电话号码是否注册 Telegram

本技术指南介绍如何使用 TG Validator 实时验证 CSV 中的电话号码是否注册 Telegram，重点涵盖数据准备、同步单号与多号接口、并发管理及结果解读。

TG Validator 以实时验证为主：把一个 E.164 号码提交到 POST /api/v1/check，或把最多 100 个号码提交到同步多号接口 POST /api/v1/batch-check，完成结果都在同一个 HTTP 响应中返回。验证 CSV 时，先把号码列标准化为 E.164，再通过多号接口按每次最多 100 个提交，并按照 API 文档控制客户端并发。远超一次实时请求的整份文件，也可以作为异步批量任务上传。

准备验证数据

在处理联系人 CSV 文件时，第一步是标准化输入。TG Validator 要求所有提交的电话号码必须采用 E.164 格式。这种国际编号方案确保每个号码在全球范围内是唯一的，通常以“+”开头，后跟国家代码和用户号码。在发起 API 请求之前，将 CSV 列标准化为 E.164 格式，可以防止出现电话号码无效的错误，并确保系统能够准确检查 Telegram 的注册状态。

理解 TG Validator API 工作流

TG Validator 的主模型是同步请求-响应，单号与多号检测都是如此。单号使用 POST /api/v1/check；CSV 中最多 100 个 E.164 号码可通过同步多号接口 POST /api/v1/batch-check 携带 service_type=tg 提交；两种接口都在同一个 HTTP 响应中返回结果，没有任务提交、轮询或下载步骤。 若要检查号码，请向 POST /api/v1/check 发送请求，并包含 X-API-Key 请求头和 Content-Type: application/json。JSON 正文必须包含 "service_type": "tg" 以及包含 E.164 格式号码的 "identifier"。

管理吞吐量与 API 限制

用同步多号接口逐段处理 CSV，每次最多 100 个号码，并遵守平台的 API 使用控制。TG Validator 会对每个用户施加并发限制；在决定脚本同时发出多少请求之前，请先在 API 文档中确认当前数值。远超一次实时请求的整份文件，另有异步批量任务可用（上传、等待、下载），其当前限制见 API 文档。 如果您的脚本超过这些阈值，API 将返回特定的错误代码，指示所有并发槽位已被占用，或检查未在时间预算内完成。这类拒绝不会被扣费，也不会产生检查结果。在 CSV 处理脚本中实现延迟或并发限制队列，可确保执行过程顺畅且不会产生不必要的错误。

解读结果与处理错误

API 会返回一个包含 code、msg 和 data 的文档化响应包。对于 Telegram 检查，data.registered 字段提供了账户存在信号。 对于完成的 Telegram 检测，公开 data 仅包含 service_type、identifier 和 registered；内部记录、交易、状态和计费字段不会对外返回。

常见问题解答

验证时电话号码应采用什么格式？

所有电话号码必须以 E.164 格式提交，该格式以“+”开头，后跟国家代码和用户号码，确保每个号码在全球范围内是唯一的。

如果我超过了并发限制会怎样？

如果超出文档记录的并发限制，API 将返回错误代码。这些基于限制的拒绝请求不会被扣费，也不会生成检查结果。

可以一次请求检测多个号码吗？

可以。同步多号接口 POST /api/v1/batch-check 一次最多接收 100 个 E.164 号码，完成结果在同一个 HTTP 响应中返回。远超这一规模的整份文件，另有异步批量任务可用（提交时选定号码所属国家，一份名单应基本属于这一个国家），但同步接口仍是主要的检测方式。