Přeskočit na obsah

Testovací API klíč: SMS API zdarma bez odeslání

SMS API v testovacím režimu: nic se neodešle ani nezaúčtuje, simulovaná doručenka za 2 až 4 s, testovací čísla pro selhání a testovací webhook.

5 min čtení

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 price v 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

  1. Zaregistrujte se a ověřte telefon. API klíče, i testovací, fungují až u schváleného účtu.
  2. V dashboardu otevřete API přístup a klikněte na Nový API klíč.
  3. Zvolte oprávnění (send pro odesílání, read pro stav zpráv) a zaškrtněte Testovací klíč.
  4. Zkopírujte Client ID a secret. Požadavky podepisujete hlavičkou Authorization: Bearer CLIENT_ID:SECRET.
  5. 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ý staverrorCodeCo simuluje
0000failedundeliveredneplatné číslo
0001expiredexpiredtelefon byl po celou dobu platnosti vypnutý
cokoli jinéhodelivered–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í SMSneano
Kreditnemění sestrhává se cena zprávy
Doručenkasimulovaná za 2 až 4 sod operátora
Odkazy v textuprojdouvyžadují aspoň jedno placené dobití kreditu
Plánované odesláníscheduled: true, bez jobIdjobId

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íč:

  1. Úspěšné odeslání a uložení id z odpovědi k objednávce nebo uživateli.
  2. Chybný formát čísla. Pošlete číslo bez předvolby nebo s písmeny a ověřte, že váš kód chybu 400 zachytí a nezkouší odesílat donekonečna.
  3. Doručenka. Webhook přijde, podpis sedí a stav se zapíše ke správné zprávě podle id.
  4. Nedoručení a vypršení přes čísla končící 0000 a 0001.
  5. Výpadek vašeho serveru. Dočasně vraťte z webhooku chybu a v logu klíče uvidíte opakované pokusy.
  6. 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.

Webhooky a doručenky

Stav každé zprávy vám pošleme HTTP POSTem s podpisem, bez pollingu. 0,99 Kč za SMS, bez paušálu, 10 testovacích SMS.