API аренды номеров
Арендуйте номер на фиксированный срок и читайте все входящие SMS через совместимый endpoint handler_api.php.
Как это работает
Каждый запрос это GET на /stubs/handler_api.php с api_key и action. Действия аренды отвечают в JSON как при успехе, так и при ошибке.
Для действий аренды принимается только аутентификация по API-ключу. Токены веб-сессии получают WRONG_ACTION.
Цены такие же, как в веб-панели, списание идёт в USD с вашего баланса.
Действия
| Действие | Параметры | Что делает |
|---|---|---|
getRentServicesAndCountries | country, rent_time | Предложения аренды с ценами для одной страны и срока. services.{code}.cost это цена, quant это доступный остаток. |
getRentNumber | service, country, rent_time | Арендует номер и списывает средства. Возвращает phone.id, phone.number и phone.endDate. |
getRentStatus | id, page, size | SMS, полученные арендованным номером, сначала новые. Необязательные page (с 0) и size. |
setRentStatus | id, status (1 | 2) | status=1 досрочно завершает аренду без возврата. status=2 отменяет её; полный возврат только если не пришло ни одного SMS. |
continueRentNumber | id, rent_time, expectedCharge | Продлевает активную аренду на rent_time часов и списывает средства. |
getRentList | - | Ваши активные аренды: id и phone. |
getContinueRentPriceNumber | id, rent_time | Стоимость продления аренды без списания. |
Коды стран
- Аренда доступна в 27 странах: AT, BE, BR, CZ, DE, EE, ES, FI, FR, GB, GE, GR, HR, ID, IT, LV, MD, MY, NL, PL, PT, RO, SE, SI, SK, UA, US. Для аренды номера и запроса цен параметр country обязателен; рекомендуется двухбуквенный ISO-код. Сроки: 24, 72, 168 часов.
- Чтобы получить этот список через API, вызовите getRentServicesAndCountries без country: в ответе будут countryList (ISO-коды), hours и currency, без цен и остатков. Для цен и остатков передайте country и rent_time.
- Рекомендуется передавать ISO-код страны, например country=US или country=GB. Регистр букв не важен.
- Числовые ID стран различаются между сервисами. Если вы передаёте число, берите его из ответа getCountries для своего API-ключа; не копируйте его из списка другого провайдера.
- Действия аренды принимают числовой ID только для стран, доступных для аренды, в том виде, как он указан в getCountries. Любое другое число возвращает BAD_COUNTRY; если сомневаетесь, используйте ISO-код.
- Числа 42 (DE), 44 (HR), 45 (SE), 47 (NL), 48 (LV), 49 (AT), 51 (TH), 55 (ES), 58 (SI), 62 (CZ), 72 (BR), 77 (FR), 90 (SK), 97 (PT), 115 (GE), 116 (GR), 128 (BE), 175 (FI), 178 (IT) не принимаются для аренды, так как в других сервисах они обозначают другую страну. Они всегда возвращают BAD_COUNTRY_USE_ISO; деньги не списываются, номер не арендуется. Вместо них передавайте ISO-код, например country=DE. Для этих стран поле countries в ответе getRentServicesAndCountries пустое.
- Также принимается наш slug страны.
- getRentServicesAndCountries возвращает числовой ID страны в countries.
Список стран и их кодов
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getCountries"Предложения аренды для страны по ISO-коду
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries&country=US&rent_time=24"Список стран, доступных для аренды
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentServicesAndCountries"Ответ
{"countryList":["AT","BE","BR","CZ","DE","EE","ES","FI","FR","GB","GE","GR","HR","ID","IT","LV","MD","MY","NL","PL","PT","RO","SE","SI","SK","UA","US"],"hours":[24,72,168],"currency":840}Пример
Запрос
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentNumber&service=wa&country=US&rent_time=24"Ответ
{
"status": "success",
"phone": {
"id": "cm4x9k2...",
"endDate": "2026-11-02T12:00:00",
"number": "15550000001"
}
}Запрос
curl "https://smsbulk.net/stubs/handler_api.php\
?api_key=YOUR_KEY&action=getRentStatus&id=cm4x9k2..."Ответ
{
"status": "success",
"quantity": "1",
"values": {
"0": {
"phoneFrom": "WhatsApp",
"text": "Your code: 123456",
"service": "wa",
"date": "2026-11-01 12:05:00"
}
}
}Детали ответа
- id аренды это строка (например "cm4x9k2..."), а не число. Храните его как текст.
- Срок в часах читается из rent_time; параметр time тоже принимается.
- Если срок не передан, используется самый короткий доступный срок (сейчас 24 часа). Передавайте rent_time явно при аренде и продлении.
- currency равно 840 (USD). cost и price это числа в USD.
- endDate и даты SMS указаны в UTC, без суффикса часового пояса.
- Параметр url игнорируется: аренда не отправляет webhook. Опрашивайте getRentStatus, чтобы читать новые SMS.
- Ошибки возвращаются как {"status":"error","message":"<CODE>"}. Ошибки аутентификации и лимита запросов остаются в текстовом формате (BAD_KEY, RATE_LIMITED).
- Перед continueRentNumber получите цену через getContinueRentPriceNumber. Списанная сумма никогда не превышает последнюю показанную вам цену (действует 10 минут, та же аренда и rent_time). Необязательный expectedCharge (USD, например 1.334) может только снизить этот потолок, но не поднять его. Если цена выше потолка или у вас нет действующей цены, аренда не продлевается, ничего не списывается и возвращается новая цена: WRONG_CHARGE, сумма в поле price. Повторите запрос с новой ценой.
- Аренду можно продлить только после окончания окна бесплатной отмены (первые 20 минут); до этого continueRentNumber возвращает CONTINUE_TOO_EARLY и ничего не списывается.
Окно отмены
В первые 2 минуты аренды отмена отклоняется (CANT_CANCEL).
Бесплатная отмена возможна до 20 минут после начала аренды. После этого окна отмена отклоняется, обычно с CANT_CANCEL (в редких случаях TEMPORARILY_UNAVAILABLE); вместо этого завершите аренду через status=1.
Отменённая аренда возвращается полностью только если не получила ни одного SMS.
Таймауты и повторы
getRentNumber не идемпотентен: не повторяйте его после таймаута. Сначала вызовите getRentList; если найдёте ненужную аренду, отмените её между 2-й и 20-й минутой для полного возврата (если SMS не было).
Лимиты
Новые аренды ограничены для каждого API-ключа в сутки UTC (продления не считаются): не больше 50 аренд на ключ. Сверх лимита: RENT_LIMIT.
getRentNumber и continueRentNumber также учитываются в дневной квоте покупок ключа.
Эти действия доступны для всех API-ключей вашего аккаунта.
Коды ошибок
{ "status": "error", "message": "NO_BALANCE" }NO_ | Недостаточно средств на балансе. |
NO_ | Сейчас нет номера для этого сервиса, страны и срока. |
BAD_ | Код сервиса отсутствует или не поддерживается. |
BAD_ | Страна не указана, неизвестна или недоступна (используйте ISO-код). |
BAD_ | Числовой ID страны не принимается для аренды (в других сервисах он обозначает другую страну). Используйте ISO-код; деньги не списываются. Эти числа перечислены в разделе «Коды стран». В ответе также есть понятное поле description. |
BAD_ | Такой срок не предлагается. |
NO_ | Не передан параметр id. |
INVALID_ | На вашем аккаунте нет аренды с таким id. |
INCORECT_ | status в setRentStatus должен быть 1 или 2. |
CANT_ | Отмена сейчас невозможна (в первые 2 минуты или после бесплатного окна до 20 минут). |
ALREADY_ | Аренда уже завершена. |
ALREADY_ | Аренда уже отменена. |
STATUS_ | Аренда активна, но SMS ещё не пришло. |
STATUS_ | Аренда отменена. |
STATUS_ | Аренда завершена или истекла. |
RENT_ | Достигнут дневной лимит аренд для этого API-ключа. |
TEMPORARILY_ | Временная проблема. Для getRentNumber и continueRentNumber средства не списаны или возвращены. При отмене результат может быть неизвестен: перед повтором проверьте аренду через getRentStatus. |
WRONG_ | continueRentNumber: цена выше вашего потолка (последняя показанная вам цена, действует 10 минут, сниженная expectedCharge) или у вас нет действующей цены. Аренда не продлена, ничего не списано. Новая цена в поле price; повторите с ней. |
CONTINUE_ | continueRentNumber: продление недоступно в первые 20 минут аренды (окно бесплатной отмены). Ничего не списано; повторите после этого. getContinueRentPriceNumber работает и в это время. |
ERROR_ | Непредвиденная ошибка сервера. |
REST API
Те же операции доступны для всех API-ключей как JSON-эндпоинты в /api/v1/rentals (передайте ключ в заголовке x-api-key). Дневной лимит аренд на ключ общий с действиями выше; сверх лимита REST API отвечает 429 с причиной rent_daily_cap.
curl -X POST "https://smsbulk.net/api/v1/rentals" \
-H "x-api-key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "serviceCode": "wa", "countryIso": "US", "durationHours": 24 }'Продление: сначала получите цену через GET /api/v1/rentals/{id}/extend-price, затем вызовите POST /api/v1/rentals/{id}/extend. Списанная сумма никогда не превышает последнюю показанную вам цену (действует 10 минут, та же аренда и срок). Необязательный expectedCharge (USD строкой, например "1.334") может только снизить этот потолок, но не поднять его. Если цена выше потолка или у вас нет действующей цены, аренда не продлевается, ничего не списывается и API отвечает 409 PRICE_CHANGED с новой ценой в currentCharge. Повторите запрос с новой ценой.
В первые 20 минут аренды (окно бесплатной отмены) POST /api/v1/rentals/{id}/extend отвечает 409 RENTAL_EXTEND_TOO_EARLY; в теле есть extendAllowedFrom (время в формате ISO), момент, с которого продление принимается. Ничего не списывается, запрос цены остаётся доступным.