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

API Sim7

Один эндпоинт на покупку, один — на статус, один — на входящее SMS. Все запросы идут на https://sim7.org/api/v1 и авторизуются Bearer-токеном.

Базовый адрес

base_url

https://sim7.org/api/v1

Только HTTPS, тело запросов и ответов — JSON в UTF-8.

Заголовок авторизации

Bearer

Authorization

Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ключ доступен в разделе API-ключи личного кабинета. Ключи nx_test работают в песочнице без списаний.

Начало работы

Базовый адрес, формат ответов и первый запрос за пять минут.

Все запросы идут на https://sim7.org/api/v1 по HTTPS. Тело запросов и ответов — JSON в кодировке UTF-8; запросы без TLS отклоняются, редиректа на защищённое соединение нет.

Успешный ответ всегда содержит объект с данными. Ошибка возвращает объект с полями code и message: code — стабильный машинный идентификатор, message — текст на русском для логов и интерфейса. Ориентируйтесь в коде на code, а не на HTTP-статус.

Суммы возвращаются в долларах числом с плавающей точкой и округлением до четвёртого знака. Все временные метки — в UTC в формате ISO 8601.

Аутентификация

Bearer-токен в заголовке, тестовый и боевой ключи, ограничение по IP.

Ключ передаётся в заголовке: Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx. Ключи с префиксом nx_live работают с реальным балансом, ключи nx_test — в песочнице, где заказы проходят полный жизненный цикл, но списаний не происходит.

Ключ выдаётся сразу после регистрации и виден в разделе «API-ключи» личного кабинета. Перевыпуск отзывает старый ключ немедленно, поэтому обновляйте его во всех интеграциях одновременно.

Для боевого ключа рекомендуем включить список разрешённых IP-адресов: запросы с других адресов получают ошибку ip_not_allowed даже при верном ключе.

Каталог и цены

Сервисы, страны и актуальная цена с доступностью номеров.

Каталог меняется редко, поэтому списки сервисов и стран можно кэшировать на своей стороне — разумный интервал обновления составляет один час.

Цены и доступность, наоборот, живут минутами: они зависят от текущего наполнения пулов. Запрашивайте их прямо перед покупкой, чтобы не показывать пользователю устаревшую сумму.

GET/services

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

Возвращает каталог сервисов с категорией и минимальной ценой номера.

Параметры

Параметр	Где	Тип	Пример:
categoryОпциональный	Query	string	Фильтр по категории каталога.Пример: `messengers`
searchОпциональный	Query	string	Поиск по названию сервиса, без учёта регистра.Пример: `tele`

categoryQueryОпциональный
Фильтр по категории каталога.
string · Пример: messengers
searchQueryОпциональный
Поиск по названию сервиса, без учёта регистра.
string · Пример: tele

curl

curl -s https://sim7.org/api/v1/services \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "telegram", "name": "Telegram", "category": "Messengers", "price_from": 0.12, "available": 48210 },
    { "id": "whatsapp", "name": "WhatsApp", "category": "Messengers", "price_from": 0.09, "available": 36540 }
  ],
  "total": 1240
}

GET/countries

Список стран

Возвращает страны, телефонный код и количество доступных номеров.

Параметры

Параметр	Где	Тип	Пример:
regionОпциональный	Query	string	Фильтр по региону: europe, asia, america или africa.Пример: `europe`

regionQueryОпциональный
Фильтр по региону: europe, asia, america или africa.
string · Пример: europe

curl

curl -s "https://sim7.org/api/v1/countries?region=europe" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "germany", "name": "Germany", "iso": "DE", "dial": "+49", "available": 27600 },
    { "id": "france", "name": "France", "iso": "FR", "dial": "+33", "available": 21900 }
  ],
  "total": 195
}

GET/prices

Цены и доступность

Актуальная цена и остаток номеров для пары сервис + страна. Данные живут около минуты, кэшировать надолго не стоит.

Параметры

Параметр	Где	Тип	Пример:
serviceОбязательный	Query	string	Идентификатор сервиса из каталога.Пример: `telegram`
countryОпциональный	Query	string	Идентификатор страны. Без него вернутся все страны сервиса.Пример: `russia`

serviceQueryОбязательный
Идентификатор сервиса из каталога.
string · Пример: telegram
countryQueryОпциональный
Идентификатор страны. Без него вернутся все страны сервиса.
string · Пример: russia

curl

curl -s "https://sim7.org/api/v1/prices?service=telegram&country=russia" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "service": "telegram",
  "items": [
    {
      "country": "russia",
      "operator": "any",
      "price": 0.12,
      "available": 18240,
      "success_rate": 0.978
    }
  ]
}

Заказы

Покупка номера, получение кода, отмена и повторная аренда.

Заказ проходит статусы waiting → completed либо waiting → cancelled. Пока заказ в статусе waiting, номер закреплён за вами и принимает сообщения; окно ожидания по умолчанию — 1200 секунд.

Если код не пришёл до конца окна, заказ автоматически переходит в cancelled, а сумма возвращается на баланс. Отдельного запроса на возврат делать не нужно.

Не опрашивайте статус чаще одного раза в пять секунд — вместо этого подключите вебхук и используйте опрос как страховку для заказов, которые висят дольше обычного.

POST/numbers

Купить номер

Резервирует номер под выбранный сервис и создаёт заказ в статусе waiting. Сумма списывается сразу и возвращается, если код не придёт.

Параметры

Параметр	Где	Тип	Пример:
serviceОбязательный	Тело	string	Идентификатор сервиса, для которого нужен номер.Пример: `telegram`
countryОбязательный	Тело	string	Идентификатор страны.Пример: `russia`
operatorОпциональный	Тело	string	Идентификатор оператора. По умолчанию any — подбор по доставляемости.Пример: `mts`
max_priceОпциональный	Тело	number	Защита от роста цены: заказ не создастся, если номер дороже указанной суммы.Пример: `0.2`
ttl_secondsОпциональный	Тело	number	Окно ожидания SMS в секундах, от 300 до 3600. По умолчанию 1200.Пример: `1200`

serviceТелоОбязательный
Идентификатор сервиса, для которого нужен номер.
string · Пример: telegram
countryТелоОбязательный
Идентификатор страны.
string · Пример: russia
operatorТелоОпциональный
Идентификатор оператора. По умолчанию any — подбор по доставляемости.
string · Пример: mts
max_priceТелоОпциональный
Защита от роста цены: заказ не создастся, если номер дороже указанной суммы.
number · Пример: 0.2
ttl_secondsТелоОпциональный
Окно ожидания SMS в секундах, от 300 до 3600. По умолчанию 1200.
number · Пример: 1200

curl

curl -s -X POST https://sim7.org/api/v1/numbers \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"russia","max_price":0.2}'

request.json

{
  "service": "telegram",
  "country": "russia",
  "operator": "any",
  "max_price": 0.2,
  "ttl_seconds": 1200
}

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "service": "telegram",
  "country": "russia",
  "operator": "mts",
  "price": 0.12,
  "status": "waiting",
  "expires_at": "2026-07-31T18:32:00Z"
}

GET/orders/{order_id}

Статус заказа и код

Возвращает текущий статус заказа и все полученные сообщения. Пока код не пришёл, поле code равно null.

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор заказа, полученный при покупке номера.Пример: `a13f9c`

order_idПутьОбязательный
Идентификатор заказа, полученный при покупке номера.
string · Пример: a13f9c

curl

curl -s https://sim7.org/api/v1/orders/a13f9c \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "status": "completed",
  "code": "482913",
  "price": 0.12,
  "messages": [
    {
      "sender": "Telegram",
      "text": "Your login code: 482913",
      "received_at": "2026-07-31T18:12:44Z"
    }
  ]
}

GET/orders

История заказов

Постраничный список заказов аккаунта, от новых к старым.

Параметры

Параметр	Где	Тип	Пример:
statusОпциональный	Query	string	Фильтр по статусу: waiting, completed или cancelled.Пример: `completed`
limitОпциональный	Query	number	Размер страницы, от 1 до 100. По умолчанию 20.Пример: `20`
cursorОпциональный	Query	string	Курсор следующей страницы из поля next_cursor предыдущего ответа.Пример: `b27e41`

statusQueryОпциональный
Фильтр по статусу: waiting, completed или cancelled.
string · Пример: completed
limitQueryОпциональный
Размер страницы, от 1 до 100. По умолчанию 20.
number · Пример: 20
cursorQueryОпциональный
Курсор следующей страницы из поля next_cursor предыдущего ответа.
string · Пример: b27e41

curl

curl -s "https://sim7.org/api/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    {
      "order_id": "a13f9c",
      "service": "telegram",
      "country": "russia",
      "number": "+7 901 234 56 78",
      "code": "482913",
      "price": 0.12,
      "status": "completed",
      "created_at": "2026-07-29T14:12:00Z"
    }
  ],
  "next_cursor": "b27e41"
}

POST/orders/{order_id}/cancel

Отменить заказ

Досрочно освобождает номер. Если код ещё не пришёл, сумма возвращается на баланс полностью.

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор заказа в статусе waiting.Пример: `c88a02`

order_idПутьОбязательный
Идентификатор заказа в статусе waiting.
string · Пример: c88a02

curl

curl -s -X POST https://sim7.org/api/v1/orders/c88a02/cancel \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "c88a02",
  "status": "cancelled",
  "refunded": 0.05,
  "balance": 24.85
}

POST/orders/{order_id}/reuse

Повторная аренда номера

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

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор завершённого заказа.Пример: `a13f9c`
serviceОпциональный	Тело	string	Другой сервис для того же номера. По умолчанию сервис исходного заказа.Пример: `whatsapp`

order_idПутьОбязательный
Идентификатор завершённого заказа.
string · Пример: a13f9c
serviceТелоОпциональный
Другой сервис для того же номера. По умолчанию сервис исходного заказа.
string · Пример: whatsapp

curl

curl -s -X POST https://sim7.org/api/v1/orders/a13f9c/reuse \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp"}'

request.json

{
  "service": "whatsapp"
}

response.json

{
  "order_id": "f0271d",
  "number": "+7 901 234 56 78",
  "service": "whatsapp",
  "price": 0.07,
  "status": "waiting",
  "expires_at": "2026-07-31T19:04:00Z"
}

Аккаунт

Баланс, лимиты и статистика по аккаунту.

Проверяйте баланс перед серией покупок: при недостатке средств запрос на номер вернёт ошибку insufficient_funds и заказ не будет создан.

В ответе также приходят текущие лимиты аккаунта — число одновременных активных заказов и остаток по частоте запросов. Это удобнее, чем подбирать лимиты эмпирически по ошибкам 429.

GET/balance

Баланс и лимиты

Текущий баланс аккаунта, действующий тариф и остаток лимитов.

curl

curl -s https://sim7.org/api/v1/balance \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "balance": 24.8,
  "currency": "USD",
  "plan": "api",
  "limits": {
    "concurrent_orders": 250,
    "active_orders": 3,
    "requests_per_minute": 600
  }
}

Вебхуки

Мгновенное уведомление о входящем коде и проверка подписи.

Мы отправляем POST-запрос на ваш адрес сразу после разбора сообщения. Каждый запрос подписан заголовком X-Sim7-Signature: подпись считается как HMAC-SHA256 по сырому телу запроса с секретом вебхука.

Проверяйте подпись до разбора тела и сравнивайте её функцией с постоянным временем выполнения. Обработчик должен отвечать статусом 200 в течение пяти секунд.

Доставка гарантируется минимум один раз, поэтому обработчик обязан быть идемпотентным по order_id. При ошибке мы повторяем отправку пять раз с растущим интервалом от 10 секунд до 5 минут.

PUT/webhook

Настроить вебхук

Задаёт адрес обработчика и список событий. Секрет для подписи возвращается один раз при создании.

Параметры

Параметр	Где	Тип	Пример:
urlОбязательный	Тело	string	HTTPS-адрес обработчика.Пример: `https://sim7.org/webhooks/sim7`
eventsОбязательный	Тело	string	События: order.code_received, order.cancelled, balance.low.Пример: `order.code_received`
is_enabledОпциональный	Тело	boolean	Позволяет временно отключить доставку, не удаляя настройку.Пример: `true`

urlТелоОбязательный
HTTPS-адрес обработчика.
string · Пример: https://sim7.org/webhooks/sim7
eventsТелоОбязательный
События: order.code_received, order.cancelled, balance.low.
string · Пример: order.code_received
is_enabledТелоОпциональный
Позволяет временно отключить доставку, не удаляя настройку.
boolean · Пример: true

curl

curl -s -X PUT https://sim7.org/api/v1/webhook \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://sim7.org/webhooks/sim7","events":["order.code_received"]}'

request.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true
}

response.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true,
  "secret": "whsec_9f31c0a7d84b2e65",
  "updated_at": "2026-07-31T18:40:12Z"
}

POSThttps://sim7.org/webhooks/sim7

Событие order.code_received

Запрос, который мы отправляем на ваш адрес после разбора сообщения. Отвечайте статусом 200 в течение пяти секунд.

Параметры

Параметр	Где	Тип	Пример:
eventОбязательный	Тело	string	Тип события.Пример: `order.code_received`
order_idОбязательный	Тело	string	Идентификатор заказа — используйте его как ключ идемпотентности.Пример: `a13f9c`
codeОбязательный	Тело	string	Код, извлечённый из текста сообщения.Пример: `482913`

eventТелоОбязательный
Тип события.
string · Пример: order.code_received
order_idТелоОбязательный
Идентификатор заказа — используйте его как ключ идемпотентности.
string · Пример: a13f9c
codeТелоОбязательный
Код, извлечённый из текста сообщения.
string · Пример: 482913

curl

# we send this request; here's how to replay it locally:
curl -s -X POST https://sim7.org/webhooks/sim7 \
  -H "Content-Type: application/json" \
  -H "X-Sim7-Signature: sha256=1f8c…" \
  -d '{"event":"order.code_received","order_id":"a13f9c","code":"482913"}'

request.json

{
  "event": "order.code_received",
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "code": "482913",
  "text": "Your login code: 482913",
  "received_at": "2026-07-31T18:12:44Z"
}

response.json

{
  "received": true
}

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

Стабильные коды ошибок и частота запросов по тарифам.

Ошибки клиента (4xx) означают, что запрос нужно исправить — повторять его без изменений бессмысленно. Ошибки 5xx и 429 можно повторять с экспоненциальной задержкой.

При превышении частоты запросов в ответе приходит заголовок Retry-After с числом секунд до следующей допустимой попытки.

Коды ошибок

Коды ошибок API Sim7
Код	HTTP	Что произошло
`invalid_request`	400	Некорректный запросТело или параметры не проходят валидацию: пропущено обязательное поле или неверный тип.
`unauthorized`	401	Ключ не принятЗаголовок Authorization отсутствует, ключ отозван или скопирован не полностью.
`ip_not_allowed`	403	IP не в списке разрешённыхКлюч верный, но запрос пришёл с адреса, которого нет в списке разрешённых для аккаунта.
`order_not_found`	404	Заказ не найденЗаказа с таким идентификатором нет или он принадлежит другому аккаунту.
`order_not_cancellable`	409	Заказ уже закрытОтмена доступна только для заказов в статусе waiting: код уже получен или окно истекло.
`insufficient_funds`	402	Недостаточно средствБаланса не хватает на выбранный номер. Заказ не создан, списания не было.
`no_numbers_available`	409	Нет свободных номеровПул для пары сервис + страна временно пуст. Повторите запрос позже или смените страну.
`price_changed`	409	Цена выше лимитаАктуальная цена превысила значение max_price из запроса. Обновите цену и повторите покупку.
`rate_limited`	429	Слишком много запросовПревышена частота запросов. Дождитесь числа секунд из заголовка Retry-After.
`concurrency_limit`	429	Лимит активных заказовДостигнут предел одновременных заказов по тарифу. Дождитесь завершения текущих.
`internal_error`	500	Внутренняя ошибкаСбой на нашей стороне. Запрос можно повторить с экспоненциальной задержкой.
`service_unavailable`	503	Сервис недоступенПлановые работы или деградация. Текущее состояние публикуем на странице статуса.

invalid_request400
Некорректный запрос
Тело или параметры не проходят валидацию: пропущено обязательное поле или неверный тип.
unauthorized401
Ключ не принят
Заголовок Authorization отсутствует, ключ отозван или скопирован не полностью.
ip_not_allowed403
IP не в списке разрешённых
Ключ верный, но запрос пришёл с адреса, которого нет в списке разрешённых для аккаунта.
order_not_found404
Заказ не найден
Заказа с таким идентификатором нет или он принадлежит другому аккаунту.
order_not_cancellable409
Заказ уже закрыт
Отмена доступна только для заказов в статусе waiting: код уже получен или окно истекло.
insufficient_funds402
Недостаточно средств
Баланса не хватает на выбранный номер. Заказ не создан, списания не было.
no_numbers_available409
Нет свободных номеров
Пул для пары сервис + страна временно пуст. Повторите запрос позже или смените страну.
price_changed409
Цена выше лимита
Актуальная цена превысила значение max_price из запроса. Обновите цену и повторите покупку.
rate_limited429
Слишком много запросов
Превышена частота запросов. Дождитесь числа секунд из заголовка Retry-After.
concurrency_limit429
Лимит активных заказов
Достигнут предел одновременных заказов по тарифу. Дождитесь завершения текущих.
internal_error500
Внутренняя ошибка
Сбой на нашей стороне. Запрос можно повторить с экспоненциальной задержкой.
service_unavailable503
Сервис недоступен
Плановые работы или деградация. Текущее состояние публикуем на странице статуса.

Частота запросов

Лимиты частоты запросов по тарифам
Тариф	Запросов в минуту	Примечание
Разовая покупка	60	До 10 одновременных активных заказов.
API для разработчиков	600	До 250 одновременных активных заказов.
Бизнес	По запросу	Лимиты согласуются под нагрузку, без ограничения одновременных заказов.
Тестовый ключ nx_test	120	Песочница без списаний, код приходит через 3–5 секунд.

Разовая покупка60
До 10 одновременных активных заказов.
API для разработчиков600
До 250 одновременных активных заказов.
БизнесПо запросу
Лимиты согласуются под нагрузку, без ограничения одновременных заказов.
Тестовый ключ nx_test120
Песочница без списаний, код приходит через 3–5 секунд.

Текущее состояние компонентов и историю инцидентов мы публикуем на странице статуса.

Готовы попробовать?

Ключ выдаётся сразу после регистрации, песочница не расходует баланс, а подпись вебхуков проверяется по заголовку X-Sim7-Signature.

Получить ключ доступа Мои API-ключи

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

API Sim7

Базовый адрес

base_url

https://sim7.org/api/v1

Только HTTPS, тело запросов и ответов — JSON в UTF-8.

Заголовок авторизации

Bearer

Authorization

Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ключ доступен в разделе API-ключи личного кабинета. Ключи nx_test работают в песочнице без списаний.

Начало работы

Базовый адрес, формат ответов и первый запрос за пять минут.

Аутентификация

Bearer-токен в заголовке, тестовый и боевой ключи, ограничение по IP.

Каталог и цены

Сервисы, страны и актуальная цена с доступностью номеров.

GET/services

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

Возвращает каталог сервисов с категорией и минимальной ценой номера.

Параметры

Параметр	Где	Тип	Пример:
categoryОпциональный	Query	string	Фильтр по категории каталога.Пример: `messengers`
searchОпциональный	Query	string	Поиск по названию сервиса, без учёта регистра.Пример: `tele`

categoryQueryОпциональный
Фильтр по категории каталога.
string · Пример: messengers
searchQueryОпциональный
Поиск по названию сервиса, без учёта регистра.
string · Пример: tele

curl

curl -s https://sim7.org/api/v1/services \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "telegram", "name": "Telegram", "category": "Messengers", "price_from": 0.12, "available": 48210 },
    { "id": "whatsapp", "name": "WhatsApp", "category": "Messengers", "price_from": 0.09, "available": 36540 }
  ],
  "total": 1240
}

GET/countries

Список стран

Возвращает страны, телефонный код и количество доступных номеров.

Параметры

Параметр	Где	Тип	Пример:
regionОпциональный	Query	string	Фильтр по региону: europe, asia, america или africa.Пример: `europe`

regionQueryОпциональный
Фильтр по региону: europe, asia, america или africa.
string · Пример: europe

curl

curl -s "https://sim7.org/api/v1/countries?region=europe" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    { "id": "germany", "name": "Germany", "iso": "DE", "dial": "+49", "available": 27600 },
    { "id": "france", "name": "France", "iso": "FR", "dial": "+33", "available": 21900 }
  ],
  "total": 195
}

GET/prices

Цены и доступность

Параметры

Параметр	Где	Тип	Пример:
serviceОбязательный	Query	string	Идентификатор сервиса из каталога.Пример: `telegram`
countryОпциональный	Query	string	Идентификатор страны. Без него вернутся все страны сервиса.Пример: `russia`

serviceQueryОбязательный
Идентификатор сервиса из каталога.
string · Пример: telegram
countryQueryОпциональный
Идентификатор страны. Без него вернутся все страны сервиса.
string · Пример: russia

curl

curl -s "https://sim7.org/api/v1/prices?service=telegram&country=russia" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "service": "telegram",
  "items": [
    {
      "country": "russia",
      "operator": "any",
      "price": 0.12,
      "available": 18240,
      "success_rate": 0.978
    }
  ]
}

Заказы

Покупка номера, получение кода, отмена и повторная аренда.

POST/numbers

Купить номер

Параметры

Параметр	Где	Тип	Пример:
serviceОбязательный	Тело	string	Идентификатор сервиса, для которого нужен номер.Пример: `telegram`
countryОбязательный	Тело	string	Идентификатор страны.Пример: `russia`
operatorОпциональный	Тело	string	Идентификатор оператора. По умолчанию any — подбор по доставляемости.Пример: `mts`
max_priceОпциональный	Тело	number	Защита от роста цены: заказ не создастся, если номер дороже указанной суммы.Пример: `0.2`
ttl_secondsОпциональный	Тело	number	Окно ожидания SMS в секундах, от 300 до 3600. По умолчанию 1200.Пример: `1200`

serviceТелоОбязательный
Идентификатор сервиса, для которого нужен номер.
string · Пример: telegram
countryТелоОбязательный
Идентификатор страны.
string · Пример: russia
operatorТелоОпциональный
Идентификатор оператора. По умолчанию any — подбор по доставляемости.
string · Пример: mts
max_priceТелоОпциональный
Защита от роста цены: заказ не создастся, если номер дороже указанной суммы.
number · Пример: 0.2
ttl_secondsТелоОпциональный
Окно ожидания SMS в секундах, от 300 до 3600. По умолчанию 1200.
number · Пример: 1200

curl

curl -s -X POST https://sim7.org/api/v1/numbers \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"telegram","country":"russia","max_price":0.2}'

request.json

{
  "service": "telegram",
  "country": "russia",
  "operator": "any",
  "max_price": 0.2,
  "ttl_seconds": 1200
}

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "service": "telegram",
  "country": "russia",
  "operator": "mts",
  "price": 0.12,
  "status": "waiting",
  "expires_at": "2026-07-31T18:32:00Z"
}

GET/orders/{order_id}

Статус заказа и код

Возвращает текущий статус заказа и все полученные сообщения. Пока код не пришёл, поле code равно null.

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор заказа, полученный при покупке номера.Пример: `a13f9c`

order_idПутьОбязательный
Идентификатор заказа, полученный при покупке номера.
string · Пример: a13f9c

curl

curl -s https://sim7.org/api/v1/orders/a13f9c \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "status": "completed",
  "code": "482913",
  "price": 0.12,
  "messages": [
    {
      "sender": "Telegram",
      "text": "Your login code: 482913",
      "received_at": "2026-07-31T18:12:44Z"
    }
  ]
}

GET/orders

История заказов

Постраничный список заказов аккаунта, от новых к старым.

Параметры

Параметр	Где	Тип	Пример:
statusОпциональный	Query	string	Фильтр по статусу: waiting, completed или cancelled.Пример: `completed`
limitОпциональный	Query	number	Размер страницы, от 1 до 100. По умолчанию 20.Пример: `20`
cursorОпциональный	Query	string	Курсор следующей страницы из поля next_cursor предыдущего ответа.Пример: `b27e41`

statusQueryОпциональный
Фильтр по статусу: waiting, completed или cancelled.
string · Пример: completed
limitQueryОпциональный
Размер страницы, от 1 до 100. По умолчанию 20.
number · Пример: 20
cursorQueryОпциональный
Курсор следующей страницы из поля next_cursor предыдущего ответа.
string · Пример: b27e41

curl

curl -s "https://sim7.org/api/v1/orders?status=completed&limit=20" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "items": [
    {
      "order_id": "a13f9c",
      "service": "telegram",
      "country": "russia",
      "number": "+7 901 234 56 78",
      "code": "482913",
      "price": 0.12,
      "status": "completed",
      "created_at": "2026-07-29T14:12:00Z"
    }
  ],
  "next_cursor": "b27e41"
}

POST/orders/{order_id}/cancel

Отменить заказ

Досрочно освобождает номер. Если код ещё не пришёл, сумма возвращается на баланс полностью.

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор заказа в статусе waiting.Пример: `c88a02`

order_idПутьОбязательный
Идентификатор заказа в статусе waiting.
string · Пример: c88a02

curl

curl -s -X POST https://sim7.org/api/v1/orders/c88a02/cancel \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "order_id": "c88a02",
  "status": "cancelled",
  "refunded": 0.05,
  "balance": 24.85
}

POST/orders/{order_id}/reuse

Повторная аренда номера

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

Параметры

Параметр	Где	Тип	Пример:
order_idОбязательный	Путь	string	Идентификатор завершённого заказа.Пример: `a13f9c`
serviceОпциональный	Тело	string	Другой сервис для того же номера. По умолчанию сервис исходного заказа.Пример: `whatsapp`

order_idПутьОбязательный
Идентификатор завершённого заказа.
string · Пример: a13f9c
serviceТелоОпциональный
Другой сервис для того же номера. По умолчанию сервис исходного заказа.
string · Пример: whatsapp

curl

curl -s -X POST https://sim7.org/api/v1/orders/a13f9c/reuse \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp"}'

request.json

{
  "service": "whatsapp"
}

response.json

{
  "order_id": "f0271d",
  "number": "+7 901 234 56 78",
  "service": "whatsapp",
  "price": 0.07,
  "status": "waiting",
  "expires_at": "2026-07-31T19:04:00Z"
}

Аккаунт

Баланс, лимиты и статистика по аккаунту.

GET/balance

Баланс и лимиты

Текущий баланс аккаунта, действующий тариф и остаток лимитов.

curl

curl -s https://sim7.org/api/v1/balance \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx"

response.json

{
  "balance": 24.8,
  "currency": "USD",
  "plan": "api",
  "limits": {
    "concurrent_orders": 250,
    "active_orders": 3,
    "requests_per_minute": 600
  }
}

Вебхуки

Мгновенное уведомление о входящем коде и проверка подписи.

PUT/webhook

Настроить вебхук

Задаёт адрес обработчика и список событий. Секрет для подписи возвращается один раз при создании.

Параметры

Параметр	Где	Тип	Пример:
urlОбязательный	Тело	string	HTTPS-адрес обработчика.Пример: `https://sim7.org/webhooks/sim7`
eventsОбязательный	Тело	string	События: order.code_received, order.cancelled, balance.low.Пример: `order.code_received`
is_enabledОпциональный	Тело	boolean	Позволяет временно отключить доставку, не удаляя настройку.Пример: `true`

urlТелоОбязательный
HTTPS-адрес обработчика.
string · Пример: https://sim7.org/webhooks/sim7
eventsТелоОбязательный
События: order.code_received, order.cancelled, balance.low.
string · Пример: order.code_received
is_enabledТелоОпциональный
Позволяет временно отключить доставку, не удаляя настройку.
boolean · Пример: true

curl

curl -s -X PUT https://sim7.org/api/v1/webhook \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://sim7.org/webhooks/sim7","events":["order.code_received"]}'

request.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true
}

response.json

{
  "url": "https://sim7.org/webhooks/sim7",
  "events": ["order.code_received", "order.cancelled"],
  "is_enabled": true,
  "secret": "whsec_9f31c0a7d84b2e65",
  "updated_at": "2026-07-31T18:40:12Z"
}

POSThttps://sim7.org/webhooks/sim7

Событие order.code_received

Параметры

Параметр	Где	Тип	Пример:
eventОбязательный	Тело	string	Тип события.Пример: `order.code_received`
order_idОбязательный	Тело	string	Идентификатор заказа — используйте его как ключ идемпотентности.Пример: `a13f9c`
codeОбязательный	Тело	string	Код, извлечённый из текста сообщения.Пример: `482913`

eventТелоОбязательный
Тип события.
string · Пример: order.code_received
order_idТелоОбязательный
Идентификатор заказа — используйте его как ключ идемпотентности.
string · Пример: a13f9c
codeТелоОбязательный
Код, извлечённый из текста сообщения.
string · Пример: 482913

curl

# we send this request; here's how to replay it locally:
curl -s -X POST https://sim7.org/webhooks/sim7 \
  -H "Content-Type: application/json" \
  -H "X-Sim7-Signature: sha256=1f8c…" \
  -d '{"event":"order.code_received","order_id":"a13f9c","code":"482913"}'

request.json

{
  "event": "order.code_received",
  "order_id": "a13f9c",
  "number": "+7 901 234 56 78",
  "code": "482913",
  "text": "Your login code: 482913",
  "received_at": "2026-07-31T18:12:44Z"
}

response.json

{
  "received": true
}

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

Стабильные коды ошибок и частота запросов по тарифам.

Коды ошибок

Коды ошибок API Sim7
Код	HTTP	Что произошло
`invalid_request`	400	Некорректный запросТело или параметры не проходят валидацию: пропущено обязательное поле или неверный тип.
`unauthorized`	401	Ключ не принятЗаголовок Authorization отсутствует, ключ отозван или скопирован не полностью.
`ip_not_allowed`	403	IP не в списке разрешённыхКлюч верный, но запрос пришёл с адреса, которого нет в списке разрешённых для аккаунта.
`order_not_found`	404	Заказ не найденЗаказа с таким идентификатором нет или он принадлежит другому аккаунту.
`order_not_cancellable`	409	Заказ уже закрытОтмена доступна только для заказов в статусе waiting: код уже получен или окно истекло.
`insufficient_funds`	402	Недостаточно средствБаланса не хватает на выбранный номер. Заказ не создан, списания не было.
`no_numbers_available`	409	Нет свободных номеровПул для пары сервис + страна временно пуст. Повторите запрос позже или смените страну.
`price_changed`	409	Цена выше лимитаАктуальная цена превысила значение max_price из запроса. Обновите цену и повторите покупку.
`rate_limited`	429	Слишком много запросовПревышена частота запросов. Дождитесь числа секунд из заголовка Retry-After.
`concurrency_limit`	429	Лимит активных заказовДостигнут предел одновременных заказов по тарифу. Дождитесь завершения текущих.
`internal_error`	500	Внутренняя ошибкаСбой на нашей стороне. Запрос можно повторить с экспоненциальной задержкой.
`service_unavailable`	503	Сервис недоступенПлановые работы или деградация. Текущее состояние публикуем на странице статуса.

invalid_request400
Некорректный запрос
Тело или параметры не проходят валидацию: пропущено обязательное поле или неверный тип.
unauthorized401
Ключ не принят
Заголовок Authorization отсутствует, ключ отозван или скопирован не полностью.
ip_not_allowed403
IP не в списке разрешённых
Ключ верный, но запрос пришёл с адреса, которого нет в списке разрешённых для аккаунта.
order_not_found404
Заказ не найден
Заказа с таким идентификатором нет или он принадлежит другому аккаунту.
order_not_cancellable409
Заказ уже закрыт
Отмена доступна только для заказов в статусе waiting: код уже получен или окно истекло.
insufficient_funds402
Недостаточно средств
Баланса не хватает на выбранный номер. Заказ не создан, списания не было.
no_numbers_available409
Нет свободных номеров
Пул для пары сервис + страна временно пуст. Повторите запрос позже или смените страну.
price_changed409
Цена выше лимита
Актуальная цена превысила значение max_price из запроса. Обновите цену и повторите покупку.
rate_limited429
Слишком много запросов
Превышена частота запросов. Дождитесь числа секунд из заголовка Retry-After.
concurrency_limit429
Лимит активных заказов
Достигнут предел одновременных заказов по тарифу. Дождитесь завершения текущих.
internal_error500
Внутренняя ошибка
Сбой на нашей стороне. Запрос можно повторить с экспоненциальной задержкой.
service_unavailable503
Сервис недоступен
Плановые работы или деградация. Текущее состояние публикуем на странице статуса.

Частота запросов

Лимиты частоты запросов по тарифам
Тариф	Запросов в минуту	Примечание
Разовая покупка	60	До 10 одновременных активных заказов.
API для разработчиков	600	До 250 одновременных активных заказов.
Бизнес	По запросу	Лимиты согласуются под нагрузку, без ограничения одновременных заказов.
Тестовый ключ nx_test	120	Песочница без списаний, код приходит через 3–5 секунд.

Разовая покупка60
До 10 одновременных активных заказов.
API для разработчиков600
До 250 одновременных активных заказов.
БизнесПо запросу
Лимиты согласуются под нагрузку, без ограничения одновременных заказов.
Тестовый ключ nx_test120
Песочница без списаний, код приходит через 3–5 секунд.

Текущее состояние компонентов и историю инцидентов мы публикуем на странице статуса.

Готовы попробовать?

Получить ключ доступа Мои API-ключи

Базовый адрес

Заголовок авторизации

Начало работы

Аутентификация

Каталог и цены

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

Параметры

Список стран

Параметры

Цены и доступность

Параметры

Заказы

Купить номер

Параметры

Статус заказа и код

Параметры

История заказов

Параметры

Отменить заказ

Параметры

Повторная аренда номера

Параметры

Аккаунт

Баланс и лимиты

Вебхуки

Настроить вебхук

Параметры

Событие order.code_received

Параметры

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

Коды ошибок

Частота запросов

Готовы попробовать?

Собираем страницу

Базовый адрес

Заголовок авторизации

Начало работы

Аутентификация

Каталог и цены

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

Параметры

Список стран

Параметры

Цены и доступность

Параметры

Заказы

Купить номер

Параметры

Статус заказа и код

Параметры

История заказов

Параметры

Отменить заказ

Параметры

Повторная аренда номера

Параметры

Аккаунт

Баланс и лимиты

Вебхуки

Настроить вебхук

Параметры

Событие order.code_received

Параметры

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

Коды ошибок

Частота запросов

Готовы попробовать?