Szybki start z API dla deweloperów

API dla deweloperów SmsGrab daje Twojemu oprogramowaniu te same numery co aplikacja, przez REST API posługujące się formatem JSON. To płatny produkt z własnymi cenami dla deweloperów, opłacany z Twojego zwykłego salda SmsGrab i objęty tymi samymi automatycznymi zwrotami.

Kto może z niego korzystać

• Konto e-mail z potwierdzonym adresem. Konta gościa nie mogą tworzyć kluczy.
• Konto bez ograniczeń.

1. Utwórz klucz API

Otwórz Konto > Deweloperzy na stronie albo Ustawienia > API dla programistów w aplikacji i utwórz klucz. Ze względów bezpieczeństwa potwierdzasz to hasłem, a jeśli masz włączoną weryfikację dwuetapową, także jej kodem. Wybierz zakres read dla narzędzi tylko do odczytu albo read i purchase, aby kupować numery.

Klucz zaczyna się od sgk_ i jest pokazywany tylko raz. Przechowuj go w magazynie sekretów serwera. Zobacz Klucze API i bezpieczeństwo.

2. Uwierzytelnianie

Bazowy URL to https://smsgrab.com/api/dev/v1. Wysyłaj klucz jako token bearer albo w nagłówku X-Api-Key:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Klucze należą do serwerów. Nigdy nie umieszczaj ich na stronie, w rozszerzeniu przeglądarki ani w aplikacji, którą dajesz innym.

3. Sprawdź saldo i ceny

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Kwoty są zawsze podawane w jednostkach podstawowych USD, więc 18 oznacza 0,18 USD. price_minor to Twoja cena dla deweloperów, a retail_price_minor cena w aplikacji.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Kup numer

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service i country przyjmują nasze identyfikatory, takie jak whatsapp i indonesia. Kraje akceptują też kody ISO, na przykład ID.
• max_price_minor Cię chroni: jeśli cena wzrosła, nic nie zostaje pobrane i dostajesz 409 PRICE_CHANGED.
• Idempotency-Key sprawia, że ponowienia są bezpieczne. Powtórzenie żądania z tym samym kluczem zwraca pierwszy wynik zamiast kupować drugi raz.

Odpowiedź to 201 Created z aktywacją:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. Poczekaj na SMS

Zamiast odpytywać w ciasnej pętli, pozwól API wstrzymać żądanie do 30 sekund, aż coś się zmieni:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Gdy przyjdzie wiadomość, status zmienia się na CODE_RECEIVED, a sms zawiera wszystkie dotychczasowe wiadomości:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Wolisz powiadomienia push od odpytywania? Skonfiguruj webhooki.

6. Zakończ lub anuluj

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish po użyciu kodu. Jest akceptowane dopiero po nadejściu kodu.
• cancel, dopóki czekasz na pierwszy kod. Pełna cena zostaje zwrócona.
• Jeśli nic nie zrobisz, numer bez kodu wygaśnie po 20 minutach i zostanie zwrócony automatycznie.

Wartości statusu

Błędy

Każdy błąd ma ten sam kształt. Reaguj na code i reason, a nieznane Ci jeszcze powody ignoruj:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Częste przypadki to 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 z ACTIVATION_LIMIT_REACHED (na koncie może jednocześnie czekać maksymalnie 100 numerów) oraz 429 RATE_LIMITED z nagłówkiem Retry-After.

Pełną dokumentację znajdziesz w dokumentacji dla deweloperów.