Verify API
ověřovací kódy SMS

1. Odeslání kódu

POST https://www.topsms.cz/api/verify/send
Authorization: Bearer CLIENT_ID:SECRET

{ "to": "+420601234567", "brand": "MojeFirma", "length": 6, "ttl": 300 }

Odpověď obsahuje id ověření, expiresAt a cenu. Zákazník dostane SMS „MojeFirma: vas overovaci kod je 482913. Plati 5 min. Nikomu ho nesdelujte.“ (bez diakritiky, aby to byla vždy jedna SMS; "locale": "en" pošle anglickou verzi).

• length 4 až 8 číslic (výchozí 6), ttl 60 až 1800 sekund (výchozí 300)
• from volitelně vaše schválené jméno odesílatele
• Nový kód na stejné číslo předchozí nevyřízený kód zneplatní

2. Ověření kódu

POST https://www.topsms.cz/api/verify/check
Authorization: Bearer CLIENT_ID:SECRET

{ "id": "cmv...", "code": "482913" }

→ { "valid": true, "status": "approved" }
→ { "valid": false, "status": "pending", "attemptsLeft": 4 }

Místo id můžete poslat to, ověří se poslední kód na dané číslo. Stavy: approved, pending (špatný kód, lze zkusit znovu), expired, failed (vyčerpáno 5 pokusů), canceled (nahrazen novějším kódem).

Bezpečnost a limity

• Kód ukládáme jen jako HMAC otisk, v databázi ani v logu ho v čitelné podobě nenajdete
• Maximálně 5 pokusů na jeden kód, porovnání v konstantním čase
• Na jedno číslo nejvýš 5 kódů za hodinu a 30 s mezi dvěma kódy, proti zneužití a nafukování nákladů
• Čísla na blacklistu se neodesílají, zprávy se účtují stejně jako běžné SMS

Testovací režim

S testovacím API klíčem (v dashboardu při vytváření klíče zaškrtněte Testovací klíč) se nic neodešle ani neúčtuje a kód je vždy 123456 (případně prvních N číslic z 12345678). Odpověď obsahuje "test": true a testCode, takže celý tok přihlášení odladíte bez telefonu.