开发者 API 文档：授权码接入完整申请流程

接口与快速开始

基址：https://gettgapi.com/api/open/v1。通过你的服务器调用，使用同一张授权码的剩余次数。无需客户注册账号，不需要 Telegram 客户端 API、两步认证密码或设备授权。每次申请仍需要号码持有人提供开发者门户验证码。

下载 OpenAPI 3.1 文档 · 下载 Python 完整示例 · 咨询接入

1. 用授权码查询 GET /balance，确认剩余次数。
2. POST /applications 提交号码、应用资料及使用授权，保存返回的申请 id。
3. 每隔至少 5 秒查询申请。waiting_code 且 challenge 不为空时，让号码持有人提供本轮验证码。
4. POST /applications/{id}/code 提交验证码，继续查询。
5. 状态为 succeeded 后读取 GET /applications/{id}/result。
6. 在你的系统安全保存结果，确认保存成功后调用删除接口。删除后无法补领。

已有应用时返回已有结果；没有应用时尝试创建。平台不保证所有号码都能申请成功，限制或异常可能需要人工处理。

授权与请求格式

每个业务请求必须携带：

Authorization: Bearer YOUR_AUTHORIZATION_CODE
Accept: application/json

写入请求另外携带：

Content-Type: application/json
Idempotency-Key: 2e8718cd-84ef-4830-b273-66b3afdd682d

授权码可以带原有连字符，字母不区分大小写。不得放在 URL、网页前端、日志或公开仓库中。接口不使用网页 Cookie 或 CSRF Token，不开放跨站 CORS；授权码泄漏等同服务权限泄漏，应立即联系发放方停用。

仅使用 HTTPS。请求体最多 8 KiB；未知字段、错误类型或无效格式会被拒绝。所有时间字段为 Unix 秒；null 表示当前无此数据，不能当成 0。

成功响应统一为：

{"data": {"available": 1}, "request_id": "服务端生成的追踪编号"}

上面是结构示意，完整字段见各接口和 OpenAPI。响应头 X-Request-ID 与 request_id 一致；响应禁止缓存。request_id 用于联系客服排查，不能用作下次写入的幂等键。

授权码余额

GET /balance，成功 HTTP 200。

{
  "data": {
    "total": 10,
    "available": 8,
    "reserved": 1,
    "consumed": 1,
    "revoked": 0,
    "max_concurrent": 2,
    "result_retention_seconds": 1800
  },
  "request_id": "示例追踪编号"
}

total = available + reserved + consumed + revoked。reserved 为正在处理的预占次数，consumed 为已成功使用次数，revoked 为已收回次数。单张授权码同时最多两个预占申请，网页与接口共用这一限制及余额。

查询余额不消耗次数、不兑换授权码。次数用完后仍可通过原授权码读取接口申请及清除临时结果；停用或暂停后禁止访问，请联系发放方处理。

创建申请

POST /applications，成功或幂等重试成功均为 HTTP 202。

{
  "phone": "+12025550123",
  "title": "My Telegram App",
  "short_name": "myapp2026",
  "consent": true
}

HTTP 202 表示申请已受理，不代表验证码已送达或已经成功。返回申请对象见下一节。首次受理预占 1 次，成功才扣次。明确失败、创建前取消或重复结果会退回预占；结果未确认时保留预占并继续核对。

同一授权码、同一号码的未结束或成功记录不会重复创建。资料相同的接口记录会返回原申请；不同资料或原记录属于网页会话时返回 PHONE_ALREADY_USED。已删除结果的号码仍保留使用记录，不能用换幂等键的方式补领或重复计费。

申请查询与状态

GET /applications/{id}，成功 HTTP 200，返回申请对象：

{
  "data": {
    "id": "28f4a4d0-e69f-48d4-b520-85c479873b1f",
    "phone_mask": "+120••••123",
    "title": "My Telegram App",
    "short_name": "myapp2026",
    "status": "waiting_code",
    "message": "请在 Telegram 中查看验证码，并在下方输入。",
    "challenge": {"id": "c8a34997-38bd-4a1c-90bb-5baac7dbabcc", "expires_at": 1790998200, "attempts_remaining": 5},
    "poll_after_seconds": 5,
    "retry_at": null,
    "result_expires_at": null,
    "quota": "reserved",
    "created_at": 1790997600,
    "updated_at": 1790997605
  },
  "request_id": "示例追踪编号"
}

quota 为 reserved、consumed 或 released。challenge 仅在当前可输入验证码时存在；尝试失败或重新验证后，其 id 可能变化，必须重新查询。retry_at 是建议等待至的时间，不承诺该时刻必定完成。poll_after_seconds=0 表示无需持续自动轮询。

GET /applications?limit=20&before={id} 提供分页列表；limit 为 1–50，默认 20，before 可省略。结果按创建时间和 id 倒序，返回 data.items 与 data.next_before，后者为 null 时结束。只显示本授权码通过接口创建的记录；网页结果和其他授权码记录不可见。

提交验证码

POST /applications/{id}/code，成功 HTTP 202，返回更新后的申请对象。

{"challenge_id": "c8a34997-38bd-4a1c-90bb-5baac7dbabcc", "code": "Ab_cd-12"}

code 为 3–64 个可打印 ASCII 字符，不含空格，区分大小写。仅提交号码持有人本轮收到的开发者门户验证码；不提交两步密码，不使用旧验证轮次。单轮最多 5 次输入，验证码有效期以 challenge.expires_at 为准。

成功受理只代表已进入验证队列。若重试同一 HTTP 请求，保持同一个幂等键与完全相同参数。若验证码确实错误，先查询新 challenge，然后用新幂等键提交正确验证码。

取消申请

POST /applications/{id}/cancel，JSON 为 {"confirm": true}，成功 HTTP 200，返回申请对象。

仅排队、等待验证码、等待重试等允许取消的状态可操作。正在执行或结果未确定的申请不能取消，返回 STATE_CONFLICT；此时继续查询，或联系人工。已取消和明确失败的申请重复取消不会再次退次数。

读取结果与确认删除

GET /applications/{id}/result，成功 HTTP 200：

{
  "data": {"api_id": 12345678, "api_hash": "0123456789abcdef0123456789abcdef", "expires_at": 1790999400},
  "request_id": "示例追踪编号"
}

示例不是可用凭据。结果默认仅提供 30 分钟交付窗口，以实际 expires_at 为准；不会因读取而续期。可多次读取，读取不会扣次数。请不要将 Hash 放入访问日志、浏览器分析、URL 或客服聊天。

保存成功并确认可用后，调用 POST /applications/{id}/result/deletion，JSON 为 {"confirm": true}，成功 HTTP 200：

{
  "data": {"application_id": "28f4a4d0-e69f-48d4-b520-85c479873b1f", "deleted_at": 1790998000, "status": "deleted"},
  "request_id": "示例追踪编号"
}

删除会清除平台用于交付的临时 API 副本，保留使用次数和必要的处理记录，不会删除你的 Telegram 官方应用或你的系统已保存的副本。删除完成、交付过期或临时交付介质失效后，再次读取返回 HTTP 410。删除请求可安全重试；应先保存，后删除。

幂等、限流和重试

所有 POST 必须使用 Idempotency-Key：16–80 位字母、数字、点、下划线、冒号或连字符，建议 UUID。业务系统先持久化这个键，再发请求。每个不同操作生成新键；网络超时、断线或 5xx 后重试原操作时复用原键。

同一授权码的键全局绑定原操作和参数，不可跨接口复用。重放返回同一申请的当前状态，不保证字节级相同响应；不会重复发码、预占或扣次。结果删除后该键也不会创建新申请。不要以“超时就换键”处理未知响应。

429 和 503 按响应的 Retry-After 等待，建议指数退避并加入少量随机延迟。5xx、连接超时和读取超时都可能发生在服务器已经完成写入之后；复用原键重试，不能据此认定未扣次。4xx 通常先修正输入或查询进度，不自动无限重试。

服务过载或暂无法执行新申请时返回 503，未受理的请求不占次数。系统故障后会恢复持久任务，并核对已经提交但响应未知的申请；不会盲目再次创建。单机部署仍存在主机和机房故障边界，本接口未承诺多机容灾 SLA。

错误响应与错误码

{
  "error": {"code": "RATE_LIMITED", "message": "请求过于频繁，请等待后重试。", "retryable": true, "retry_after_seconds": 60},
  "request_id": "请提供此编号以便排查"
}

程序以 code 和 HTTP 状态判断，不解析 message，也不依赖内部实现。上游异常不会原样返回。可重试错误同时带 Retry-After；追踪编号不含授权码和申请结果。

接入示例与安全保存

下载页首 Python 示例，要求 Python 3.10+ 与 requests。它会在本地受限目录保存请求状态，以相同幂等键恢复未确认请求，并在结果安全落盘后询问是否删除平台临时副本。不要把工作目录加入版本库。

python3 -m pip install requests
python3 gettgapi_client.py --work-dir ./private-application

授权码和验证码在终端隐蔽输入，不写入示例日志；程序会询问号码和 short_name。下次使用同一目录会恢复这次操作；为另一号码申请请使用新的目录。请先在自己可控制的号码上测试，HTTP 受理和自动化测试不能替代真实号码验证。

请在自己的服务中加密保存结果、限制员工读取权限，并避免在客户端公开授权码。发放给不同客户时应使用各自独立授权码；同一授权码的持有人有权管理该码的全部接口申请。

需要接入协助，请访问 https://gettgapi.com/help#contact，提供 request_id 和申请 id 即可，不发送验证码、授权码全文或 API Hash。