Preskočiť na obsah
API dokumentácia

Firma a e-shopy

Firma (tenant)

Účet v Poštárni patrí firme. V API sa jej hovorí tenant a jej verejné ID (UUID) je v ceste každej operácie: /api/v1/tenants/{tenant}/....

  • Dáta firiem sú od seba oddelené na úrovni databázy. Kľúč jednej firmy na ceste inej firmy dostane 403 forbidden / tenant, objekt inej firmy sa tvári ako neexistujúci (404).
  • Firma má členov s rolami (správca účtu, marketing, obsah, analytik, vývojár, financie). API kľúč patrí firme, pracuje s rolami, ktoré mu jeho autor dal, a nikdy nespravuje členov ani kľúče.
  • ID firmy zistíte z GET /api/v3/account-info (data.guid), pozrite Začíname.

E-shopy

Firma má jeden alebo viac e-shopov (napríklad CZ v korunách a SK v eurách). E-shop určuje:

  • menu (CZK alebo EUR): objednávky, košíky, kupóny a podmienky o tržbách sú vždy v mene e-shopu,
  • jazyk (cs alebo sk): východiskový jazyk kontaktov a stránok pre príjemcov,
  • odosielateľa (overené adresy, GET /senders) a pätičku s identitou firmy,
  • odkazovú doménu, na ktorej bežia odhlásenie, nastavenie odberu a formuláre.
Požiadavka: GET /api/v1/tenants/{tenant}/shops
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/shops" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "items": [
    {
      "id": "7",
      "code": "cz",
      "displayName": "Example.cz",
      "domain": "example.cz",
      "currency": "CZK",
      "language": "cs",
      "active": true
    },
    {
      "id": "8",
      "code": "sk",
      "displayName": "Example.sk",
      "domain": "example.sk",
      "currency": "EUR",
      "language": "sk",
      "active": true
    }
  ]
}

Ku ktorému e-shopu čo patrí:

ObjektVäzba na e-shop
Kontakthlavný e-shop (shopId); zakladá sa vždy s e-shopom
Zozname-shop, alebo celá firma (shopId: null)
Segmentvždy jeden e-shop; vyhodnocuje sa nad kontaktmi s týmto hlavným e-shopom
Kampaňjeden e-shop (odosielateľ, pätička, mena)
Automatizáciajeden e-shop; e-shop sa po založení nemení
Objednávka, košík, kupóny, feedjeden e-shop

Vypnutý e-shop (POST /shops/{id}/disable) nič nové neposiela: jeho automatizáciu nejde zapnúť a nové kampane neodídu.

Zákaznická výnimka (soft opt-in)

Zákazníkovi, ktorý u e-shopu nakúpil, smie e-shop za zákonných podmienok posielať obchodné oznámenia bez výslovného súhlasu. Poštárna to stráži po e-shopoch:

  • Slovenský e-shop má zo zákona limit 12 mesiacov od poslednej dokončenej objednávky (zákon č. 452/2021 Z. z., § 116 ods. 16), aj bez nastavenia.
  • Iný e-shop má výnimku vypnutú, dokým si ju firma nenastaví.
  • Čítanie a zmena: GET /consent-settings, PATCH /consent-settings/{shopId} s telom {"months": 12} (0 = vypnuté, 1 až 120 mesiacov).
  • Kontaktu, ktorému výnimka vypršala, kampane ani automatizácie nepošlú nič (v počte príjemcov ako exception_expired).

Časová zóna

Firma má časovú zónu (Europe/Prague alebo Europe/Bratislava). V nej sa počítajú kalendárne dni segmentov a podmienok, miestne časy automatizácií ("08:00", "2026-12-01T09:00") a dni v CSV štatistikách. Časy v JSON sú vždy v UTC.