REST API
dokumentace

Základ: endpoint a autentizace

API je čisté HTTP/JSON přes HTTPS. Produkční základ (base URL) je https://www.topsms.cz. Nepotřebujete žádnou knihovnu ani SDK — postačí HTTP klient, který už máte (curl, Guzzle, requests, fetch).

Autentizace probíhá přes API klíč v hlavičce Authorization. Klíč tvoří dvojice clientId a secret, kterou vygenerujete v dashboardu v sekci API přístup (secret se ukládá jen jako hash, takže si ho při vytvoření uschovejte):

Authorization: Bearer <clientId>:<secret>
Content-Type: application/json

Ke každému klíči patří oprávnění (scope) — send pro odesílání a read pro čtení stavu — a volitelně IP whitelist, kterým klíč omezíte na konkrétní adresy vašeho serveru.

Odeslání SMS

POST https://www.topsms.cz/api/sms/send — vyžaduje scope send.

Tělo požadavku (JSON):

Pole	Povinné	Popis
to	ano	Telefonní číslo v mezinárodním formátu (např. +420600000000).
text	ano	Text zprávy v UTF-8.
from	ne	Jméno odesílatele (Sender ID), max 11 znaků. Bez uvedení se použije výchozí „TopSMS".

Požadavek:

POST /api/sms/send
{
  "to": "+420600000000",
  "text": "Vas overovaci kod je 482910",
  "from": "MojeFirma"
}

Úspěšná odpověď (HTTP 200):

{
  "ok": true,
  "id": "cmp7a1b2c3...",
  "externalId": "a1b2c3d4",
  "to": "+420600000000",
  "from": "MojeFirma",
  "smsCount": 1,
  "price": 0.9,
  "status": "sent"
}

id je interní identifikátor zprávy (použijete pro dotaz na stav), externalId je ID u operátora, smsCount je počet účtovaných částí a price je cena v Kč, která se v ten moment odečte z kreditu.

Zjištění stavu doručení (delivery report)

GET https://www.topsms.cz/api/sms/status/{id} — vyžaduje scope read.

Do {id} dosaďte buď interní id, nebo externalId z odpovědi na odeslání. Delivery report od operátora dorazí asynchronně (typicky do několika sekund až minut) a stav se pak aktualizuje. Doporučený postup je krátký polling — po odeslání se čas od času zeptejte na stav.

{
  "id": "cmp7a1b2c3...",
  "externalId": "a1b2c3d4",
  "to": "+420600000000",
  "from": "MojeFirma",
  "status": "delivered",
  "price": 0.9,
  "carrier": "T-Mobile CZ",
  "createdAt": "2026-08-10T09:12:00.000Z",
  "deliveredAt": "2026-08-10T09:12:03.000Z",
  "failedAt": null,
  "errorMessage": null
}

Hodnoty pole status:

• sent — přijato a předáno operátorovi
• delivered — doručeno na telefon (viz deliveredAt)
• failed — nedoručeno (důvod v errorMessage, čas v failedAt)
• expired — vypršela platnost, operátor zprávu nedoručil

Chybové kódy

Chyba vždy vrací JSON { "error": "popis" } s odpovídajícím HTTP kódem:

HTTP	Význam
400	Chybí to nebo text, neplatné číslo, nebo je číslo na blacklistu (odhlásilo se přes STOP).
401	Chybějící nebo neplatná autentizace (zkontrolujte formát Bearer clientId:secret).
402	Nedostatečný kredit na účtu.
403	Účet není aktivní/schválený, IP mimo whitelist, nebo klíč nemá potřebný scope.
404	Zpráva nenalezena (u dotazu na stav).
429	Překročen rate limit klíče.
502	Chyba na straně operátora při doručování.

Délka zprávy a cena

Cena se počítá podle počtu částí zprávy (segmentů). Limit na jednu SMS závisí na tom, jestli text obsahuje diakritiku:

• Bez diakritiky (GSM-7): 160 znaků na 1 SMS, u delších 153 znaků na část.
• S diakritikou nebo emoji (Unicode): 70 znaků na 1 SMS, u delších 67 znaků na část.

Odpověď na odeslání vrací smsCount (počet účtovaných částí) i price (cena v Kč dle vašeho tarifu), takže cenu znáte hned. Detail počítání najdete v článku Kolik znaků má SMS.

Příklady: curl, PHP, Python, Node.js

Ve všech příkladech nahraďte CLIENT_ID:SECRET svým klíčem.

curl

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

PHP (cURL)

$ch = curl_init('https://www.topsms.cz/api/sms/send');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer CLIENT_ID:SECRET',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to'   => '+420600000000',
    'text' => 'Ahoj z PHP',
    'from' => 'MojeFirma',
  ]),
]);
$response = curl_exec($ch);
echo $response;

Python (requests)

import requests

r = requests.post(
    "https://www.topsms.cz/api/sms/send",
    headers={"Authorization": "Bearer CLIENT_ID:SECRET"},
    json={"to": "+420600000000", "text": "Ahoj z Pythonu", "from": "MojeFirma"},
)
print(r.json())

Node.js (fetch)

const res = await fetch("https://www.topsms.cz/api/sms/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer CLIENT_ID:SECRET",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ to: "+420600000000", text: "Ahoj z Node", from: "MojeFirma" }),
})
console.log(await res.json())

Limity, IP whitelist a Sender ID

• Rate limit — nastaven na každý klíč zvlášť (výchozí 60 požadavků/min). Vyšší limity pro velké objemy na vyžádání.
• IP whitelist — u klíče volitelně povolíte jen konkrétní IP adresy vašeho serveru. Požadavek z jiné IP dostane 403.
• Sender ID — vlastní jméno odesílatele místo čísla (pole from). Schválení u operátorů trvá 3–5 pracovních dní, jednorázový poplatek 500 Kč. Detail na stránce Vlastní Sender ID.
• Blacklist — čísla, která se odhlásila (STOP), API automaticky odmítne s kódem 400. Odhlášení řešíte na své straně, my ho respektujeme.
• Klíče a scope — spravujete v dashboardu (sekce API přístup): vytvoření, oprávnění send/read, IP whitelist a revokace.