Pravidla API

Platí pro API v1 (/api/v1/...). API v3 kompatibilní se SmartEmailingem má vlastní obálky a formáty, popsané v Kompatibilitě se SmartEmailingem.

Adresa a formát#

• Základ: https://www.postarna.cz/api/v1. Operace firmy: /api/v1/tenants/{tenant}/..., kde {tenant} je veřejné ID firmy (UUID).
• Tělo požadavků POST, PUT a PATCH je JSON (Content-Type: application/json, UTF-8). Jiný typ obsahu = 415 validation / contentType, tělo, které není objekt JSON, = 400 validation / body. Výjimky: nahrání CSV a souborů přijímá i multipart/form-data.
• Odpovědi jsou JSON v UTF-8 (diakritika není escapovaná). Exporty a statistiky umí i CSV (format=csv).
• Jedno tělo požadavku má nejvýš 5 MB (větší = 413 validation / size); CSV soubor importu nahraný jako multipart/form-data až 64 MB.

Datové typy#

• Časy zapisované do API (sendAt, createdAt objednávky) posílejte s časovou zónou (Z nebo +02:00).
• Dny v segmentech a podmínkách („za posledních 30 dní“) jsou kalendářní dny v časové zóně firmy (Europe/Prague, Europe/Bratislava).
• Měny se nikdy nesčítají ani nepřevádějí. Každý e-shop má jednu měnu; objednávka v jiné měně, než má její e-shop, je chyba 400. Součty (obraty, konverze) jsou vždy po měnách.

Stránkování, hledání a řazení#

• Seznamy objektů mají page (od 1) a pageSize (1 až 100, výchozí 25). Odpověď je {"items": [...], "total": 240, "page": 1, "pageSize": 25}.
• Projděte všechny stránky, dokud page * pageSize < total.
• q hledá v názvu nebo adrese bez ohledu na velikost písmen a diakritiku (nejvýš 200 znaků). U automatizací q=#123 najde automatizaci podle ID.
• shop omezí přehled na jeden e-shop (ID e-shopu).
• sort u přehledů, které ho mají: pole oddělená čárkou, - na začátku = sestupně, nejvýš 3 pole (sort=name,-createdAt). Výchozí řazení je od nejnovějšího. Neznámé pole = 400 validation / sort.

Chyby#

Každá chyba má stejný tvar a vhodný HTTP stav:

{"error": {"code": "conflict", "message": "version", "params": {"current": 4}}}

• code: stálý strojový kód (validation, unauthorized, forbidden, not_found, conflict, rate_limited, unavailable a další). Podle něj se rozhodujte.
• message: technický údaj, obvykle název pole (email, definition.1.0.listId, graph) nebo důvod (version, status). Není to text pro lidi a může být prázdný.
• params: podrobnosti, například issues u grafu automatizace, expected a actual u počtu příjemců, reason.
• API neposílá texty pro lidi; texty v češtině a slovenštině si skládá aplikace.

Úplný seznam kódů s významem a nápravou: Chyby a limity.

Limity požadavků#

• Na firmu (všechny klíče dohromady): zásobník 2 500 požadavků, který se doplňuje 4 požadavky za sekundu, a 100 000 požadavků za den (doplňuje se průběžně, žádný reset o půlnoci).
• Každá odpověď na požadavek s klíčem nese X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (unixový čas, kdy bude zásobník zase plný) zásobníku, kterému zbývá méně.
• Po překročení přijde 429 rate_limited s hlavičkou Retry-After (za kolik sekund). Odmítnuté požadavky se nepočítají.
• Některé akce mají vlastní limity (testovací e-maily, události kontaktu, MCP); jsou v Chybách a limitech.

Opakování požadavků a idempotence#

API nepoužívá hlavičku Idempotency-Key. Po výpadku sítě nebo chybě 5xx proto opakujte jen to, co je bezpečné opakovat:

• GET opakujte vždy.
• PUT nahrazuje celý objekt (obsah šablony, graf automatizace, stavy objednávek): opakování se stejnými daty nic nepokazí; u obsahu a grafu ale hlídá verzi (viz níže).
• DELETE opakujte; druhé volání vrátí 404, což znamená „už smazáno“.
• POST /orders je upsert podle dvojice (shopId, id objednávky): opakování se stejnými daty vrátí change: "unchanged".
• POST /lists/{id}/members je idempotentní: kontakt, který už je členem, se počítá do alreadyMember.
• POST /contacts: druhé založení stejné adresy vrátí 409 conflict / email. Před opakováním kontakt vyhledejte (GET /contacts?q=adresa) a případně upravte přes PATCH.
• POST /contact-events idempotentní není: každá událost se zapíše znovu. Po časovém limitu raději jednu událost ztraťte, než ji pošlete dvakrát.
• POST /campaigns/{id}/approve chrání stav kampaně: druhé schválení vrátí 409 conflict / status.
• Při 429 počkejte Retry-After; při 5xx opakujte s rostoucí prodlevou (1, 2, 4, 8 s) a nejvýš pětkrát.

Souběžné úpravy (verze)#

Obsah šablon a kampaní, patičky a grafy automatizací mají číslo verze. Ukládání posílá baseVersion = verzi, kterou jste naposledy načetli. Když mezitím uložil někdo jiný, server vrátí 409 conflict / version s params.current; načtěte objekt znovu, sloučte změny a uložte s novou verzí.

Oprávnění#

• Každá operace patří do modulu (contacts, campaigns, content, settings, billing) a potřebuje úroveň read nebo full. Reference to u každé operace uvádí.
• Klíč s přístupem jen pro čtení dosáhne jen na operace s úrovní read (i POST, který jen počítá, například náhled segmentu). Jinak 403 forbidden / scope.
• Klíč v cizí firmě: 403 forbidden / tenant. Chybějící role: 403 forbidden s názvem modulu v message. Objekt jiné firmy se tváří jako neexistující (404).
• Bez přihlášené osoby (tedy ani klíčem) nejde: správa členů, pozvánek, API klíčů a připojených aplikací, hlavní vypínač odesílání a změny tarifu.

Neznámá pole#

Posílejte jen zdokumentovaná pole. Většina tras neznámá pole ignoruje, některé je odmítnou s názvem pole v message (například POST /orders), nastavení uzlů automatizace se při uložení zahodí. Nová pole v odpovědích mohou přibývat, klient je má ignorovat.