REST API
pro vývojáře

Jak funguje TopSMS REST API?

API je postaveno na standardním HTTP/REST principu s autentizací přes Bearer token. Každý požadavek je zpracován synchronně — odpověď obsahuje ID zprávy a okamžitý stav přijetí. Delivery report (potvrzení doručení od operátora) přichází asynchronně přes webhook nebo je dostupný přes polling endpoint.

Sandbox prostředí je identické s produkčním API — zprávy se skutečně nezasílají, ale veškerá logika, chybové stavy a formáty odpovědí jsou totožné. Přechod z testování do produkce vyžaduje pouze změnu URL a API klíče.

• Endpoint: POST https://api.topsms.cz/v1/messages
• Autentizace: Bearer token (Client ID + Secret)
• Formát: JSON, UTF-8 encoding
• Rate limiting: 100 req/s (vyšší limity na vyžádání)
• Sandbox: https://sandbox.api.topsms.cz/v1/

Připravené knihovny a SDK

Pro rychlý start jsou k dispozici oficiální knihovny pro nejpoužívanější programovací jazyky. Každá knihovna obsahuje kompletní dokumentaci, příklady kódu a unit testy.

• PHP — composer install topsms/php-sdk
• Python — pip install topsms
• Node.js — npm install topsms-node
• Java — Maven/Gradle dependency
• Postman — kolekce ke stažení v dokumentaci

Delivery reporty a webhooky

Spolehlivá SMS brána není jen o odeslání — je i o potvrzení doručení. TopSMS poskytuje delivery reporty pro každou odeslanou zprávu. Reporty jsou dostupné v reálném čase přes webhook (push) nebo přes GET endpoint (pull).

Webhook notifikace přijde na vaši URL do 2 sekund po změně stavu zprávy. Podporované stavy: DELIVERED, UNDELIVERED, EXPIRED, REJECTED.

• Webhook s retry logikou (3× při chybě, exponenciální backoff)
• Polling endpoint pro pull model
• Bulk delivery report pro hromadné kampaně
• Audit log všech zpráv dostupný 90 dní