Přeskočit na obsah
API dokumentace

Firma a e-shopy

Firma (tenant)

Účet v Poštárně patří firmě. V API se jí říká tenant a její veřejné ID (UUID) je v cestě každé operace: /api/v1/tenants/{tenant}/....

  • Data firem jsou od sebe oddělená na úrovni databáze. Klíč jedné firmy na cestě jiné firmy dostane 403 forbidden / tenant, objekt jiné firmy se tváří jako neexistující (404).
  • Firma má členy s rolemi (správce účtu, marketing, obsah, analytik, vývojář, finance). API klíč patří firmě, pracuje s rolemi, které mu jeho autor dal, a nikdy nespravuje členy ani klíče.
  • ID firmy zjistíte z GET /api/v3/account-info (data.guid), viz Začínáme.

E-shopy

Firma má jeden nebo víc e-shopů (například CZ v korunách a SK v eurech). E-shop určuje:

  • měnu (CZK nebo EUR): objednávky, košíky, kupóny a podmínky o tržbách jsou vždy v měně e-shopu,
  • jazyk (cs nebo sk): výchozí jazyk kontaktů a stránek pro příjemce,
  • odesílatele (ověřené adresy, GET /senders) a patičku s identitou firmy,
  • odkazovou doménu, na které běží odhlášení, nastavení odběru a formuláře.
Požadavek: 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"
Odpověď: 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
    }
  ]
}

Ke kterému e-shopu co patří:

ObjektVazba na e-shop
Kontakthlavní e-shop (shopId); zakládá se vždy s e-shopem
Sezname-shop, nebo celá firma (shopId: null)
Segmentvždy jeden e-shop; vyhodnocuje se nad kontakty s tímto hlavním e-shopem
Kampaňjeden e-shop (odesílatel, patička, měna)
Automatizacejeden e-shop; e-shop se po založení nemění
Objednávka, košík, kupóny, feedjeden e-shop

Vypnutý e-shop (POST /shops/{id}/disable) nic nového neposílá: jeho automatizace nejde zapnout a nové kampaně neodejdou.

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

Zákazníkovi, který u e-shopu nakoupil, smí e-shop za zákonných podmínek posílat obchodní sdělení bez výslovného souhlasu. Poštárna to hlídá po e-shopech:

  • Slovenský e-shop má ze zákona limit 12 měsíců od poslední dokončené objednávky (zákon č. 452/2021 Z. z., § 116 ods. 16), i bez nastavení.
  • Jiný e-shop má výjimku vypnutou, dokud si ji firma nenastaví.
  • Čtení a změna: GET /consent-settings, PATCH /consent-settings/{shopId} s tělem {"months": 12} (0 = vypnuto, 1 až 120 měsíců).
  • Kontaktu, kterému výjimka vypršela, kampaně ani automatizace nepošlou nic (v počtu příjemců jako exception_expired).

Časová zóna

Firma má časovou zónu (Europe/Prague nebo Europe/Bratislava). V ní se počítají kalendářní dny segmentů a podmínek, místní časy automatizací ("08:00", "2026-12-01T09:00") a dny v CSV statistikách. Časy v JSON jsou vždy v UTC.