Pornire rapidă cu API-ul pentru dezvoltatori

API-ul pentru dezvoltatori SmsGrab îi dă software-ului tău aceleași numere ca aplicația, printr-un API REST care folosește JSON. Este un produs plătit, cu propriile prețuri pentru dezvoltatori, plătit din soldul tău obișnuit SmsGrab și acoperit de aceleași rambursări automate.

Cine îl poate folosi

• Un cont cu e-mail și adresă confirmată. Conturile de invitat nu pot crea chei.
• Un cont fără restricții.

1. Creează o cheie API

Deschide Cont > Dezvoltatori pe site sau Setări > API pentru dezvoltatori în aplicație și creează o cheie. Pentru siguranță confirmi cu parola și, dacă este activată, cu codul verificării în doi pași. Alege domeniul read pentru unelte care doar citesc sau read și purchase ca să cumperi numere.

Cheia începe cu sgk_ și este afișată o singură dată. Păstreaz-o în depozitul de secrete al serverului. Vezi Chei API și securitate.

2. Autentificarea

URL-ul de bază este https://smsgrab.com/api/dev/v1. Trimite cheia ca token bearer sau în antetul X-Api-Key:

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

Cheile stau pe servere. Nu le pune niciodată într-un site, într-o extensie de browser sau într-o aplicație pe care o dai altora.

3. Verifică soldul și prețurile

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"

Sumele sunt date mereu în subunități de USD, deci 18 înseamnă 0,18 USD. price_minor este prețul tău pentru dezvoltatori, iar retail_price_minor prețul din aplicație.

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

4. Cumpără un număr

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 primesc id-urile noastre, de exemplu whatsapp și indonesia. Țările acceptă și coduri ISO, de exemplu ID.
• max_price_minor te protejează: dacă prețul a crescut, nu ți se ia nimic și primești 409 PRICE_CHANGED.
• Idempotency-Key face reîncercările sigure. Repetarea cererii cu aceeași cheie întoarce primul rezultat în loc să cumpere de două ori.

Răspunsul este 201 Created cu activarea:

{ "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. Așteaptă SMS-ul

În loc să interoghezi într-o buclă strânsă, lasă API-ul să țină cererea până la 30 de secunde, până se schimbă ceva:

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

Când sosește un mesaj, status devine CODE_RECEIVED, iar sms conține toate mesajele de până atunci:

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

Preferi push în loc de interogare? Configurează webhook-uri.

6. Finalizează sau anulează

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 după ce ai folosit codul. Este acceptat doar după ce a sosit un cod.
• cancel cât timp încă aștepți primul cod. Prețul întreg se rambursează.
• Dacă nu faci nimic, un număr fără cod expiră după 20 de minute și este rambursat automat.

Valorile stării

Erori

Fiecare eroare are aceeași formă. Reacționează la code și reason și ignoră motivele pe care nu le cunoști încă:

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

Cazuri frecvente sunt 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 cu ACTIVATION_LIMIT_REACHED (cel mult 100 de numere pot aștepta simultan pe un cont) și 429 RATE_LIMITED cu antetul Retry-After.

Referința completă este în documentația pentru dezvoltatori.