Rychlý start s API pro vývojáře

API pro vývojáře SmsGrab dává vašemu softwaru stejná čísla jako aplikace, přes REST API, které komunikuje ve formátu JSON. Je to placený produkt s vlastními cenami pro vývojáře, placený z vašeho běžného zůstatku SmsGrab a krytý stejným automatickým vracením peněz.

Kdo ho může používat

• E-mailový účet s potvrzenou adresou. Účty hostů nemohou vytvářet klíče.
• Účet bez omezení.

1. Vytvořte klíč API

Otevřete na webu Účet > Vývojáři, nebo v aplikaci Nastavení > API pro vývojáře, a vytvořte klíč. Z bezpečnostních důvodů to potvrdíte heslem, a pokud máte zapnuté dvoufázové ověření, i jeho kódem. Zvolte rozsah read pro nástroje, které jen čtou, nebo read a purchase pro nákup čísel.

Klíč začíná sgk_ a zobrazí se jen jednou. Uložte ho do úložiště tajných údajů na serveru. Viz Klíče API a zabezpečení.

2. Ověření

Základní URL je https://smsgrab.com/api/dev/v1. Posílejte klíč jako bearer token, nebo v hlavičce X-Api-Key:

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

Klíče patří na servery. Nikdy je nevkládejte do webu, rozšíření prohlížeče ani do aplikace, kterou dáváte jiným lidem.

3. Zjistěte zůstatek a 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"

Peníze se vždy uvádějí v nejmenších jednotkách USD, takže 18 znamená 0,18 USD. price_minor je vaše cena pro vývojáře a retail_price_minor cena v aplikaci.

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

4. Kupte číslo

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 a country přijímají naše identifikátory, například whatsapp a indonesia. Země přijímají i kódy ISO, například ID.
• max_price_minor vás chrání: pokud cena mezitím stoupla, nic se nestrhne a dostanete 409 PRICE_CHANGED.
• Idempotency-Key dělá opakování bezpečnými. Zopakování požadavku se stejným klíčem vrátí první výsledek, místo aby se nakoupilo dvakrát.

Odpověď je 201 Created s aktivací:

{ "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. Počkejte na SMS

Místo dotazování v těsné smyčce nechte API podržet požadavek až 30 sekund, dokud se něco nezmění:

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

Když přijde zpráva, status se změní na CODE_RECEIVED a sms obsahuje všechny dosavadní zprávy:

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

Dáváte přednost push před dotazováním? Nastavte webhooky.

6. Dokončete nebo zrušte

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, jakmile kód použijete. Přijme se až poté, co kód dorazí.
• cancel, dokud ještě čekáte na první kód. Celá cena se vrátí.
• Pokud nic neuděláte, číslo bez kódu po 20 minutách vyprší a peníze se vrátí automaticky.

Hodnoty stavu

Chyby

Každá chyba má stejný tvar. Reagujte na code a reason a důvody, které zatím neznáte, ignorujte:

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

Časté případy jsou 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 s ACTIVATION_LIMIT_REACHED (na jednom účtu může současně čekat nejvýše 100 čísel) a 429 RATE_LIMITED s hlavičkou Retry-After.

Úplnou referenci najdete v dokumentaci pro vývojáře.