如何使用 E.164 号码进行 TG 注册状态检查

本技术指南介绍了如何集成同步 Telegram 注册状态检查，使用 E.164 格式的电话号码，并涵盖了 API 工作流程、批量处理及使用控制。

若要运行 Telegram 注册状态检查，请将 E.164 格式的电话号码提交至 TG Validator 平台。该服务提供同步响应，以指示该标识符的注册状态。

理解 Telegram 注册状态检查

TG Validator 是一个专注于 Telegram 验证的产品，而非多平台检查工具。当组织处理联系人列表或评估用户记录时，需要准确的路由信息。此信号有助于内部决策并支持联系人分段工作流程。由于该产品是同步的，单号码请求会在同一 HTTP 响应中返回一个结果。这种“即时响应”的工作流程有助于技术团队将检查直接集成到其路由逻辑中，而无需构建复杂的轮询机制。明确该信号的范围非常重要：已注册的结果仅确认该账号在 Telegram 平台上存在。团队可以将此可达性信号作为辅助输入，与其他检查结合使用，以支持其运营工作流程。

准备数据：E.164 格式

在向 API 提交请求之前，技术团队必须确保数据格式正确。TG Validator 平台要求所有提交的电话号码均使用 E.164 格式。E.164 是一种国际电话编号计划，确保公共交换电话网络上的每个设备都分配有唯一的标准化号码。通常，此格式包含一个加号，后跟国家代码和用户号码。以这种标准化格式提交号码是 API 的严格要求。如果请求包含格式不正确的标识符，系统将返回无效电话号码的错误代码。组织应在数据准备管道中实施规范化步骤，在发起检查前将本地或自定义的电话号码格式转换为严格的 E.164 字符串。此准备工作有助于保持 API 的稳定性能并减少被拒绝的请求数量。

执行注册状态检查

TG Validator 平台提供用于执行检查的同步 REST API。记录的请求契约使用 POST /api/v1/check 端点。为了进行身份验证，请求必须包含包含账户凭据的 X-API-Key 标头，以及 Content-Type: application/json 标头。JSON 有效负载需要两个特定字段：service_type 设置为 tg，identifier 包含 E.164 格式的电话号码。该服务支持同步单号码检查，每个请求处理一个标识符。对于处理较大数量的组织，同步批量端点允许在单个请求中接受最多 100 个标识符。此批量端点会在同一 HTTP 响应中返回整个批次的结果，或者作为一个整体失败，从而保持“即时响应”的工作流程，无需任务提交、轮询、回调或文件下载。处理成功后，外部响应信封包含 code、msg 和 data 字段。公共 data 对象包含 service_type、identifier 和 registered 布尔字段。对于 Telegram 服务类型，API 仅返回此 registered 字段；它不返回头像或业务字段。registered 布尔值仅在完成且已确定的检查中提供。如果检查无法确定，API 将返回非零业务代码，且不包含已完成的结果对象。

管理 API 操作与可靠性

在集成 TG Validator API 时，技术团队必须考虑使用控制和错误处理。系统使用每用户并发和超时控制，而非每分钟请求速率限制。团队应查阅当前的 API 文档，为这些特定行为设计安全的客户端处理逻辑。如果系统提交的请求超过了可用的并发槽位，API 将返回并发限制拒绝。这些拒绝发生在检查创建之前，因此不会生成已完成的检查结果。公共 API 文档列出了开发者应处理的特定错误代码，包括不支持的服务类型、无效的 JSON 正文、无效的电话号码、缺失或无效的 API 密钥、余额不足、并发槽位已满、检查超时以及验证服务维护。该服务的计费按检查次数计算。如果检查失败或处于未确定状态（导致非零业务代码），系统会自动为该特定请求处理退款。并发拒绝不计费。

通过开发者仪表板监控工作流程

为了支持 API 操作，TG Validator 提供了 SaaS Web 仪表板。此界面有助于团队管理集成并监控使用模式。仪表板支持 API 密钥管理，帮助管理员生成和轮换 X-API-Key 标头所需的凭据。操作员还可以使用仪表板查看账户余额、检查历史记录和使用报告。界面显示最近的检查、余额消费详情和七天趋势。这种可见性有助于组织跟踪验证量、监控特定错误代码的频率，并确保账户保持足够的余额以支持其并发需求。

与支持 MCP 的 AI 客户端集成

除了标准的 REST API 外，TG Validator 还提供官方的模型上下文协议 (MCP) 服务器。该服务器可通过网站的 /mcp 路径通过流式 HTTP 和 JSON-RPC 访问。它支持 Claude Code、Cursor 或 Claude Desktop 等支持 MCP 的 AI 客户端与检查服务进行交互。MCP 集成使用客户现有的 API 密钥，无需单独的账户或凭据。它与 REST API 共享完全相同的产品、余额、身份验证、并发限制、超时、计费和结果语义。向 AI 助手公开的工具包括列出可用产品、检查单个 E.164 号码、同步检查最多 100 个 E.164 号码的小批量数据以及查询账户余额。这些 MCP 调用保持实时和同步，利用相同的“即时响应”工作流程，无需创建异步任务。

常见问题解答

Telegram 注册结果指示什么？

它确认提交的 E.164 电话号码是否与 Telegram 账号关联。此信号有助于团队路由记录并对联系人进行分段。

可以一次检查多个电话号码吗？

可以，平台通过同步批量端点支持批量处理。该端点在单个请求中接受最多 100 个 E.164 标识符。系统处理请求并在同一 HTTP 响应中返回整个批次的结果，或者作为一个整体失败。

失败的检查会从我的账户中扣费吗？

不会，计费严格按检查次数计算，系统会自动为任何失败或未确定的检查退款。