API для отримання СМС
API для отримання СМС — це три виклики: купити номер, дочекатися коду, звільнити номер. Він сягає 517 сервісів у 225 країнах, номери починаються від 0,07 EUR, а активація, на яку нічого не надійшло, повертається без звернення до підтримки. Ключі мають scope, купівлі ідемпотентні, а старі клієнти handler_api працюють без змін.
API одним блоком
Оновлено 28 серп. 2026 р.- Базовий URL
- https://virtualsmsnumbers.com/api/v1
- Автентифікація
- Bearer-ключ або X-Api-Key
- Ліміт запитів
- 120/хв, сплеск 20/с
- Вікно ідемпотентності
- 24 години
- Автоповернення через
- 20 хвилин
- Найдешевша активація
- 0,07 EUR
- Країн охоплено
- 225
- Формат
- JSON, центи, ISO 8601 UTC
Ціни й наявність беруться з операторського пулу в його теперішньому стані, а не з опублікованого прайс-листа.
Потік із трьох викликів
Усе інше в довіднику необов’язкове. Це весь шлях верифікації, і він не змінювався з 2019 року.
- 1
POST /activations
Запитайте сервіс і, якщо вам не байдуже, країну. У відповіді прийдуть номер, ціна в центах і час спливання. Передайте Idempotency-Key, щоб повторений запит не купив другий номер, і max_price_cents, якщо сторона, що викликає, автоматична.
- 2
GET /activations/{id}?wait=180
Довге опитування. З’єднання тримається відкритим, доки не надійде повідомлення або не спливе таймаут, тож один запит замінює цикл, який зробив би дев’яносто. Статус повертається як code_received: розібраний код і поруч сирий текст, бо відправники форматують його по-різному.
- 3
POST /activations/{id}/complete
Закрийте активацію і звільніть лінію. Якщо нічого не надійшло, не робіть узагалі нічого: вікно спливе саме, а баланс повернеться. Дострокове скасування — той самий виклик під іншою назвою.
Робочий приклад
Задайте VSN_KEY і запустіть. Відповіді в коментарях — справжні форми, разом із полями, які ви захочете зберегти.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Ліміти запитів
120 запитів на хвилину на ключ, сплеск до 20 на секунду. У кожній відповіді приходять X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset, а 429 каже, скільки чекати, замість того щоб змушувати вас гадати.
Ліміт рідко стає обмеженням, якщо API використовують за призначенням: одне довге опитування замість дев’яноста, вебхук замість таймера і переліки країн та сервісів, закешовані на старті. Якщо запас справді потрібен — попросіть: підняти ліміт простіше для нас обох, ніж налагоджувати парк ключів.
Ідемпотентність
Передавайте заголовок Idempotency-Key у POST /activations. Повтор із тим самим ключем протягом 24 годин поверне початкову активацію в її теперішньому стані, із заголовком Idempotent-Replay, замість купівлі другого номера й другого списання.
Ключ не є хешем тіла: інший payload під уже використаним ключем однаково поверне першу активацію. Генеруйте по одному ключу на логічну купівлю — UUID цілком підійде — і перевикористовуйте його між повторами, але ніколи між купівлями.
Старі клієнти handler_api
Скрипти, написані під класичний протокол handler_api.php, працюють далі. Спрямуйте їх на сумісний ендпоїнт, замініть api_key — і ті самі дії повернуть ті самі токени ACCESS_ і STATUS_, що й завжди.
Це шар перекладу над тим самим пулом, тож ціни, залишки й повернення поводяться однаково в обох випадках. Новий код усе ж варто писати на /api/v1: у JSON-відповідях є мітки часу, коди помилок і поля цін, для яких у токенах місця немає.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Агенти, MCP і виявлення
Є розміщений MCP-сервер, документ OpenAPI 3.1 та індекс llms.txt, тож агент знайде потрібні йому три інструменти без написаної вручну обв’язки. Спрямуйте клієнт на ендпоїнт нижче, і він виявить купівлю, очікування та звільнення.
Перш ніж дозволити чомусь автономному витрачати баланс: обмежте ключ до scope numbers:read і numbers:write, задайте стелю max_price_cents на кожну купівлю й видайте йому окремий ключ, щоб його відкликання не поклало вашу бойову інтеграцію.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Перед продакшеном
- Задавайте max_price_cents на кожну купівлю. Ціни рухаються разом із пулом, і необмежений агент залюбки купить його дорогий кінець.
- Вважайте ідентифікатори непрозорими рядками. Ідентифікатори активацій сьогодні десятизначні; це не обіцянка, як і їхня довжина.
- Розгалужуйтеся за кодом помилки, а не за текстом. Коди стабільні в межах версії; тексти написані для людей і їх переписують.
- Підпишіться на sms.received і перевіряйте підпис — HMAC-SHA256 по сирому тілу, з вікном повтору в п’ять хвилин — замість опитування стану, про який вам можуть повідомити самі.
- Рахуйте арифметику за цілочисловими полями в центах. Відформатовані рядки поруч із ними потрібні для відображення й залежать від локалі.
Повний довідник
Шість ендпоїнтів, таблиці помилок, корисні навантаження вебхуків, scope і мапа старих токенів.
Часті запитання
Медіанна доставка — менш ніж дев’ять секунд від миті надсилання сервісом. Довге опитування існує тому, що хвіст довгий: активація лишається відкритою 20 хвилин і спливає у повернення, якщо нічого не надійшло.
Нічого, що потрібно обробляти. Вікно закриється, баланс повернеться автоматично, а активація завершиться у стані expired, який можна прочитати через API.
Так, і це нічого не коштує. Ключі мають фіксовані scope, необов’язковий перелік дозволених IP і термін дії, обраний при створенні, тож ключ стенду, який витік, не купить номери у проді.
Є тонкі обгортки без залежностей, але API — це шість ендпоїнтів поверх JSON: для потоку з трьох викликів чесно вистачає fetch, requests або curl.
У межах однієї активації — так: додаткові повідомлення приходять на той самий номер, поки вона відкрита. Між сесіями потрібна оренда, яка тримає лінію від чотирьох годин до дванадцяти місяців.
Ні. Це той самий пул за тими самими цінами; відрізняється лише кодування відповідей.