19. května 2026·4 min čtení·Tým TopSMS

SMS API za 5 minut: quickstart pro vývojáře

Od registrace k první odeslané SMS přes REST API za 5 minut. Příklady v PHP, Node.js, Python a curl. Bez SDK, jen HTTP.

TL;DR: Registrace, vystavení API klíče a první odeslaná SMS přes REST API — celkem 5 minut. V tomto quickstartu najdete kód v 4 jazycích (curl, PHP, Node.js, Python) a vysvětlení autentizace, formátů a typických chyb. Bez nutnosti SDK — stačí HTTP klient.

Tento návod je pro vývojáře, kteří chtějí poslat první SMS přes TopSMS API co nejrychleji. Předpokládá základní znalost HTTP a JSON.

1. Registrace + API klíč (2 minuty)

Vytvořte si účet na topsms.cz/sms-zdarma — dostanete 10 SMS zdarma na test
Ověřte telefon přes OTP kód v SMS
V dashboardu jděte na /dashboard/api → "Vytvořit klíč"
Vyplňte:
- Název: dev-test (jen pro vás)
- Scopes: zaškrtnout send (odesílání) a read (čtení statusu)
- IP whitelist: pro produkci vyplnit, pro test můžete přeskočit
Klikněte "Vytvořit" — uvidíte clientId a secret (secret se ukáže jen jednou, uložte si)

Autentizace probíhá Bearer tokenem ve formátu clientId:secret.

2. První SMS přes curl (30 sekund)

curl -X POST https://www.topsms.cz/api/sms/send \
  -H "Authorization: Bearer YOUR_CLIENT_ID:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+420608030884",
    "from": "TopSMS",
    "text": "Ahoj z API!"
  }'

Odpověď:

{
  "ok": true,
  "messageId": "cmp...",
  "externalId": "abc-123",
  "status": "queued",
  "cost": 0.93
}

Latence end-to-end (vaše terminál → telefon příjemce) je typicky 2-4 sekundy.

3. PHP (3 řádky)

$ch = curl_init('https://www.topsms.cz/api/sms/send');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('TOPSMS_CLIENT_ID') . ':' . getenv('TOPSMS_SECRET'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '+420608030884',
        'from' => 'TopSMS',
        'text' => 'Ahoj z PHP!',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($response['ok'] ?? false) {
    echo "SMS odeslána, ID: {$response['messageId']}";
}

Pro produkci doporučujeme Guzzle HTTP client — lepší error handling.

4. Node.js (s native fetch)

const response = await fetch('https://www.topsms.cz/api/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TOPSMS_CLIENT_ID}:${process.env.TOPSMS_SECRET}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+420608030884',
    from: 'TopSMS',
    text: 'Ahoj z Node.js!',
  }),
})

const data = await response.json()
if (data.ok) {
  console.log('SMS odeslána, ID:', data.messageId)
} else {
  console.error('Chyba:', data.error)
}

Node.js 18+ má fetch nativně. Pro starší verze použijte node-fetch nebo axios.

5. Python (requests)

import os
import requests

response = requests.post(
    'https://www.topsms.cz/api/sms/send',
    headers={
        'Authorization': f'Bearer {os.environ["TOPSMS_CLIENT_ID"]}:{os.environ["TOPSMS_SECRET"]}',
        'Content-Type': 'application/json',
    },
    json={
        'to': '+420608030884',
        'from': 'TopSMS',
        'text': 'Ahoj z Pythonu!',
    },
)

data = response.json()
if data.get('ok'):
    print(f"SMS odeslána, ID: {data['messageId']}")
else:
    print(f"Chyba: {data.get('error')}")

6. Formát telefonního čísla

Vždy E.164 formát s prefixem +:

✅ +420608030884 (CZ)
✅ +421900123456 (SK)
✅ +49301234567 (DE)
❌ 608030884 (bez prefixu — odmítnuto)
❌ 00420608030884 (00 místo + — odmítnuto)
❌ 608 030 884 (mezery — odmítnuto)

Pokud máte databázi s nestandardním formátem, použijte naši validator endpoint pro normalizaci před odesláním.

7. Sender ID (`from` parametr)

Bez vlastního sender ID: pošlete TopSMS (náš default) — funguje pro test
S vlastním sender ID: pošlete schválené jméno (např. Eshop123) — viz Sender ID schválení
Max 11 znaků, jen písmena/čísla/pomlčka/podtržítko

8. Čtení statusu zprávy

Po odeslání máte messageId. Status zjistíte:

curl -H "Authorization: Bearer YOUR_CLIENT_ID:YOUR_SECRET" \
  https://www.topsms.cz/api/sms/status/MESSAGE_ID

Odpověď:

{
  "id": "cmp...",
  "status": "delivered",
  "deliveredAt": "2026-05-19T10:23:45Z",
  "operatorCost": 0.028,
  "carrier": "230.2"
}

Možné stavy: queued, sent, delivered, failed, expired, rejected.

Alternativně si nastavte webhook URL v API klíči — pak vám delivery report přijde POSTem v reálném čase. Viz Webhooky v SMS API.

9. Typické chyby (HTTP status)

Status	Důvod	Řešení
401	Špatný token	Zkontrolovat `Authorization` header
400	Neplatný telefon	E.164 formát s `+` prefix
400	Neplatné `from`	Sender ID musí být schválené nebo `TopSMS`
402	Nedostatek kreditu	Dobít kredit v dashboardu
403	Scope `send` chybí	Editovat API klíč, zaškrtnout `send`
429	Rate limit (default 60 SMS/min)	Slow down nebo požádat o vyšší limit
500	Server error	Retry s exponential backoff, kontaktovat support

10. Doporučená architektura pro produkci

[Vaše aplikace]
      ↓ POST /api/sms/send
[TopSMS API]
      ↓ async
[T-Mobile / O2 / Vodafone]
      ↓
[Telefon příjemce]
      ↓ delivery report
[TopSMS API]
      ↓ POST webhook
[Vaše aplikace]
      ↓ update DB

Klíčové principy:

Idempotence: před retry zkontrolujte status, abyste neodeslali 2× stejnou zprávu
Webhook signature: validujte HMAC podpis (nastavitelný per API key)
Rate limit budget: rozdělte denní objem do peaků s rezervou 30 %
Fallback: pokud kredit padne pod threshold, použijte záložní cestu (jiný kanál)

11. Bezpečnost — co NEdělat

❌ Nikdy nevkládejte API key do frontendu (JavaScript v prohlížeči) — kdokoli ho ukradne. Volání API jen ze serveru.

❌ Nikdy commit do gitu — používejte .env soubor + .gitignore.

❌ Nesdílejte secret — ne v Discord, Slack, screenshotech. Pokud došlo k úniku, hned vystavte nový a starý revoke.

❌ Nezneužívejte testovací data — neposílejte SMS na náhodná čísla. Posílá-li někdo na +420608030884 (test číslo z dokumentace), zaplatí to.

12. Co dál

Po prvním úspěšném messageId máte funkční integraci. Další kroky:

Schválení vlastního sender ID — /produkty/sender-id (~5 prac. dní, 500 Kč jednorázově)
Nastavení webhooků — webhooky guide
Bulk odesílání s rate limit handling — Bulk SMS API guide
Plugin pro WordPress/WooCommerce — pluginy

Pro vyšší objemy (50k+ SMS/den) zvažte SMPP protokol — REST vs SMPP.

Související články

apiquickstartdeveloper

Otestujte TopSMS zdarma

10 SMS na start, bez závazku, registrace minuta.

Registrovat zdarma →