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

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

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

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

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

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

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

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

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

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

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

Webhooks

Webhook на получение SMS

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

Как это работает

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

Практические правила

Обрабатывайте webhook быстро и возвращайте 2xx только после успешного приёма.
Если нужна тяжёлая обработка, сначала сохраните payload в очередь или БД, а затем отвечайте.
Для отладки используйте тестовый webhook из бота, а не реальную покупку номера.

Пример payload

POST https://your-app.example/webhooks/hush
Content-Type: application/json

{
  "action": "postWebhook",
  "sms_content": "Your code: 482913",
  "sender_number": "",
  "recipient_number": "+447700900123",
  "activation_id": "66173a6d8a5f0f36e4a1c123",
  "service": "tg",
  "country": "0",
  "status": "sms_received",
  "test": false,
  "received_at": "2026-04-09T12:34:56Z"
}

Что значат поля

sms_content — текст SMS, если провайдер отдаёт только код, сюда приходит код.
recipient_number — купленный виртуальный номер.
activation_id — ID заказа в Hush SMS, его удобно связывать с вашим заказом.
test — true только у тестового webhook из бота.
sender_number может быть пустым, если upstream не передал номер отправителя.

Тестовый webhook

Кнопка Тестовый webhook отправляет такой же POST, но с test: true, тестовым номером и демонстрационным кодом 123456.

{
  "action": "postWebhook",
  "sms_content": "123456",
  "sender_number": "Hush SMS",
  "recipient_number": "+10000000000",
  "activation_id": "test-webhook",
  "service": "tg",
  "country": "0",
  "status": "sms_received",
  "test": true,
  "received_at": "2026-04-09T12:34:56Z"
}

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’ам, параметрам, схемам и примерам ответов.

Загрузка…