Hush SMS · API

Quick Start

Hush SMS API

REST API для каталога, покупки виртуальных номеров, проверки статуса и безопасной работы через идемпотентные запросы.

Base URL https://api.hush-sms.com
Авторизация Authorization: Bearer <api_key>
Первый безопасный запрос GET /v1/me

Первый запрос

Проверьте, что ключ работает и привязан к пользователю. Это лучший старт до покупки номера.

curl -X GET "https://api.hush-sms.com/v1/me" \
-H "Authorization: Bearer <api_key>"

Покупка номера

Для создания заказа обязателен Idempotency-Key. Повтор с тем же ключом защищает от двойной покупки.

curl -X POST "https://api.hush-sms.com/v1/numbers" \
-H "Authorization: Bearer <api_key>" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-H "Content-Type: application/json" \
-d '{"service":"tg","country":0}'

Что важно помнить

  • Ключ берётся в Telegram-боте, в разделе API.
  • Перед покупкой удобно запросить список сервисов и стран.
  • После создания заказа проверяйте статус по order_id.
  • Отмена доступна не для всех статусов и зависит от cooldown.
Common Flows

Типовой сценарий работы

Такой порядок запросов покрывает основной поток интеграции: от выбора сервиса до статуса и отмены.

1

Проверить доступ и баланс

Сначала запросите GET /v1/me, чтобы убедиться, что ключ активен, а баланс и профиль читаются корректно.

2

Найти сервис и страну

Получите сервисы через GET /v1/services, затем страны и цены через GET /v1/services/{code}/countries.

3

Создать заказ

Вызовите POST /v1/numbers с Idempotency-Key. Это защищает от повторной покупки при ретраях.

4

Следить за статусом

Используйте GET /v1/numbers/{order_id} и GET /v1/numbers для получения активных заказов и SMS-кодов.

Вебхуки

Webhook: входящая SMS

Событие отправляется при получении входящей SMS на номер, связанный с активной активацией. Настройка выполняется в Telegram-боте: Информация → API → Webhooks.

Тело запроса

Обязательно
application/json

JSON с данными о полученной SMS.

Практика

  • Можно указать только один HTTPS-адрес на пользователя.
  • Тестовый webhook доступен в том же меню и ограничен по частоте: не чаще одного раза в 60 секунд.
  • Возвращайте любой код 2xx как подтверждение успешной обработки.
  • Если webhook не принимается, возможны повторные попытки доставки.

Поля

ПолеТипОписание
activationIdstringID активации. Обязательное поле.
countryintegerID страны. Обязательное поле.
receivedAtstring · date-timeВремя получения SMS. Обязательное поле.
servicestringКод сервиса. Обязательное поле.
textstring | nullТекст SMS. Обязательное поле.
codestring | nullКод из SMS.

Ответы

СтатусОписание
200Webhook успешно принят. Рекомендуемый ответ.
defaultWebhook не принят, доставка может быть повторена.

Пример запроса

{
  "activationId": "123456",
  "service": "tg",
  "text": "Your code is 12345",
  "code": "12345",
  "country": 2,
  "receivedAt": "2025-12-16T10:30:00.000000Z"
}

Статус: 200

Webhook успешно принят.

Статус: default

Без тела ответа.

Errors & Statuses

Основные ошибки и статусы

Эти коды встречаются чаще всего и на них обычно нужно опираться в клиентской логике.

Коды ошибок

КодКогда возникает
missing_tokenНе передан API-ключ в заголовке Authorization.
forbiddenКлюч невалиден, неактивен или не привязан к пользователю.
not_availableДля выбранного сервиса и страны сейчас нет доступных номеров.
missing_idempotency_keyПри покупке номера не передан Idempotency-Key.
too_earlyОтмена запрошена раньше допустимого времени после создания заказа.
upstream_timeoutПревышено время ожидания ответа.

Статусы заказа

СтатусЗначение
pendingЗаказ создан, номер выдан, SMS ещё не получена.
sms_receivedХотя бы одна SMS уже доступна в заказе.
finishedРабота с заказом завершена.
canceledЗаказ отменён, номер освобождён.
refundedСредства были возвращены пользователю.
Reference

Полная схема API

Ниже находится полный интерактивный reference по всем endpoint’ам, параметрам, схемам и примерам ответов.

Загрузка…
Загрузка документации API