Pravidlá API

Platí pre API v1 (/api/v1/...). API v3 kompatibilné so SmartEmailingom má vlastné obálky a formáty, popísané v Kompatibilite so SmartEmailingom.

Adresa a formát#

• Základ: https://www.postarna.cz/api/v1. Operácie firmy: /api/v1/tenants/{tenant}/..., kde {tenant} je verejné ID firmy (UUID).
• Telo požiadaviek POST, PUT a PATCH je JSON (Content-Type: application/json, UTF-8). Iný typ obsahu = 415 validation / contentType, telo, ktoré nie je objekt JSON, = 400 validation / body. Výjimky: nahrávanie CSV a súborov prijíma aj multipart/form-data.
• Odpovede sú JSON v UTF-8 (diakritika nie je escapovaná). Exporty a štatistiky zvládnu aj CSV (format=csv).
• Jedno telo požiadavky má najviac 5 MB (väčšie = 413 validation / size); CSV súbor importu nahraný ako multipart/form-data až 64 MB.

Dátové typy#

• Časy zapisované do API (sendAt, createdAt objednávky) posielajte s časovou zónou (Z alebo +02:00).
• Dni v segmentoch a podmienkach („za posledných 30 dní“) sú kalendárne dni v časovej zóne firmy (Europe/Prague, Europe/Bratislava).
• Meny sa nikdy nesčítavajú ani neprevádzajú. Každý e-shop má jednu menu; objednávka v inej mene, než má jej e-shop, je chyba 400. Súčty (tržby, konverzie) sú vždy po menách.

Stránkovanie, vyhľadávanie a triedenie#

• Zoznamy objektov majú page (od 1) a pageSize (1 až 100, východiskovo 25). Odpoveď je {"items": [...], "total": 240, "page": 1, "pageSize": 25}.
• Prejdite všetky stránky, dokým page * pageSize < total.
• q hľadá v názve alebo adrese bez ohľadu na veľkosť písmen a diakritiku (najviac 200 znakov). Pri automatizáciách q=#123 nájde automatizáciu podľa ID.
• shop obmedzí prehľad na jeden e-shop (ID e-shopu).
• sort pri prehľadoch, ktoré ho majú: pole oddelené čiarkou, - na začiatku = zostupne, najviac 3 polia (sort=name,-createdAt). Východiskové triedenie je od najnovšieho. Neznáme pole = 400 validation / sort.

Chyby#

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

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

• code: stály strojový kód (validation, unauthorized, forbidden, not_found, conflict, rate_limited, unavailable a ďalšie). Podľa neho sa rozhodujte.
• message: technický údaj, obvykle názov poľa (email, definition.1.0.listId, graph) alebo dôvod (version, status). Nie je to text pre ľudí a môže byť prázdny.
• params: podrobnosti, napríklad issues pri grafe automatizácie, expected a actual pri počte príjemcov, reason.
• API neposiela texty pre ľudí; texty v češtine a slovenčine si skladá aplikácia.

Úplný zoznam kódov s významom a nápravou: Chyby a limity.

Limity požiadaviek#

• Na firmu (všetky kľúče spolu): zásobník 2 500 požiadaviek, ktorý sa doplňuje 4 požiadavkami za sekundu, a 100 000 požiadaviek za deň (doplňuje sa priebežne, žiadny reset o polnoci).
• Každá odpoveď na požiadavku s kľúčom nesie X-RateLimit-Limit, X-RateLimit-Remaining a X-RateLimit-Reset (unixový čas, kedy bude zásobník zase plný) zásobníka, ktorému zostáva menej.
• Po prekročení prichádza 429 rate_limited s hlavičkou Retry-After (za koľko sekúnd). Odmietnuté požiadavky sa nepočítajú.
• Niektoré akcie majú vlastné limity (testovacie e-maily, udalosti kontaktu, MCP); sú v Chybách a limitoch.

Opakovanie požiadaviek a idempotencia#

API nepoužíva hlavičku Idempotency-Key. Po výpadku siete alebo chybe 5xx preto opakujte len to, čo je bezpečné opakovať:

• GET opakujte vždy.
• PUT nahrádza celý objekt (obsah šablóny, graf automatizácie, stavy objednávok): opakovanie s rovnakými dátami nič nepokazí; pri obsahu a grafe však sleduje verziu (pozrite nižšie).
• DELETE opakujte; druhé volanie vráti 404, čo znamená „už zmazané“.
• POST /orders je upsert podľa dvojice (shopId, id objednávky): opakovanie s rovnakými dátami vráti change: "unchanged".
• POST /lists/{id}/members je idempotentné: kontakt, ktorý je už členom, sa počíta do alreadyMember.
• POST /contacts: druhé založenie rovnakej adresy vráti 409 conflict / email. Pred opakovaním kontakt vyhľadajte (GET /contacts?q=adresa) a prípadne upravte cez PATCH.
• POST /contact-events idempotentné nie je: každá udalosť sa zapíše znovu. Po časovom limite skôr jednu udalosť straťte, než ju pošlite dvakrát.
• POST /campaigns/{id}/approve chráni stav kampane: druhé schválenie vráti 409 conflict / status.
• Pri 429 počkajte Retry-After; pri 5xx opakujte s rastúcim odstupom (1, 2, 4, 8 s) a najviac päťkrát.

Súbežné úpravy (verzie)#

Obsah šablón a kampaní, pätičky a grafy automatizácií majú číslo verzie. Ukladanie posiela baseVersion = verziu, ktorú ste naposledy načítali. Keď medzitým uložil niekto iný, server vráti 409 conflict / version s params.current; načítajte objekt znovu, zlúčte zmeny a uložte s novou verziou.

Oprávnenia#

• Každá operácia patrí do modulu (contacts, campaigns, content, settings, billing) a potrebuje úroveň read alebo full. Referencia to pri každej operácii uvádza.
• Kľúč s prístupom len na čítanie dosiahne len na operácie s úrovňou read (aj POST, ktorý len počíta, napríklad náhľad segmentu). Inak 403 forbidden / scope.
• Kľúč v cudzej firme: 403 forbidden / tenant. Chýbajúca rola: 403 forbidden s názvom modulu v message. Objekt inej firmy sa tvári ako neexistujúci (404).
• Bez prihlásenej osoby (teda ani kľúčom) nejde: správa členov, pozvánok, API kľúčov a pripojených aplikácií, hlavný vypínač odosielania a zmeny tarifu.

Neznáme polia#

Posielajte len zdokumentované polia. Väčšina trás neznáme polia ignoruje, niektoré ich odmietnu s názvom poľa v message (napríklad POST /orders), nastavenie uzlov automatizácie sa pri uložení zahodí. Nové polia v odpovediach môžu pribúdať, klient ich má ignorovať.