Номера и SMS-коды по API

Купите номер, дождитесь SMS и заберите код. Баланс общий с ботом NumberCodes, деньги списываются в долларах. Подходит для ботов, сервисов автоматизации и скриптов.

REST JSONhttps://numbercodes.shop/api/v1

SMS-Activatehttps://numbercodes.shop/stubs/handler_api.php

Открыть @NumberCodes_bot Быстрый старт

Авторизация

Каждый запрос подписывается вашим ключом вида ak_live_…

Откройте @NumberCodes_bot.
Зайдите в «Профиль» или отправьте /api, нажмите «API разработчикам».
Скопируйте ключ. Если он утёк, перевыпустите его: старый перестанет работать сразу.

Как передать ключ	Пример	Где работает
Заголовок `X-API-Key` (рекомендуем)	`X-API-Key: ak_live_…`	REST
Заголовок `Authorization`	`Authorization: Bearer ak_live_…`	REST
Параметр запроса	`?api_key=ak_live_…`	SMS-Activate

Храните ключ на сервере. Не публикуйте его в репозиториях и не встраивайте в клиентский код.

Чтобы пробовать методы прямо на этой странице, вставьте ключ в поле вверху. Он остаётся только в этой вкладке браузера.

Быстрый старт

Полный цикл: купить номер Telegram, дождаться кода, завершить заказ.

Пример

Идемпотентность

Повторный запрос после обрыва связи не купит второй номер.

Передайте заголовок Idempotency-Key с уникальным значением (например, UUID) при покупке и при создании счёта на пополнение. Для покупки можно использовать и поле idempotency_key в теле запроса.

В течение 5 минут тот же ключ вернёт результат первого запроса без повторного списания.
Если первый запрос ещё выполняется, придёт ответ 409 Conflict.

Webhooks

Сервер сам сообщит о коде, и опрашивать заказы не нужно.

Webhook на заказ. Передайте callback_url при покупке или задайте его позже через PUT /orders/{id}/webhook.
Webhook на аккаунт. Один адрес на все события, с подписью и журналом доставок. Настраивается через PUT /webhook, методы описаны в группе «Webhook аккаунта».

События аккаунта

Событие	Когда приходит
`sms_received`	На номер пришло SMS
`order_cancelled`	Заказ отменён или истёк, деньги возвращены
`rental_expiring`	Аренда скоро закончится
`rental_finished`	Аренда закончилась
`balance_topped_up`	Баланс пополнен

Что приходит на ваш адрес

POST на ваш URL, application/json

{
  "id": "evt_9f3c1a52d7b84e60a1c2",
  "event": "sms_received",
  "created_at": "2026-11-03T14:31:05Z",
  "data": {
    "order_id": 54101,
    "phone": "+79991234567",
    "service": "Telegram",
    "sms_code": "49201"
  }
}

Проверка подписи

Каждый запрос содержит заголовок X-NumberCodes-Signature: t=<unix>,v1=<hex>. Значение v1 — HMAC-SHA256 от строки "<t>.<тело запроса>" с вашим секретом whsec_…. Сравнивайте подпись и проверяйте, что t не старше пяти минут.

Проверка на вашей стороне

Доставка и повторы

Адрес должен быть публичным и начинаться с https://. Внутренние адреса отклоняются.
Ответьте кодом 2xx в течение 8 секунд. Иначе сервер повторит отправку через 3, 15 и 60 секунд.
Все попытки видны в GET /webhook/deliveries, неудачную доставку можно отправить заново через POST /webhook/deliveries/{id}/retry.
Чтобы не обработать событие дважды, храните id уже принятых событий.

Ошибки и лимиты

Ошибки REST приходят в формате {"status":"error","code":402,"detail":"…"}

Код	Значение	Что делать
`400`	Неверные параметры	Проверьте сервис, id и условия. Отменить заказ после получения SMS нельзя
`401`	Нет доступа	Ключ не передан или недействителен
`402`	Не хватает денег	Пополните баланс в боте или через POST /deposits
`404`	Не найдено	Заказа нет или он принадлежит другому аккаунту
`409`	Запрос уже выполняется	Дождитесь результата первого запроса с тем же Idempotency-Key
`429`	Слишком много запросов	Лимит 120 запросов в минуту. Вместо частого опроса используйте /wait или webhook
`502`	Сбой у поставщика	Повторите через несколько секунд
`503`	Нет свободных номеров	Попробуйте другую страну или оператора, проверьте GET /availability

Протокол SMS-Activate

Для готового программного обеспечения, которое умеет работать с SMS-Activate или SMSHub. Выберите этот сервис в настройках и подставьте адрес ниже.

Адрес: /stubs/handler_api.php. Ключ передаётся параметром api_key, действие — параметром action. Ответы приходят обычным текстом.

action	Что делает
`getBalance`	Баланс: `ACCESS_BALANCE:7.00`
`getNumber`	Купить номер, параметры `service`, `country`, `operator`. Ответ `ACCESS_NUMBER:id:телефон`
`getNumberV2`	То же, но ответ в JSON
`getStatus`	Код по `id`: `STATUS_WAIT_CODE` или `STATUS_OK:84920`. После запроса повторного SMS: `STATUS_WAIT_RETRY:84920`, пока не придёт новое
`getStatusV2`	То же, но код приходит в JSON: `{"sms": {"code": "84920", "text": "…"}}`
`getFullSms`	Полный текст SMS: `FULL_SMS:текст`
`setStatus`	`status=1` готов, `3` запросить ещё одно SMS, `6` завершить, `8` отменить с возвратом
`getPrices`	Цены и количество номеров
`getServicesList`	Список сервисов
`getNumbersStatus`	Сколько номеров доступно по сервисам
`getCountries`	Справочник стран
`getOperators`	Операторы по странам
`getActiveActivations`	Активные заказы

Ответы протокола

Ответ	Значение
`ACCESS_NUMBER:id:phone`	Номер выдан
`STATUS_WAIT_CODE`	SMS ещё нет. Опрашивайте раз в 2–4 секунды
`STATUS_OK:code`	Код получен
`STATUS_WAIT_RETRY:code`	Повторное SMS запрошено (`setStatus=3`), новое ещё не пришло. В `code` прежний код. Как только SMS придёт, `getStatus` вернёт `STATUS_OK:новый_код`, а на webhook уйдёт `sms_received`
`STATUS_CANCEL`	Заказ отменён или время вышло
`ACCESS_READY` · `ACCESS_RETRY_GET` · `ACCESS_ACTIVATION`	Подтверждения `setStatus` 1, 3 и 6
`ACCESS_CANCEL`	Заказ отменён, деньги вернулись на баланс
`BAD_KEY`	Ключ неверный или отключён
`BAD_SERVICE`	Неизвестный код сервиса
`BAD_STATUS`	Статус недопустим, например отмена после получения кода
`BAD_ACTION`	Неизвестное значение `action`
`NO_BALANCE`	Не хватает денег на балансе
`NO_NUMBERS`	Свободных номеров нет
`NO_ACTIVATION`	Заказ не найден
`ERROR_RATE_LIMIT`	Больше 240 запросов в минуту (HTTP 429)

Загружаю справочник методов…