Testování API napojení

Než pustíte integraci do provozu, je vhodné ji vyzkoušet — ověřit, že sestavujete platné požadavky, správně zpracováváte odpovědi a umíte přijmout doručenky (webhooky). SmsManager k tomu nabízí čtyři nezávislé nástroje, které můžete kombinovat. Žádný z nich neodešle skutečnou zprávu na telefon příjemce.

Nástroj	Jak zapnout	Kredit	Odešle SMS?	Doručenky (webhook)?	Kdy použít
Validační endpoint	`POST https://rest-api.smsmngr.com/v1/messaging/validate`	Neodečítá se	Ne	Ne	Vývoj a řešení problémů
Testovací číslo	`to.phone_number` = `420777777777`	Neodečítá se	Ne	Ne	Ověření, že požadavek projde a odpověď zpracujete správně
Testovací brána	`gateway: "test"` ve flow objektu `sms`	0,001 Kč / SMS	Ne	Ano	End-to-end test zpracování doručenek na vaší callback URL
Mock endpointy	Doména `api-mock` / `rest-api-mock`	Neodečítá se	Ne	Ne	Vývoj a automatizované testy proti simulaci API

Validace bez odeslání

Endpoint POST https://rest-api.smsmngr.com/v1/messaging/validate ověří požadavek na odeslání, aniž by cokoli odeslal. Nic se za něj neúčtuje. Autentizujete se stejným API klíčem v hlavičce x-api-key. Endpoint přijímá stejné tělo jako odesílací endpointy JSON API v2:

jeden objekt zprávy, stejně jako POST /message,
pole 1 až 10 zpráv, stejně jako POST /messages.

curl -X POST https://rest-api.smsmngr.com/v1/messaging/validate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Ahoj!",
    "to": [
      {"phone_number": "420777123456"},
      {"phone_number": "123"}
    ]
  }'

curl -X POST https://rest-api.smsmngr.com/v1/messaging/validate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "body": "Ahoj!",
      "to": [{"phone_number": "420777123456"}]
    },
    {
      "to": [{"phone_number": "420777123457"}],
      "flow": [{"sms": {"body": "Ahoj přes lowcost!", "gateway": "lowcost"}}]
    }
  ]'

Co se kontroluje

Validace kontroluje pouze strukturu požadavku:

pole a jejich datové typy,
kroky flow,
formát telefonních čísel příjemců.

Validace nekontroluje doručitelnost, schválení odesílatele, opt-out seznamy ani stav kreditu. Úspěšná validace proto nezaručuje, že zpráva bude odeslána a doručena. Tyto podmínky se vyhodnotí až při skutečném odeslání.

Odpověď

Výsledek validace dostanete s HTTP 200, i když je obsah požadavku neplatný. O výsledku proto rozhoduje pole success. Odpověď na požadavek s jednou zprávou z příkladu výše vypadá takto:

Odpověď

{
  "success": false,
  "validate": {
    "accepted": [
      { "key": "0", "phone_number": "420777123456" }
    ],
    "rejected": [
      { "key": "1", "phone_number": "123" }
    ],
    "errors": [
      {
        "key": "1",
        "field": "to[1].phone_number",
        "message": "Phone number is not in a valid format",
        "code": "302"
      }
    ]
  }
}

Pole	Popis
`success`	`true` jen tehdy, když validací prošly všechny zprávy i všichni příjemci, tedy `rejected` i `errors` jsou prázdné.
`validate.accepted`	Položky, které validací prošly.
`validate.rejected`	Položky, které validací neprošly. Důvod najdete v `errors` pod stejným `key`.
`validate.errors`	Všechny chyby validace. Pole je v odpovědi vždy, při úspěchu je prázdné.
`errors[].field`	Cesta k neplatnému poli, například `to[1].phone_number` nebo `flow[0].sms.gateway`.
`errors[].message`	Popis chyby.
`errors[].code`	Interní stavový kód, pokud existuje. Kód `302` znamená číslo ve špatném formátu (viz chybové kódy).

Význam pole key závisí na tvaru požadavku, stejně jako u odesílacích endpointů:

Jedna zpráva (jako POST /message) — key je index příjemce v poli to. Položky v accepted a rejected obsahují i phone_number tak, jak jste ho poslali. Chyby na úrovni celé zprávy nemají key.
Pole zpráv (jako POST /messages) — key je index zprávy v odeslaném poli. Položky neobsahují phone_number.

Chyby požadavku

Pokud tělo požadavku nejde zvalidovat vůbec, endpoint vrátí HTTP 400 s popisem v poli message:

Zpráva	Příčina
`Missing request body`	Požadavek nemá tělo.
`Request must contain 1 to 10 messages`	Pole zpráv je prázdné nebo obsahuje víc než 10 zpráv.

Testovací telefonní číslo

Na speciální číslo 420777777777 se zpráva nikdy neodešle a neodečte se za ni kredit. Příjemce se vyhodnotí jako neplatný. API požadavek se přesto zpracuje jako běžně — dostanete zpět request_id a pro každého příjemce message_id — takže si ověříte, že vaše integrace sestaví platný požadavek, autentizuje se a správně zpracujete odpověď od API.

cURL

curl -X POST https://api.smsmngr.com/v2/message \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Testovací zpráva",
    "to": [{"phone_number": "420777777777"}]
  }'

Testovací číslo negeneruje doručenky — zpráva se reálně nepředává k doručení, takže žádný webhook o stavu doručení nepřijde. Pokud chcete otestovat i příjem doručenek, použijte testovací bránu níže.

Testovací brána

Přidáním gateway: "test" do flow objektu sms označíte zprávu jako testovací. Takové zprávy stojí jen 0,001 Kč / SMS, ve skutečnosti se nedoručují na telefon, ale SmsManager pro ně vygeneruje doručenky a pošle je jako webhook na vaši callback URL. Díky tomu otestujete celý tok od odeslání až po zpracování doručenky. Důvodem pro odečtení kreditu je zapojení fakturace a validace do všech částí zpracování pro kompletní end-to-end otestování.

Tělo požadavku

{
  "body": "Testovací zpráva s doručenkou",
  "to": [{"phone_number": "420777123456"}],
  "callback": "https://yourapp.com/webhooks/sms",
  "flow": [
    {
      "sms": {
        "sender": "MujApp",
        "gateway": "test"
      }
    }
  ]
}

Nastavte pole callback na URL vašeho endpointu, abyste doručenky skutečně obdrželi. Podrobnosti o formátu payloadu a sekvenci stavů najdete v návodu Webhooky.

Mock (sandbox) endpointy

Pro vývoj a automatizované testy můžete místo produkčních domén volat mock endpointy. Ty jen simulují příjem požadavku a odpovídají podle OpenAPI specifikace — nic se neodešle a neodečte se kredit. Hodí se, když chcete ověřit sestavení požadavků a parsování odpovědí, aniž byste zasáhli produkci. Do adresy stačí doplnit -mock za název odpovídající produkční domény:

API	Produkční základní URL	Mock základní URL
JSON API v2	`https://api.smsmngr.com/v2`	`https://api-mock.smsmngr.com/v2`
REST API	`https://rest-api.smsmngr.com/v1`	`https://rest-api-mock.smsmngr.com/v1`

cURL

curl -X POST https://api-mock.smsmngr.com/v2/message \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Ahoj z mocku!",
    "to": [{"phone_number": "420777123456"}]
  }'

Mock endpointy vracejí ukázkové odpovědi podle OpenAPI specifikace — nezrcadlí stav vašeho účtu ani reálné doručení. Pro test skutečných doručenek použijte testovací bránu proti produkční doméně.

Doporučený postup testování

Ověřte sestavení požadavku

Během vývoje ověřte strukturu zpráv přes validační endpoint. Potom volejte mock endpointy nebo produkci s testovacím číslem 420777777777. Ověříte tak autentizaci, tvar požadavku i parsování odpovědi — zdarma a bez odeslání.

Otestujte doručenky

Přepněte na testovací bránu gateway: "test" s nastaveným polem callback. Za 0,01 Kč / SMS ověříte, že váš endpoint doručenky přijme a správně zpracuje sekvenci stavů.

Přejděte do provozu

Odeberte gateway: "test", nasměrujte volání na produkční doménu a odešlete zprávu na své skutečné číslo pro finální kontrolu. Poté můžete integraci pustit naostro.

Další kroky

Odeslat SMS

Kompletní přehled polí SMS zprávy včetně hodnot pole gateway.

Webhooky

Formát doručenky, sekvence stavů a osvědčené postupy pro váš endpoint.

Odesílání zpráv

Příjem a ověření

Stav a statistiky

Testování

AI asistenti

Přístup a klíče

Validace bez odeslání

Co se kontroluje

Odpověď

Chyby požadavku

Testovací telefonní číslo

Testovací brána

Mock (sandbox) endpointy

Doporučený postup testování

Další kroky

Odeslat SMS

Webhooky

​Validace bez odeslání

​Co se kontroluje

​Odpověď

​Chyby požadavku

​Testovací telefonní číslo

​Testovací brána

​Mock (sandbox) endpointy

​Doporučený postup testování

​Další kroky

Odeslat SMS

Webhooky

Validace bez odeslání

Co se kontroluje

Odpověď

Chyby požadavku

Testovací telefonní číslo

Testovací brána

Mock (sandbox) endpointy

Doporučený postup testování

Další kroky