Dokumentace API

Odesílání SMS a ověřování telefonních čísel jedním voláním. Základní adresa je https://sms.wopro.cz/api/v1.

Vytvořit API klíč Ceník

Začínáme

Všechna volání jsou JSON, odpověď má vždy pole ok. Při chybě je ok:false, kód v error a lidská věta česky v message.

1. Přihlas se účtem Wopro a ověř totožnost (KYC), bez toho se neodesílá.
2. Dobij kredit (od 50 Kč, kartou přes GoPay).
3. V části API klíče vytvoř klíč. Zobrazí se celý jen jednou.

# uložit klíč na server do proměnné prostředí
export WOPRO_SMS_KEY=sk_live_...

# ověřit, že klíč funguje (nic neúčtuje)
curl https://sms.wopro.cz/api/v1/ping -H "Authorization: Bearer $WOPRO_SMS_KEY"

# poslat zprávu (účtuje se z kreditu)
curl https://sms.wopro.cz/api/v1/sms \
  -H "Authorization: Bearer $WOPRO_SMS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+420777123456","text":"Dobrý den, objednávka je na cestě."}'

Ověření klíčem

Pošli klíč v hlavičce Authorization: Bearer sk_live_… (nebo X-API-Key). Každá zpráva odeslaná klíčem se účtuje z kreditu tvé organizace. Klíč uvidíš celý jen při vytvoření, uchovej ho na serveru, nikdy v aplikaci v telefonu ani na webu. Když unikne, zruš ho v části API klíče a vytvoř nový.

Odeslat SMS POST /v1/sms

// odpověď 200
{
  "ok": true,
  "message": {
    "id": "msg_9f2c4a7d51e08b3a6c1d4e7f",
    "to": "+420777123456",
    "sender": "SMSpro",
    "status": "sent",
    "parts": 1,
    "encoding": "ucs2",
    "price_czk": 1.4,
    "reference": null,
    "created_at": "2026-10-14T09:20:11+00:00",
    "error": null
  }
}

Stavy: queued čeká, sent předáno operátorovi, delivered doručeno, undelivered nedoručeno (telefon vypnutý), failed a rejected odmítnuto (cena se vrací).

Odhad ceny POST /v1/sms/estimate

Tělo {"text":"…","to":"+420…","encoding":"auto"}. Vrací parts, chars, encoding a price_czk. Nic se neodešle ani neúčtuje.

Stav a historie

GET /v1/sms/{id} vrátí zprávu. GET /v1/sms?limit=20&status=delivered&reference=…&before=msg_… vrací seznam od nejnovějších a next_before pro další stránku. GET /v1/balance vrací zůstatek kreditu, GET /v1/pricing ceník (bez klíče).

Ověření telefonního čísla kódem

Nemusíš kódy vyrábět ani hlídat. Kód má platnost (výchozí 5 minut), nejvýš 5 pokusů o zadání, nový kód zneplatní starý a na jedno číslo jdou nejvýš 3 kódy za 10 minut. Odeslání kódu se účtuje jako jedna SMS.

# 1. pošli kód
curl https://sms.wopro.cz/api/v1/verify -H "Authorization: Bearer $WOPRO_SMS_KEY" -H "Content-Type: application/json" \
  -d '{"to":"+420777123456","brand":"Vaše firma"}'
# → {"ok":true,"verification":{"id":"ver_…","status":"pending","expires_at":"…","resend_after":30}}

# 2. zkontroluj, co člověk opsal
curl https://sms.wopro.cz/api/v1/verify/check -H "Authorization: Bearer $WOPRO_SMS_KEY" -H "Content-Type: application/json" \
  -d '{"id":"ver_…","code":"482913"}'
# → {"ok":true,"verification":{"status":"verified","valid":true,…}}

Volitelná pole startu: length (4 až 8), ttl (60 až 900 s), template (text s {code}, {brand}, {minutes}), sender, reference. Kontrolu jde zadat i podle čísla: {"to":"…","code":"…"}. Text zprávy se u nás ukládá se zakrytým kódem.

Webhooky

Adresu nastavíš v účtu (Nastavení) nebo u zprávy v callback_url. Při každé změně stavu (sent, delivered, undelivered, failed) pošleme POST s JSON {"type":"sms.delivered","created":1791970000,"data":{…zpráva…}}. Odpověz kódem 2xx. Při chybě to zkusíme znovu za 30 s, 2 min, 10 min, 1 h a 6 h.

Pravost ověř podpisem v hlavičce X-SMSpro-Signature: t=<čas>,v1=<hex>, kde v1 je HMAC-SHA256 z řetězce čas.tělo s tvým tajemstvím webhooku:

// PHP
[$t, $v1] = array_map(fn($p) => explode('=', $p, 2)[1], explode(',', $_SERVER['HTTP_X_SMSPRO_SIGNATURE']));
$body = file_get_contents('php://input');
$ok = hash_equals(hash_hmac('sha256', $t . '.' . $body, $tajemstvi), $v1) && abs(time() - (int)$t) < 300;

Limity a ochrana

• Jen mobilní čísla a jen povolené země (výchozí CZ a SK, další povolíš v nastavení).
• Výchozí limity: 60 zpráv za minutu, 300 za den a 300 Kč za den na účet. Zvýšení na požádání.
• Na jedno číslo nejvýš 6 běžných zpráv za hodinu (ověřovací kódy mají přísnější pravidla výše).
• Zprávy odešleme až po stržení kreditu. Když zpráva natrvalo selže, cena se vrátí.

Chyby

Služby Wopro

Aplikace platformy Wopro (například Eshopland nebo Onlinepet) volají Wopro SMS napřímo, bez API klíče: POST /v1/service/sms, POST /v1/service/verify, POST /v1/service/verify/check a GET /v1/service/balance. Každé volání nese ?service_slug=<služba>&org=<organizace> a hlavičku X-Service-Secret (tajemství služby Wopro). Parametr org jde vynechat: pak se účtuje organizaci, kterou má služba nastavenou na serveru Wopro SMS (aplikace platformy tak nic dalšího neposílají).

• Kdo platí: organizace z org (uživatel, za kterého aplikace posílá). Strhne se z jejího kreditu Wopro, a jen když to organizace povolila na stránce Aplikace Wopro. Jinak odpověď 403 org_not_allowed.
• Kolik: cenu určuje vždy Wopro SMS podle ceníku a vrací ji v odpovědi jako price_czk. Aplikace může v těle poslat max_price_czk, tedy nejvyšší cenu, kterou uživatel odsouhlasil. Vyjde-li zpráva dráž, přijde 422 price_exceeds_limit a nic se neodešle ani nestrhne.
• Kdo to uvidí: zpráva nese název aplikace (service v odpovědi). Organizace ji vidí v Historii se sloupcem Odkud a útratu po aplikacích na stránce Aplikace Wopro, správce Wopro SMS vidí útratu každé aplikace i jednotlivých organizací přes ni.
• KYC: u volání od aplikací Wopro se nevyžaduje, odpovídá za něj aplikace.

POST https://sms.wopro.cz/api/v1/service/sms?service_slug=czechday&org=3F2A…(32 znaků)
X-Service-Secret: <tajemství služby>
{"to":"+420777123456","text":"Dobrý den, váš lístek je připravený.","reference":"order-1042","max_price_czk":1.4}

Máš otázku, kterou tu nenajdeš? Napiš na [email protected].