Ověřovací SMS kódy (OTP) přes API: přihlášení a registrace za 15 minut

Ověření telefonu SMS kódem je nejčastější důvod, proč vývojář hledá SMS bránu. Registrace bez falešných účtů, přihlášení s druhým faktorem, potvrzení platby nebo změny údajů. Samotné odeslání SMS je snadné. Složitější je všechno kolem: generování kódu, jeho bezpečné uložení, platnost, počet pokusů a ochrana proti tomu, aby vám někdo přes formulář nerozeslal tisíce SMS na vaše náklady.

Přesně tohle řeší Verify API. Jedním voláním pošlete kód, druhým ho ověříte. Kód negenerujete ani neukládáte, limity hlídáme my.

Jak to funguje

1. Uživatel zadá telefon. Váš server zavolá POST /api/verify/send.
2. Uživatel dostane SMS, například „MojeFirma: vas overovaci kod je 482913. Plati 5 min. Nikomu ho nesdelujte.“
3. Uživatel opíše kód. Váš server zavolá POST /api/verify/check a dostane valid: true, nebo false.

Text je záměrně bez diakritiky, aby se vešel do jedné SMS (s diakritikou má SMS jen 70 znaků). Pro zahraniční uživatele pošlete "locale": "en".

Co budete potřebovat

• Účet TopSMS. Registrace je zdarma, nový účet má 10 SMS na vyzkoušení.
• API klíč z dashboardu (sekce API přístup). Na vývoj si vytvořte testovací klíč: nic neodesílá ani neúčtuje a kód je vždy 123456.

1. Odeslání kódu

curl -X POST https://www.topsms.cz/api/verify/send \
  -H "Authorization: Bearer CLIENT_ID:SECRET" \
  -H "Content-Type: application/json" \
  -d '{"to": "+420601234567", "brand": "MojeFirma"}'

Odpověď:

{ "ok": true, "id": "cmv8k2...", "to": "+420601234567", "status": "pending",
  "expiresAt": "2026-09-29T14:05:00.000Z", "price": 0.98 }

Hodnotu id si uložte k relaci uživatele. Volitelně nastavíte délku kódu (length, 4 až 8 číslic), platnost (ttl, 60 až 1800 sekund) a vlastní jméno odesílatele (from), pokud ho máte schválené.

2. Ověření kódu

curl -X POST https://www.topsms.cz/api/verify/check \
  -H "Authorization: Bearer CLIENT_ID:SECRET" \
  -H "Content-Type: application/json" \
  -d '{"id": "cmv8k2...", "code": "482913"}'

{ "valid": true, "status": "approved" }

Při špatném kódu přijde { "valid": false, "status": "pending", "attemptsLeft": 4 }. Po pěti špatných pokusech je kód zablokovaný (failed), po vypršení expired. Jednou schválený kód nejde použít znovu.

Ukázka v PHP

function topsms(string $path, array $body): array {
    $ch = curl_init('https://www.topsms.cz' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('TOPSMS_TOKEN'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($body),
    ]);
    $res = json_decode(curl_exec($ch), true);
    curl_close($ch);
    return $res ?? [];
}

// registrace: poslat kód
$v = topsms('/api/verify/send', ['to' => $_POST['phone'], 'brand' => 'MojeFirma']);
$_SESSION['verify_id'] = $v['id'] ?? null;

// druhý krok: ověřit kód
$r = topsms('/api/verify/check', ['id' => $_SESSION['verify_id'], 'code' => $_POST['code']]);
if (!empty($r['valid'])) {
    // telefon ověřen, aktivujte účet
}

Ukázka v Node.js

const topsms = (path, body) =>
  fetch('https://www.topsms.cz' + path, {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.TOPSMS_TOKEN, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  }).then(r => r.json())

const { id } = await topsms('/api/verify/send', { to: '+420601234567', brand: 'MojeFirma' })
// ... uživatel opíše kód ...
const { valid } = await topsms('/api/verify/check', { id, code: userCode })

Bezpečnost: co hlídáme my a co vy

Na naší straně:

• Kód ukládáme jen jako HMAC otisk. V databázi ani v logu ho v čitelné podobě nenajdete.
• Na jeden kód 5 pokusů, porovnání v konstantním čase.
• Na jedno číslo nejvýš 5 kódů za hodinu a 30 sekund mezi dvěma kódy (odpověď 429 s polem code: "rate_limited" nebo "cooldown"). Útočník vám tak přes jedno číslo nenafouká účet.
• Nový kód na stejné číslo předchozí nevyřízený kód zneplatní.

Na vaší straně:

• Volejte API jen ze serveru, nikdy z prohlížeče nebo mobilní aplikace. API klíč do klientského kódu nepatří.
• Omezte počet odeslání i na úrovni vaší aplikace, třeba na IP adresu a účet. Chrání vás to před rozesíláním na mnoho různých čísel.
• Ověřené id svažte s konkrétní relací uživatele, ať nejde použít cizí ověření.
• Na přihlášení zvažte CAPTCHA před odesláním kódu, pokud je formulář veřejný.

Testovací režim

S testovacím klíčem odladíte celý tok bez telefonu a bez nákladů. verify/send nic neodešle, v odpovědi vrátí "test": true a testCode a kód je vždy 123456. Všechna volání vidíte v dashboardu u klíče v sekci Log a webhook, včetně těla požadavku a odpovědi.

Kolik to stojí

Platíte jen odeslanou SMS podle ceníku: 0,88 až 0,98 Kč za kód do Česka a na Slovensko, bez paušálu a bez poplatku za ověření. Kredit nepropadá. Ověření samotné, limity i testovací klíče jsou zdarma.

Kde pokračovat

• Verify API: kompletní popis
• REST API dokumentace a OpenAPI specifikace pro Postman nebo Insomnia
• Webhooky pro doručenky u běžných SMS

Potřebujete poradit s napojením? Napište na info@topsms.cz.