API 文档

在 sms.tc 上自动购买号码并完成短信验证。提供两种接口：现代化的 REST API，以及可直接替换的 SMS-Activate 兼容接口——无需修改任何代码，即可将您现有的 SMS-Activate 软件指向 sms.tc。

获取 API 密钥兼容 SMS-Activate

概述

sms.tc 是一个多供应商聚合平台：通过同一个 API 即可获取多家上游供应商的号码，并按我们的定价计费。您可以选择最适合自己技术栈的接口。

REST API

基于 HTTP 的 JSON 接口，推荐用于新的集成。

https://sms.tc/api/v1

SMS-Activate

与 SMS-Activate 客户端兼容的纯文本协议。

https://sms.tc/stubs/handler_api.php

获取 API 密钥

1登录后打开“个人资料 → API”页面。
2生成密钥。密钥仅显示一次——请复制并妥善保存。
3重新生成会吊销旧密钥，并通过邮件发送新密钥。您还可以将密钥限制为特定 IP 地址使用，并设置到期日期。

获取 API 密钥

身份验证

每个请求都必须包含您的 API 密钥。REST API 从请求头读取密钥；SMS-Activate 接口从 api_key 查询参数读取密钥。

REST

Authorization: Bearer smstc_live_xxxX-Api-Key: smstc_live_xxx

SMS-Activate

?api_key=smstc_live_xxx

核心概念

标准代码

国家使用 SMS-Activate 数字 ID（0=俄罗斯，1=乌克兰…），服务使用简短代码（tg、wa、ig…）。可通过 catalog / getCountries / getServicesList 接口查询。

货币

所有价格和余额均以 USD（ISO 840）计。

余额

购买费用从您的 sms.tc 余额中扣除。失败或超时的激活会自动退款。

短信成功率 (rate)

报价响应中可能包含 rate 字段：表示我们自身已结算的激活中成功收到短信的比例（百分比，或 null）。按供应商 + 服务 + 国家分别计算，仅在至少有 10 次已结算激活时显示，每天刷新一次。如需按供应商细分的数据，请使用 /activations/offers/providers。

REST API

基础 URL 为 https://sms.tc/api/v1。使用 Bearer / X-Api-Key 请求头进行身份验证。响应格式为 JSON。

GET/activations/offersList available numbers (service → country → price/count/rate).

GET/activations/offers/providersPer-provider offers (provider, operator, price, stock, SMS success rate). Requires service + country.

POST/activationsBuy a number. Body: { service, country, operator? }.

GET/activations/{id}Get activation status + received SMS code.

GET/emailsList email activations.

POST/emailsBuy an email activation. Body: { site, domain }.

POST/emails/batchBuy email activations in bulk (count 1–10).

GET/emails/{id}Check an email activation.

DELETE/emails/{id}Cancel an email activation.

POST/emails/{id}/reorderReorder an email activation.

GET/emails/domainsList available email domains.

GET/catalog/countriesCanonical country list (SMS-Activate ids).

GET/catalog/servicesCanonical service list (short codes).

GET/catalog/pricesPrices by country/service, incl. SMS success rate (rate).

GET/rent/offersRentable services for a country + duration.

POST/rentRent a number. Body: { service, country, duration }.

GET/rent/{id}Get a rent order + its SMS.

POST/rent/{id}/prolongExtend a rent. Body: { duration }.

示例 · cURL

# 1) 列出可用号码
curl https://sms.tc/api/v1/activations/offers \
  -H "Authorization: Bearer smstc_live_xxx"

# 2) 购买号码（Telegram，国家 6）
curl -X POST https://sms.tc/api/v1/activations \
  -H "Authorization: Bearer smstc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":6}'

# 3) 查询验证码
curl https://sms.tc/api/v1/activations/123456 \
  -H "X-Api-Key: smstc_live_xxx"

SMS-Activate 兼容 API

单一接口 /stubs/handler_api.php，通过 action 查询参数分发请求——完整复刻 SMS-Activate 协议，现有合作伙伴软件无需改动即可使用。响应为纯文本（V2 / 列表类操作返回 JSON）。

action	返回值
getBalance	ACCESS_BALANCE:12.50
getNumber	ACCESS_NUMBER:<id>:<phone>
getNumberV2	JSON (activationId, phoneNumber, …)
getStatus	STATUS_WAIT_CODE · STATUS_OK:<code>
getStatusV2	JSON (sms, call, …)
setStatus	ACCESS_READY · ACCESS_RETRY_GET · ACCESS_ACTIVATION · ACCESS_CANCEL
getActiveActivations	JSON (active list)
getHistory	JSON (history)
getPrices	JSON (prices by country/service)
getCountries	JSON (countries)
getServicesList	JSON (services)
getOperators	JSON (operators)
getAllSms	JSON (all SMS for an activation)
finishActivation	204
cancelActivation	204
reactivate / reactivateOptions	JSON · provider-dependent
getRentNumber / getRentServicesAndCountries / serviceCountRent	JSON · provider-dependent
prolong / prolongOptions / prolongHistory	JSON · rent only

setStatus

1 报告已就绪3 请求再发一条短信6 完成激活8 取消并退款

示例

# 获取号码
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=getNumber&service=tg&country=6
→ ACCESS_NUMBER:123456:628712345678

# 查询状态 / 验证码
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=getStatus&id=123456
→ STATUS_OK:12345

# 完成 (6) 或取消 (8)
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=setStatus&id=123456&status=8
→ ACCESS_CANCEL

错误代码

SMS-Activate 接口返回纯文本标识（HTTP 200）。REST API 返回带有 HTTP 状态码和错误代码的 JSON。

NO_KEY缺少 API 密钥。

BAD_KEYAPI 密钥无效、已过期或不允许从您的 IP 使用。

BAD_ACTION未知的 action 参数。

BAD_SERVICE未知的服务代码。

NO_NUMBERS该服务/国家暂无可用号码。

NO_BALANCE余额不足。

WRONG_ACTIVATION_ID激活 ID 缺失或格式错误。

NO_ACTIVATION在您的账户中未找到该激活。

BAD_STATUS无效的 setStatus 值。

EARLY_CANCEL_DENIED暂时无法取消（未达到最短保留时间）。

ACTION_NOT_AVAILABLE所选供应商不支持此操作。

规范文档

完整的机器可读规范和入门指南可在下方获取。

OpenAPI (YAML) README