Перейти к содержимому

API v1

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

Для тех, кто делает свой сервис: Telegram-бот, сайт или софт по продаже номеров. Покупайте номера и получайте коды через API, продавайте со своей наценкой. Протокол совместим с SMS-Activate — готовые интеграции заработают после замены адреса и ключа.

  • Свой Telegram-бот

    Продавайте номера в боте со своей наценкой

  • Свой сайт

    Выдавайте номера клиентам на своей витрине

  • Софт и скрипты

    Автоматическая регистрация аккаунтов

  • Один эндпоинт

    Все методы — GET-запросы к /api/v1

  • Bearer-ключ

    Ключ в заголовке, а не в ссылке

  • Возврат денег

    Нет СМС — отмена вернёт оплату

Базовый адресhttps://mukhasms.com/api/v1

Авторизация

Ключ выдаётся в личном кабинете — это 32 латинские буквы и цифры. Передавайте его в заголовке Authorization. Для совместимости со старыми скриптами работает и параметр api_key.

Authorization: Bearer 8fK2pQ9xLm3vT7nR1sYc4wHb6dJe0aZu

Храните ключ в секрете

Ключом можно тратить ваш баланс. Не публикуйте его в коде на GitHub и во фронтенде. Если ключ утёк — создайте новый в кабинете, старый сразу перестанет работать.

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

Типичный сценарий — купить номер, дождаться кода и завершить активацию. Сохраните ключ в переменную окружения MUKHA_API_KEY.

  1. 1Купить номер — getNumber
  2. 2Опрашивать — getStatus
  3. 3Завершить — setStatus=6
Терминал
# 1. Купить номер для Telegram в России
curl "https://mukhasms.com/api/v1?action=getNumber&service=tg&country=187" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
# → ACCESS_NUMBER:1042:14155550123

# 2. Запросить код в Telegram, затем опрашивать статус
curl "https://mukhasms.com/api/v1?action=getStatus&id=1042" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
# → STATUS_WAIT_CODE … STATUS_OK:48213

# 3. Завершить активацию
curl "https://mukhasms.com/api/v1?action=setStatus&id=1042&status=6" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
# → ACCESS_ACTIVATION

Методы

GET

getBalance

Нужен ключ

Баланс

Возвращает текущий баланс аккаунта в рублях.

Параметры

Только action

curl "https://mukhasms.com/api/v1?action=getBalance" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · text/plain
ACCESS_BALANCE:1250.00
GET

getServicesList

Без ключа

Список сервисов

Все сервисы, для которых можно купить номер. Код сервиса передаётся в getNumber и getPrices.

Параметры

Только action

curl "https://mukhasms.com/api/v1?action=getServicesList"
Ответ · JSON
{
  "status": "success",
  "services": [
    { "code": "tg", "name": "Telegram" },
    { "code": "wa", "name": "WhatsApp" }
  ]
}
GET

getCountries

Без ключа

Список стран

Страны и их числовые идентификаторы.

Параметры

Только action

curl "https://mukhasms.com/api/v1?action=getCountries"
Ответ · JSON
[
  { "id": 187, "rus": "США", "eng": "USA" },
  { "id": 2, "rus": "Казахстан", "eng": "Kazakhstan" }
]
GET

getPrices

Нужен ключ

Цены и наличие

Цена номера и количество свободных номеров для сервиса по каждой стране.

Параметры

  • servicestringобязательный

    Код сервиса, например tg

curl "https://mukhasms.com/api/v1?action=getPrices&service=tg" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · JSON
{
  "0": { "tg": { "cost": 12.5, "count": 340 } },
  "2": { "tg": { "cost": 9.9, "count": 125 } }
}
GET

getNumber

Нужен ключ

Купить номер

Покупает номер и списывает его стоимость с баланса. Если СМС не придёт, деньги вернутся при отмене.

Параметры

  • servicestringобязательный

    Код сервиса

  • countryintegerобязательный

    ID страны из getCountries

curl "https://mukhasms.com/api/v1?action=getNumber&service=tg&country=0" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · text/plain
ACCESS_NUMBER:1042:14155550123
GET

getNumberV2

Нужен ключ

Купить номер (JSON)

То же, что getNumber, но ответ в JSON с ценой и временем окончания аренды.

Параметры

  • servicestringобязательный

    Код сервиса

  • countryintegerобязательный

    ID страны из getCountries

curl "https://mukhasms.com/api/v1?action=getNumberV2&service=tg&country=0" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · JSON
{
  "activationId": "1042",
  "phoneNumber": "14155550123",
  "activationCost": 12.5,
  "currency": 643,
  "countryCode": 187,
  "serviceCode": "tg",
  "activationTime": "2026-10-25T12:00:00.000Z",
  "activationEndTime": "2026-10-25T12:20:00.000Z"
}
GET

getStatus

Нужен ключ

Статус активации

Проверяет, пришёл ли код. Опрашивайте не чаще раза в 3–5 секунд.

Параметры

  • idintegerобязательный

    ID активации из getNumber

curl "https://mukhasms.com/api/v1?action=getStatus&id=1042" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · text/plain
STATUS_OK:48213
GET

getStatusV2

Нужен ключ

Статус активации (JSON)

Статус с полным текстом СМС и временем получения.

Параметры

  • idintegerобязательный

    ID активации

curl "https://mukhasms.com/api/v1?action=getStatusV2&id=1042" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · JSON
{
  "verificationType": 0,
  "sms": {
    "dateTime": "2026-10-25T12:01:14.000Z",
    "code": "48213",
    "text": "Telegram code: 48213"
  },
  "call": null
}
GET

setStatus

Нужен ключ

Изменить статус

Завершает активацию, отменяет её с возвратом денег или запрашивает ещё одно СМС.

Параметры

  • idintegerобязательный

    ID активации

  • statusintegerобязательный

    3 — ещё СМС, 6 — завершить, 8 — отменить

curl "https://mukhasms.com/api/v1?action=setStatus&id=1042&status=6" \
  -H "Authorization: Bearer $MUKHA_API_KEY"
Ответ · text/plain
ACCESS_ACTIVATION

Статусы

Ответы getStatus и setStatus.

STATUS_WAIT_CODE
Номер выдан, ждём СМС
STATUS_OK:КОД
Код получен — он идёт после двоеточия
STATUS_CANCEL
Активация отменена или истекла
ACCESS_ACTIVATION
Активация завершена (setStatus=6)
ACCESS_CANCEL
Активация отменена, деньги вернулись (setStatus=8)
ACCESS_RETRY_GET
Ждём следующее СМС (setStatus=3)

Ошибки

Ошибки приходят обычным текстом с HTTP-кодом 4xx или 5xx.

КодHTTPЧто значит
BAD_KEY401Ключ не передан или неверный
BAD_ACTION400Неизвестный action или не хватает параметров
BAD_STATUS400Недопустимое значение status
NO_BALANCE400Недостаточно денег на балансе
NO_NUMBERS400Нет свободных номеров для этого сервиса и страны
NO_ACTIVATION404Активация не найдена
EARLY_CANCEL_DENIED400Отменить можно через 2 минуты после покупки
SERVICE_UNAVAILABLE502Временный сбой у поставщика — повторите позже