Документация API

Автоматизируйте покупку номеров и SMS-верификацию на sms.tc. Два интерфейса: современный REST API и полностью совместимый с SMS-Activate эндпоинт — подключите своё ПО для SMS-Activate к sms.tc без изменений в коде.

Получить API-ключ Совместимо с SMS-Activate

Обзор

sms.tc — мультипровайдерный агрегатор: единый API даёт доступ к номерам нескольких поставщиков по нашим ценам. Используйте тот интерфейс, который подходит вашему стеку.

REST API

JSON по HTTP. Рекомендуется для новых интеграций.

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 — из query-параметра api_key.

REST

Authorization: Bearer smstc_live_xxxX-Api-Key: smstc_live_xxx

SMS-Activate

?api_key=smstc_live_xxx

Основные понятия

Канонические коды

Страны обозначаются числовыми ID SMS-Activate (0=Россия, 1=Украина…), а сервисы — короткими кодами (tg, wa, ig…). Узнать их можно через эндпоинты catalog / getCountries / getServicesList.

Валюта

Все цены и балансы указаны в USD (ISO 840).

Баланс

Покупки оплачиваются с вашего баланса sms.tc. Неудачные активации и активации с истёкшим временем возвращаются автоматически.

Доля успешных SMS (rate)

Ответы с предложениями могут содержать поле rate — долю наших завершённых активаций, на которые пришло SMS (% или 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"

API, совместимый с SMS-Activate

Единый эндпоинт /stubs/handler_api.php, действие задаётся query-параметром action. Он повторяет протокол SMS-Activate, поэтому существующее партнёрское ПО работает без изменений. Ответы — простой текст (или JSON для V2 и действий со списками).

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 запросить ещё одно SMS6 завершить активацию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 возвращает JSON с HTTP-статусом и кодом ошибки.

NO_KEYAPI-ключ не указан.

BAD_KEYAPI-ключ недействителен, истёк или не разрешён для вашего IP.

BAD_ACTIONНеизвестный параметр action.

BAD_SERVICEНеизвестный код сервиса.

NO_NUMBERSНет доступных номеров для этого сервиса/страны.

NO_BALANCEНедостаточно средств на балансе.

WRONG_ACTIVATION_IDID активации не указан или имеет неверный формат.

NO_ACTIVATIONАктивация не найдена в вашем аккаунте.

BAD_STATUSНедопустимое значение setStatus.

EARLY_CANCEL_DENIEDОтменить пока нельзя (минимальное время удержания ещё не прошло).

ACTION_NOT_AVAILABLEЭто действие недоступно для выбранного поставщика.

Спецификация

Полная машиночитаемая спецификация и руководство по началу работы доступны ниже.

OpenAPI (YAML) README