Замена API SMS-Activate: как перейти на Hush SMS API

Как перейти с API SMS-Activate на Hush SMS: соответствие методов и статусов

Коротко

API Hush SMS — это REST с JSON, а не текстовые ответы вида ACCESS_NUMBER. Логика та же: купить номер, дождаться кода, завершить или отменить заказ. getNumber заменяет POST /v1/numbers, getStatus — GET /v1/numbers/{id}, а setStatus 6 и 8 — завершение и отмена. Ключ выдаётся в разделе API бота @HushNumBot.

После закрытия SMS-Activate многие интеграции остались без поставщика номеров. Если ваш код работал с handler API SMS-Activate, перенести его на Hush SMS можно быстро: принципы те же, меняются адреса, формат ответов и несколько правил.

Что меняется в целом

REST и JSON вместо одного адреса с параметром action и текстовых ответов;
ключ передаётся в заголовке Authorization: Bearer, а не в строке запроса;
покупка требует заголовок Idempotency-Key: повтор запроса с тем же ключом вернёт тот же заказ, а не купит второй номер;
коды можно получать через webhooks, а не только опросом статуса.

Соответствие методов

Методы SMS-Activate и Hush SMS API
SMS-Activate	Hush SMS API
`getBalance`	`GET /v1/me` — профиль и баланс
`getNumber`	`POST /v1/numbers` с телом `{"service", "country"}` и заголовком `Idempotency-Key`
`getStatus`	`GET /v1/numbers/{order_id}` — статус и коды; `GET /v1/orders/{order_id}/sms` — все SMS заказа
`setStatus`, status=6	`POST /v1/orders/{order_id}/finish` — завершить заказ
`setStatus`, status=8	`POST /v1/numbers/{order_id}/cancel` — отменить заказ
`setStatus`, status=3	Отдельного метода нет; повторный код запрашивается в боте кнопкой «Ещё SMS»
`getPrices`, `getNumbersStatus`	`GET /v1/services`, `GET /v1/services/{code}/countries`, `GET /v1/services/{code}/offers`
Активные заказы и история	`GET /v1/numbers` и `GET /v1/orders/history`

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

Статусы SMS-Activate и Hush SMS API
SMS-Activate	Hush SMS API
`STATUS_WAIT_CODE`	`pending` — номер выдан, ждём SMS
`STATUS_OK:код`	`sms_received` — код получен и есть в ответе заказа
`STATUS_CANCEL`	`canceled`, затем `refunded` — заказ отменён, деньги вернулись на баланс
Заказ завершён	`finished`

Пример: купить номер и проверить код

curl -X POST https://api.hush-sms.com/v1/numbers \
  -H "Authorization: Bearer $HUSH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"service": "tg", "country": 0}'

curl https://api.hush-sms.com/v1/numbers/ORDER_ID \
  -H "Authorization: Bearer $HUSH_API_KEY"

Коды сервисов и ID стран не переносите из старой интеграции вслепую: берите их из GET /v1/services и GET /v1/services/{code}/countries. Полный справочник с примерами — в документации API.

Правила, которые стоит учесть

отмена доступна для заказа без SMS и не раньше чем через 2 минуты после покупки; раньше API ответит 409 too_early с числом секунд до отмены;
при ответах 503 и 504 сначала проверьте статус заказа и только потом повторяйте действие с тем же заказом;
если цена у поставщика изменилась во время покупки, в ответе будут price_changed и предыдущая цена;
цены и баланс в ответах API указаны в рублях.

Webhooks вместо опроса

Адрес для webhooks задаётся в разделе API Telegram-бота. Когда придёт SMS, Hush SMS отправит на него POST-запрос с кодом, а опрос статуса можно оставить запасным путём. Формат запроса описан в разделе Webhooks.

План перехода без простоя

Получите API-ключ в разделе API бота и пополните баланс.
Напишите адаптер: ваши вызовы getNumber, getStatus и setStatus — в методы Hush SMS.
Проверьте полный цикл на одном сервисе: покупка, код, завершение и отмена.
Подключите webhooks и оставьте опрос статуса как запасной вариант.
Переведите на новый поток небольшую долю заказов, сравните результат и только потом переключайте всё.

Если выбираете между несколькими поставщиками, пригодится чек-лист в статье аналоги Grizzly SMS, Vak-SMS и SMSHub.

Частые вопросы

Есть ли у Hush SMS адрес, совместимый с handler API SMS-Activate?

Нет. У Hush SMS собственный REST API. Для перехода удобно сделать адаптер, который переводит старые вызовы в новые методы.

Где взять API-ключ?

В Telegram-боте @HushNumBot, в разделе API. В запросах ключ передаётся в заголовке Authorization: Bearer.

Можно ли запросить повторный код через API?

Отдельного метода в API сейчас нет. Повторный код можно запросить в боте кнопкой «Ещё SMS», если сервис поддерживает повторную отправку.

Переносите интеграцию?

Получите API-ключ в разделе API бота и начните с одного тестового заказа.

Получить API-ключ

Как перейти с API SMS-Activate на Hush SMS: соответствие методов и статусов