API do weryfikacji SMS

API do weryfikacji SMS to trzy wywołania: kup numer, poczekaj na kod, zwolnij numer. Sięga do 517 serwisów w 225 krajach, numery zaczynają się od 0,07 €, a aktywacja, która nic nie odbierze, wraca na saldo bez zgłoszenia do obsługi. Klucze mają ograniczone uprawnienia, zakupy są idempotentne, a stare klienty handler_api działają bez zmian.

Otwórz dokumentację dla programistów Zacznij od €30

API w jednym bloku

Aktualizacja: 28 sie 2026

Adres bazowy: https://virtualsmsnumbers.com/api/v1
Uwierzytelnianie: Klucz bearer albo X-Api-Key
Limit żądań: 120/min, skok 20/s
Okno idempotencji: 24 godziny
Automatyczny zwrot po: 20 minut
Najtańsza aktywacja: 0,07 €
Kraje w zasięgu: 225
Format: JSON, centy, ISO 8601 UTC

Ceny i dostępność pochodzą z puli operatorskiej w jej bieżącym stanie, a nie z opublikowanego cennika.

Przepływ w trzech wywołaniach

Cała reszta dokumentacji jest opcjonalna. To jest pełna ścieżka weryfikacji i nie zmieniła się od 2019 roku.

1
POST /activations
Poproś o serwis, a jeśli ci na tym zależy, także o kraj. W odpowiedzi dostajesz numer, cenę w centach i znacznik czasu wygaśnięcia. Wyślij Idempotency-Key, żeby ponowione żądanie nie kupiło drugiego numeru, a jeśli wywołuje je automat, dodaj max_price_cents.
2
GET /activations/{id}?wait=180
Long polling. Połączenie jest trzymane otwarte, dopóki nie przyjdzie wiadomość albo nie minie timeout, więc jedno żądanie zastępuje pętlę, która wykonałaby ich dziewięćdziesiąt. Status wraca jako code_received, z rozpoznanym kodem obok surowej treści, bo nadawcy formatują je różnie.
3
POST /activations/{id}/complete
Zamknij aktywację i zwolnij linię. Jeśli nic nie przyszło, nie rób nic: okno wygaśnie samo, a saldo zostanie uznane. Wcześniejsze anulowanie to to samo wywołanie pod inną nazwą.

Działający przykład

Ustaw VSN_KEY i uruchom. Odpowiedzi w komentarzach to prawdziwe kształty, razem z polami, które warto u siebie zapisać.

buy-and-wait.sh

# 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"

Limity żądań

120 żądań na minutę na klucz, ze skokiem do 20 na sekundę. Każda odpowiedź niesie X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset, a 429 mówi, jak długo czekać, zamiast kazać ci zgadywać.

Limit rzadko bywa wąskim gardłem, jeśli używa się API zgodnie z przeznaczeniem: jeden long poll zamiast dziewięćdziesięciu odpytań, webhook zamiast timera i listy krajów oraz serwisów zbuforowane przy starcie. Jeśli naprawdę potrzebujesz większego zapasu, poproś — podniesienie limitu jest dla nas obu łatwiejsze niż debugowanie floty kluczy.

Idempotencja

Wyślij nagłówek Idempotency-Key przy POST /activations. Powtórzenie tego samego klucza w ciągu 24 godzin zwraca pierwotną aktywację w jej bieżącym stanie, z nagłówkiem Idempotent-Replay, zamiast kupować drugi numer i obciążać cię dwa razy.

Klucz nie jest skrótem z treści żądania: inny ładunek pod użytym już kluczem nadal zwróci pierwszą aktywację. Generuj jeden klucz na jeden logiczny zakup — UUID w zupełności wystarczy — i używaj go ponownie przy ponowieniach, nigdy między zakupami.

Stare klienty handler_api

Skrypty napisane pod klasyczny protokół handler_api.php działają dalej. Skieruj je na endpoint zgodności, podmień api_key, a te same akcje zwrócą te same tokeny ACCESS_ i STATUS_, co zawsze.

To warstwa tłumacząca nad tą samą pulą, więc ceny, dostępność i zwroty zachowują się identycznie w obu wariantach. Nowy kod powinien mimo wszystko korzystać z /api/v1: odpowiedzi JSON niosą znaczniki czasu, kody błędów i pola cenowe, na które format tokenowy nie ma miejsca.

legacy-compat.sh

# 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

Agenty, MCP i wykrywalność

Mamy hostowany serwer MCP, dokument OpenAPI 3.1 i indeks llms.txt, więc agent może wykryć trzy potrzebne mu narzędzia bez ręcznie pisanego kleju. Skieruj klienta na poniższy endpoint, a znajdzie zakup, oczekiwanie i zwolnienie numeru.

Zanim pozwolisz czemukolwiek autonomicznemu wydawać saldo: ogranicz klucz do numbers:read i numbers:write, ustaw pułap max_price_cents przy każdym zakupie i daj mu własny klucz, żeby jego unieważnienie nie położyło twojej integracji produkcyjnej.

Schemat OpenAPI 3.1 Indeks llms.txt

mcp.json

{
  "mcpServers": {
    "virtualsmsnumbers": {
      "type": "http",
      "url": "https://virtualsmsnumbers.com/api/mcp",
      "headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
    }
  }
}

Zanim wejdziesz na produkcję

Ustawiaj max_price_cents przy każdym zakupie. Ceny idą za pulą, a agent bez ograniczenia z ochotą kupi jej drogi koniec.
Traktuj identyfikatory jak nieprzezroczyste ciągi. Identyfikatory aktywacji mają dziś dziesięć cyfr; to nie jest obietnica, tak samo jak ich długość.
Rozgałęziaj kod na kodzie błędu, nigdy na komunikacie. Kody są stabilne w obrębie wersji; komunikaty pisze się dla ludzi i bywają przepisywane.
Zasubskrybuj sms.received i weryfikuj podpis — HMAC-SHA256 z surowego ciała, z pięciominutowym oknem powtórzeń — zamiast odpytywać o stan, o którym możemy ci powiedzieć sami.
Licz na całkowitych polach w centach. Sformatowane ciągi obok nich są do wyświetlania i zależą od ustawień regionalnych.

Pełna dokumentacja

Sześć endpointów, tabele błędów, ładunki webhooków, uprawnienia i mapa starych tokenów.

Otwórz dokumentację dla programistów

Odbierz SMS online Numer tymczasowy Aktualne ceny

Najczęstsze pytania

Mediana dostarczenia jest poniżej dziewięciu sekund od chwili wysłania przez serwis. Long polling istnieje, bo ogon rozkładu jest długi: aktywacja pozostaje otwarta przez 20 minut i wygasa w zwrot, jeśli nic nie przyjdzie.

Nic, co musiałbyś obsłużyć. Okno się zamyka, saldo zostaje uznane automatycznie, a aktywacja kończy się w stanie wygasłym, który odczytasz z API.

Tak, i nic to nie kosztuje. Klucze mają stałe uprawnienia, opcjonalną listę dozwolonych adresów IP i termin ważności wybrany przy tworzeniu, więc klucz testowy, który wycieknie, nie kupi numerów na produkcji.

Są cienkie wrappery bez zależności, ale to API ma sześć endpointów po JSON — fetch, requests albo curl naprawdę wystarczą do przepływu w trzech wywołaniach.

W ramach jednej aktywacji tak: kolejne wiadomości przychodzą na ten sam numer, dopóki jest otwarta. Między sesjami potrzebujesz wynajmu, który trzyma linię od czterech godzin do dwunastu miesięcy.

Nie. To ta sama pula w tych samych cenach; różni się wyłącznie kodowanie odpowiedzi.