HTTP GET API pro routery a monitoring

Adresa a parametry

GET nebo POST (application/x-www-form-urlencoded) na https://www.topsms.cz/api/sms/get. Stejně funguje https://topsms.eu/api/sms/get. Klíč potřebuje scope send.

• to (povinné): číslo příjemce, mezinárodně (+420601234567, v URL %2B420601234567), devítimístné české číslo bez předvolby projde také
• text (povinné): text SMS v UTF-8, v URL zakódovaný (mezera %20 nebo +, „ř“ %C5%99)
• from: schválený odesílatel (Sender ID), jinak výchozí odesílatel účtu
• send_at: plánované odeslání, ISO 8601 s časovou zónou (2026-12-01T08:00:00+01:00)
• ref: vaše reference; stejný ref do 24 hodin SMS znovu nepošle (funguje jako Idempotency-Key, chrání před dvojí SMS při opakování požadavku)
• format=json: odpověď v JSON (stejné tělo jako POST /api/sms/send)
• client_id a secret (nebo key=clientId:secret): přihlášení, když zařízení neumí hlavičku Authorization

Přihlášení a bezpečnost klíče

Podle toho, co zařízení umí, v tomto pořadí:

• Hlavička Authorization: Bearer clientId:secret: nejbezpečnější, klíč není v URL
• POST formulář s client_id a secret v těle: klíč se neukládá do logů s adresou
• Klíč v URL (?client_id=…&secret=…): jen když zařízení nic jiného neumí. Ve výchozím stavu je vypnutý a požadavek vrátí 403 url_auth_disabled. Zapnete ho u klíče v dashboardu (API přístup → GET a e-mail → Povolit autentizaci v URL).

Adresa s klíčem se ukládá do logů zařízení, proxy a webových serverů. Pro HTTP GET API proto vytvořte samostatný API klíč jen se scope send a s IP whitelistem (veřejná IP routeru nebo monitoringu) a nízkým rate limitem. Když klíč unikne, zrušíte ho jedním kliknutím bez dopadu na ostatní integrace. Hodnoty secret a key v našich lozích maskujeme. Náhledy odkazů v chatu (Slack, Teams, WhatsApp) SMS neodešlou.

Odpověď

Ve výchozím stavu jeden řádek textu, který zvládne každé zařízení:

OK cmh3x9k2a0001qz8l5v7w2abc
ERROR insufficient_credit Insufficient credit. Need 1.39 Kč, have 0.20 Kč.
ERROR url_auth_disabled URL authentication (client_id and secret in the query string) is disabled for this API key. …

HTTP stavové kódy jsou stejné jako v REST API: 200 odesláno, 202 naplánováno (send_at), 400 chybný parametr nebo číslo, 401 neplatný klíč, 402 nedostatek kreditu, 403 chybí scope, IP mimo whitelist nebo vypnutá autentizace v URL, 429 překročen rate limit. S format=json nebo hlavičkou Accept: application/json dostanete JSON jako z /api/sms/send (id, smsCount, price, currency). Testovací klíč nic neodešle ani neúčtuje a vrací stejné odpovědi.

Příklady: curl, wget, router

# curl s klíčem v hlavičce (doporučeno)
curl -H "Authorization: Bearer CLIENT_ID:SECRET" \
  "https://www.topsms.cz/api/sms/get?to=%2B420601234567&text=Vypadek%20proudu%20v%20serverovne"

# curl, POST formulář (klíč není v URL)
curl -d "client_id=CLIENT_ID" -d "secret=SECRET" -d "to=+420601234567" \
  --data-urlencode "text=Výpadek proudu v serverovně" https://www.topsms.cz/api/sms/get

# wget
wget -qO- --header="Authorization: Bearer CLIENT_ID:SECRET" \
  "https://www.topsms.cz/api/sms/get?to=%2B420601234567&text=Zalohovani%20selhalo"

# router, kamera, PLC: jen URL (zapněte u klíče autentizaci v URL, klíč s IP whitelistem)
https://www.topsms.cz/api/sms/get?client_id=CLIENT_ID&secret=SECRET&to=%2B420601234567&text=Alarm%3A%20dvere%20otevreny

Zabbix

V Zabbixu (Alerts → Media types → Create media type) zvolte typ Webhook, parametry to = {ALERT.SENDTO}, message = {ALERT.SUBJECT}: {ALERT.MESSAGE}, token = CLIENT_ID:SECRET a skript:

var p = JSON.parse(value);
var req = new HttpRequest();
req.addHeader('Authorization: Bearer ' + p.token);
req.addHeader('Content-Type: application/x-www-form-urlencoded');
var body = 'to=' + encodeURIComponent(p.to) + '&text=' + encodeURIComponent(p.message.slice(0, 600));
var res = req.post('https://www.topsms.cz/api/sms/get', body);
if (req.getStatus() !== 200 || res.indexOf('OK ') !== 0) throw 'TopSMS: ' + res;
return 'OK';

Uživateli pak v Media přidáte typ TopSMS s jeho telefonním číslem v poli Send to.

PRTG, Nagios a Checkmk

PRTG: Setup → Account Settings → Notification Templates → Add, akce Execute HTTP Action, metoda POST, URL https://www.topsms.cz/api/sms/get, Payload:

client_id=CLIENT_ID&secret=SECRET&to=%2B420601234567&text=%device %name %status %message

PRTG zástupné znaky před odesláním nahradí, mezery a diakritiku přijmeme. Nagios / Icinga: příkaz pro notifikace

define command {
  command_name  notify-by-topsms
  command_line  /usr/bin/curl -s -H "Authorization: Bearer CLIENT_ID:SECRET" \
    --data-urlencode "to=$CONTACTPAGER$" \
    --data-urlencode "text=$NOTIFICATIONTYPE$ $HOSTNAME$ $SERVICEDESC$ $SERVICESTATE$" \
    https://www.topsms.cz/api/sms/get
}

Checkmk: vlastní notifikační skript v ~/local/share/check_mk/notifications/ se stejným voláním curl, číslo z $NOTIFY_CONTACTPAGER, text z $NOTIFY_HOSTNAME a $NOTIFY_SERVICEOUTPUT.