Stručně
Testovací API klíč TopSMS vrací stejné odpovědi jako ostrý, ale nic neodešle ani nezaúčtuje. Za 2 až 4 sekundy změní stav zprávy a pošle doručenku na váš webhook s příznakem test: true. Čísla končící 0000 simulují nedoručení, 0001 vypršení platnosti. Klíč je zdarma a vytvoříte ho v dashboardu jedním zaškrtnutím.
Než napojíte SMS na e-shop, rezervační systém nebo vlastní aplikaci, potřebujete si integraci odladit: jestli posíláte správný formát čísla, jak zpracujete odpověď, jestli váš server přijme doručenku a co se stane, když zpráva nedorazí. Posílat kvůli tomu ostré SMS na vlastní telefon je pomalé a stojí to kredit. Proto má TopSMS testovací API klíče: odpovídají stejně jako ostré, ale nic neodešlou a nic nezaúčtují.
Co testovací klíč dělá
- Nic neodešle ani nezaúčtuje. Kredit se nemění. Pole
pricev odpovědi ukazuje, kolik by zpráva stála. - Vrací stejné odpovědi jako ostrý klíč, jen s polem
"test": true. Kód, který zpracovává odpověď, tak po přepnutí na ostrý klíč nemusíte měnit. - Simuluje doručení. Za 2 až 4 sekundy změní stav zprávy a pošle doručenku na webhook klíče s
"test": true. - Kontroluje vše ostatní: formát čísla, blacklist, schválení odesílatele a oprávnění klíče. Chybný požadavek tedy skončí stejnou chybou jako u ostrého klíče. Přeskočí se jen kontrola kreditu.
Testovací klíč je zdarma a funguje pro odeslání, hromadné odeslání, ověřovací kódy i pro e-mail na SMS.
Jak testovací klíč vytvořit
- Zaregistrujte se a ověřte telefon. API klíče, i testovací, fungují až u schváleného účtu.
- V dashboardu otevřete API přístup a klikněte na Nový API klíč.
- Zvolte oprávnění (
sendpro odesílání,readpro stav zpráv) a zaškrtněte Testovací klíč. - Zkopírujte Client ID a secret. Požadavky podepisujete hlavičkou
Authorization: Bearer CLIENT_ID:SECRET. - Pokud chcete testovat doručenky, vyplňte u klíče webhook URL.
První testovací SMS
curl -X POST https://www.topsms.cz/api/sms/send \
-H "Authorization: Bearer CLIENT_ID:SECRET" \
-H "Content-Type: application/json" \
-d '{"to": "+420601234567", "text": "Testovaci zprava z API"}'
Odpověď má stejný tvar jako u ostrého klíče:
{ "ok": true, "test": true, "channel": "sms", "id": "cmv…", "externalId": "test-…", "to": "+420601234567", "from": "TopSMS", "smsCount": 1, "price": 0.99, "status": "sent" }
Na telefon nic nepřijde. Za 2 až 4 sekundy se stav změní na delivered a zjistíte ho přes GET /api/sms/status/{id}, nebo ho dostanete webhookem.
Testovací čísla: doručeno, nedoručeno, vypršelo
Výsledek simulace určují poslední čtyři číslice čísla příjemce:
| Číslo končí | Výsledný stav | errorCode | Co simuluje |
|---|---|---|---|
0000 | failed | undelivered | neplatné číslo |
0001 | expired | expired | telefon byl po celou dobu platnosti vypnutý |
| cokoli jiného | delivered | – | doručeno |
Například +420601230000 skončí nedoručením, +420601230001 vypršením platnosti. Díky tomu si vyzkoušíte i větve kódu, ke kterým se s ostrými SMS dostanete jen zřídka: označení neplatného čísla v databázi, opakované odeslání později nebo upozornění pro obsluhu. Co jednotlivé stavy znamenají v ostrém provozu, popisuje článek Proč SMS nedorazila.
Testovací webhook
Pokud má klíč nastavenou webhook URL, pošleme na ni po simulovaném doručení HTTP POST se stejnou strukturou jako u ostré doručenky, navíc s "test": true:
{
"event": "sms.status",
"id": "cmv…",
"externalId": "test-…",
"to": "+420601230000",
"from": "TopSMS",
"status": "failed",
"price": 0,
"currency": "CZK",
"deliveredAt": null,
"failedAt": "2026-11-15T10:00:03.000Z",
"errorMessage": "Test: neplatné číslo (simulace, číslo končí 0000)",
"errorCode": "undelivered",
"sentAt": "2026-11-15T10:00:03.100Z",
"test": true
}
Webhook je podepsaný hlavičkou X-TopSMS-Signature (HMAC-SHA256 těla s tajným klíčem webhooku), takže si ověření podpisu vyzkoušíte stejně jako v ostrém provozu. Když váš server neodpoví úspěšně, zkusíme doručení ještě dvakrát: po 30 sekundách a po dalších 2 minutách. Podpis a opakování podrobně popisuje stránka Webhooky.
V produkčním kódu je dobré pole test kontrolovat a testovací doručenky nezapisovat do ostrých dat, pokud testujete proti stejné databázi.
Log požadavků a webhooků
U každého klíče je v dashboardu tlačítko Log a webhook. Uvidíte posledních 100 volání (čas, endpoint, stavový kód, chybu a tělo požadavku) a každý pokus o doručení webhooku včetně odpovědi vašeho serveru. Log se uchovává 30 dní, secret ani hlavička Authorization se neukládají. Tamtéž pošlete testovací webhook jedním tlačítkem, bez odeslání zprávy.
Plánované odeslání a ověřovací kódy
Plánované odeslání je jediná odchylka od tvaru ostré odpovědi. Testovací klíč s polem send_at vrátí 200 se "scheduled": true a bez jobId, ostrý klíč vrací jobId pro pozdější zrušení.
Verify API s testovacím klíčem kód neposílá a kód je vždy 123456 (případně prvních N číslic z 12345678 podle zvolené délky). Odpověď obsahuje "test": true a testCode, takže celý tok přihlášení odladíte bez telefonu.
Rozdíly mezi testovacím a ostrým klíčem
| Testovací klíč | Ostrý klíč | |
|---|---|---|
| Odeslání SMS | ne | ano |
| Kredit | nemění se | strhává se cena zprávy |
| Doručenka | simulovaná za 2 až 4 s | od operátora |
| Odkazy v textu | projdou | vyžadují aspoň jedno placené dobití kreditu |
| Plánované odeslání | scheduled: true, bez jobId | jobId |
Poslední bod se hodí znát předem: ostrý klíč odmítne zprávu s odkazem, dokud účet nemá aspoň jedno placené dobití (chyba s kódem urls_need_topup). Testovací klíč tuto kontrolu nedělá.
Co si v testovacím režimu vyzkoušet
Krátký kontrolní seznam, než přepnete na ostrý klíč:
- Úspěšné odeslání a uložení
idz odpovědi k objednávce nebo uživateli. - Chybný formát čísla. Pošlete číslo bez předvolby nebo s písmeny a ověřte, že váš kód chybu
400zachytí a nezkouší odesílat donekonečna. - Doručenka. Webhook přijde, podpis sedí a stav se zapíše ke správné zprávě podle
id. - Nedoručení a vypršení přes čísla končící
0000a0001. - Výpadek vašeho serveru. Dočasně vraťte z webhooku chybu a v logu klíče uvidíte opakované pokusy.
- Opakování požadavku se stejnou hlavičkou
Idempotency-Key, aby se při výpadku spojení neodeslala SMS dvakrát.
Po testování
Až integrace funguje, vytvořte ostrý klíč (bez zaškrtnutí Testovací klíč) a vyměňte ho v konfiguraci. Kód měnit nemusíte. Po ověření telefonu máte na účtu 10 testovacích SMS na zkoušku doručení do skutečného telefonu, potom platíte jen odeslané SMS: 0,99 Kč, při měsíční útratě od 5 000 Kč 0,96 Kč a od 15 000 Kč 0,93 Kč, konečné ceny bez paušálu.
Testovací a ostrý klíč vedle sebe
Testovací klíč nemusíte po spuštění mazat. Jeden účet může mít až 10 API klíčů, takže si testovací klíč nechte pro vývojové a testovací prostředí a ostrý klíč používejte jen v produkci. Každý klíč má vlastní oprávnění, webhook URL a log, takže se testovací a ostré doručenky nepletou. Secret ukládejte do proměnných prostředí nebo do správce tajemství, ne do repozitáře, a pokud unikne, klíč v dashboardu zneplatněte a vytvořte nový. Při další úpravě integrace, třeba přidání plánovaného odeslání nebo nového typu zprávy, pak změnu nejdřív projedete testovacím klíčem a teprve potom ji nasadíte.
Kompletní popis endpointů, chybových kódů a příklady v PHP, Pythonu a Node.js najdete v dokumentaci REST API.
Časté dotazy
Jak vyzkoušet SMS API zdarma? Po registraci si v dashboardu vytvořte API klíč a zaškrtněte Testovací klíč. Takový klíč nic neodešle ani neúčtuje, ale odpovídá stejně jako ostrý a posílá simulované doručenky na webhook.
Jak nasimulovat nedoručenou SMS? Pošlete zprávu testovacím klíčem na číslo končící 0000. Zpráva skončí ve stavu failed s errorCode undelivered. Číslo končící 0001 simuluje vypršení platnosti (expired), ostatní čísla doručení.
Kontroluje testovací klíč i chyby v požadavku? Ano. Kontroluje se formát čísla, blacklist, schválení odesílatele i oprávnění klíče. Přeskočí se jen kontrola kreditu, protože se nic neúčtuje.
Funguje testovací režim i pro ověřovací kódy? Ano. Verify API s testovacím klíčem nic neodešle a kód je vždy 123456 (případně prvních N číslic z 12345678). Odpověď obsahuje test: true a testCode.