Automatizácie

Automatizácia (scenár) je graf: uzly (spúšťače, operátory, akcie) spojené hranami. Kontakt do scenára vstúpi spúšťačom, prechádza uzlami po hranách a scenár opustí v uzle Konec, na výstupe bez hrany alebo splnením cieľa. Každý priechod jedného kontaktu je beh (run).

Presné schémy všetkých uzlov, udalostí, podmienok a časových údajov: Referencia automatizácií. Hotové scenáre: recepty.

Graf#

{
  "nodes": [
    {"id": "kosik", "type": "trigger_event", "name": "Zmena košíka", "config": {"event": "cart_updated", "reentry": "restart"}},
    {"id": "pockat", "type": "wait", "config": {"mode": "duration", "value": 2, "unit": "hours"}},
    {"id": "stale-v-kosiku", "type": "condition", "config": {"definition": {"type": "group", "match": "all", "rules": [
      {"type": "cart_items_count", "operator": "gt", "value": 0},
      {"type": "ordered_since_entry", "operator": "no"}]}}},
    {"id": "email", "type": "send_email", "config": {"templateId": "301"}}
  ],
  "edges": [
    {"source": "kosik", "target": "pockat", "branch": "next"},
    {"source": "pockat", "target": "stale-v-kosiku", "branch": "next"},
    {"source": "stale-v-kosiku", "target": "email", "branch": "yes"}
  ]
}

• id uzla je kľúč, ktorý si zvolíte: písmená, číslice, - a _, najviac 40 znakov, v grafe jedinečný. Pri ďalších uloženiach ho nechajte rovnaký: behy, história a e-maily sa na uzol odkazujú kľúčom.
• type vyberá druh uzla, config jeho nastavenie. Neznáme kľúče v config server pri uložení zahodí. Voliteľne name (do 100 znakov), note (do 1 000) a position {x, y} pre plátno v aplikácii.
• Hrana vedie z výstupu (branch) zdroja do cieľa: next (jediný výstup), yes / no (podmienka), v1 až v10 (A/B test). Každý výstup má najviac jednu hranu; výstup bez hrany = kontakt scenár opustí.
• Graf nesmie mať cyklus (ani cez uzol goto), do spúšťača a cieľa nevedie hrana. Scenár smie mať viac spúšťačov. Najviac 300 uzlov a 600 hrán.
• Automatizácia patrí jednému e-shopu (odosielateľ, pätička, objednávky spúšťačov); e-shop sa po založení nemení.

Druhy uzlov#

Spúšťač pri udalosti (trigger_event)#

config.event vyberá udalosť; niektoré majú vlastné nastavenie:

Počítajú sa len udalosti po zapnutí automatizácie. Čo zapísal hromadný zápis (import, synchronizácia e-shopu), automatizácia nespustí, pokiaľ import výslovne nepovolí runAutomations: true. Objednávka zapísaná cez POST /orders spúšťače objednávok spúšťa.

Opakovaný vstup (reentry)#

Každý spúšťač má reentry:

• parallel: kontakt smie mať v scenári viac behov súčasne (najviac 10); východiskové pre nové spúšťače.
• restart: nový vstup ukončí rozbehnutý beh (typicky košík).
• skip: dokým beh kontaktu trvá, znovu nevstúpi.
• once: raz a navždy.

Jazyk podmienok#

Uzol condition, cieľ (goal) a filter časových spúšťačov (filter) majú definíciu: rovnaký strom ako segment, ktorého pravidlá smú byť aj podmienky automatizácie.

{"type": "group", "match": "all", "rules": [
  {"type": "contact_in_list", "listId": "41", "state": "confirmed"},
  {"type": "orders_total_value", "operator": "gte", "value": "3000", "currency": "CZK",
   "period": {"from": {"variant": "interval", "sign": "-", "value": 1, "unit": "years"}, "to": null}},
  {"type": "email_activity", "operator": "opened", "nodeId": "email-1", "negate": true}
]}

• match: all (a zároveň) alebo any (alebo). Skupiny sa môžu vnárať (najviac 8 úrovní, 50 pravidiel).
• Každé pravidlo smie mať "negate": true (neplatí, že).
• Pravidlá s obdobím majú period {from, to}; strany sú časové údaje relatívne k teraz, null = bez obmedzenia.
• Podmienky automatizácií (37 podľa SmartEmailingu a vlastné): kontakt v zozname, v automatizácii, pole kontaktu, výročie (narodeniny, meniny), odoslané a otvorené e-maily, počet a hodnota objednávok, objednaný produkt alebo atribút, košík, deň v mesiaci a týždni, hodina, kupón, skript, kliky, návštevy, feed, víťaz A/B testu, angažovanosť.
• Pravidlá, ktoré čítajú beh (email_activity, passed_node, ordered_since_entry, event_attribute, script), nejde použiť vo filtri spúšťača (beh tam ešte nie je).
• Hodnoty podmienok automatizácií smú byť čísla ("value": 0) aj reťazce číslic; pravidlá segmentu majú hodnoty ako reťazce.

Presné polia každého pravidla: Referencia automatizácií.

Podmienka s čakaním na splnenie#

condition.config.waitUntilMet {"value": 3, "unit": "days"}: kontakt v uzle čaká, dokým podmienka neplatí (potom výstup yes), najdlhšie po zadanú dobu (potom no). Kontrola beží každých 20 minút až raz denne podľa dĺžky čakania.

Čakanie a čas#

Uzol wait má mode:

Najdlhšie čakanie je 10 rokov. Časové údaje (spec, period) majú tri varianty: calendar (konkrétny deň), interval (posun o jednotky), event (pomenovaný deň: zajtra, ďalší pondelok, ďalší pracovný deň, posledný deň mesiaca). Náhľad presného okamihu: POST /automations/resolve-time.

Životný cyklus#

• POST /automations založí koncept (verzia 1); graf môžete poslať rovno, alebo neskôr cez PUT /automations/{id}/graph.
• POST /automations/{id}/activate zapne: draft alebo paused → active. Keď niečo chýba, vráti 400 validation / graph s params.issues (pozrite nižšie). Zapnutie posiela e-maily skutočným ľuďom.
• POST /automations/{id}/pause zastaví; čakajúce kontakty zostanú na mieste a po ďalšom zapnutí pokračujú.
• DELETE /automations/{id} zmaže len scenár, do ktorého nikto nevstúpil (inak 409 runs).
• POST /automations/{id}/copy vytvorí koncept „<názov> - kópia“ (bez hesiel webhookov).

Validácia a problémy grafu#

Problémy majú tvar {"node": "<kľúč>" | null, "field": "<pole>", "code": "<kód>"} a dve úrovne:

• Chyby (errors): graf sa nedá uložiť (400 validation / graph s params.issues). Kódy: invalid, unavailable (typ uzla), duplicate, node (hrana k neexistujúcemu uzlu), cycle, self_trigger (scenár by spúšťal sám seba).
• Neúplné nastavenie (incomplete): graf sa uloží, ale nejde zapnúť ani otestovať. Kódy: required, invalid, unavailable (udalosť alebo podmienka), not_found, locked (zoznam napojený na e-shop), empty (šablóna bez obsahu), lint (chyba kontroly obsahu šablóny), unverified (neoverený odosielateľ), unreachable (uzol, kam žiadny spúšťač nedojde), too_short, too_long, not_whitelisted, reserved. Bez spúšťača: {"node": null, "field": "trigger", "code": "required"}.

POST /automations/validate s {shopId, graph} skontroluje graf bez uloženia:

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/validate" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "shopId": "1",
  "graph": {
    "nodes": [
      {
        "id": "kosik",
        "type": "trigger_event",
        "config": {
          "event": "cart_updated",
          "shopId": "1",
          "reentry": "restart"
        }
      },
      {
        "id": "pockat",
        "type": "wait",
        "config": {
          "mode": "duration",
          "value": 2,
          "unit": "hours"
        }
      },
      {
        "id": "email",
        "type": "send_email",
        "config": {}
      }
    ],
    "edges": [
      {
        "source": "kosik",
        "target": "pockat"
      },
      {
        "source": "pockat",
        "target": "email"
      }
    ]
  }
}
JSON

{
  "errors": [],
  "incomplete": [
    {
      "node": "email",
      "field": "templateId",
      "code": "required"
    }
  ]
}

Detail automatizácie (GET /automations/{id}) vracia v issues všetko, čo bráni zapnutiu.

Uloženie grafu a verzie#

PUT /automations/{id}/graph s {"baseVersion", "graph"} vráti detail s verziou + 1.

• Iná verzia na serveri = 409 conflict / version s params.current.
• Bežiaci scenár (active) sa uloží len s "confirmRunning": true a len bez akéhokoľvek problému; inak 409 conflict / confirm. Zmeny platia pre ďalší krok každého kontaktu.
• Odstrániť alebo zmeniť typ uzla, v ktorom kontakty čakajú, nejde: 409 conflict / waiting s params.nodes (najprv ich uvoľnite: POST /automations/{id}/nodes/{kľúč}/release).
• Zmena spúšťača začne jeho plán znovu; nová hrana z odkladiska pustí čakajúce kontakty ďalej.
• Každé uloženie je verzia: GET /automations/{id}/versions, GET /automations/{id}/versions/{verzia}.

curl -sS -X PUT "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/graph" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "baseVersion": 1,
  "graph": {
    "nodes": [],
    "edges": []
  }
}
JSON

{
  "error": {
    "code": "conflict",
    "message": "confirm"
  }
}

Testovanie a sledovanie#

• POST /automations/{id}/test: skúšobný priechod nad dnešnými dátami, nič sa neuloží ani neodošle. Vráti, koľko kontaktov by vstúpilo a koľko by ich došlo do každého uzla a výstupu. Voliteľne graph (neuložený graf z editora) a days (1 až 90, okno prehrania udalostí).
• POST /automations/{id}/trace s {"contactId" | "email"}: priechod jedného kontaktu krok za krokom s dôvodmi (smie vstúpiť, kam pôjde, kde skončí). Nič sa neodošle.
• GET /automations/{id}/counts: živé počty po uzloch a výstupoch vrátane čakajúcich.
• GET /automations/{id}/runs?contactId=: história behov kontaktu.
• GET /automations/{id}/nodes/{kľúč}/passes: kto prešiel uzlom.
• GET /automations/{id}/report?from=&to= (aj format=csv): štatistiky e-mailových uzlov a volaní webhookov.

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/83/test" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{}
JSON

{
  "scope": "today",
  "days": null,
  "since": null,
  "entered": 0,
  "waiting": 0,
  "left": 0,
  "nodes": {
    "svatek": {
      "reached": 0,
      "waiting": 0,
      "left": 0,
      "outputs": {
        "next": 0
      }
    },
    "prani": {
      "reached": 0,
      "waiting": 0,
      "left": 0,
      "outputs": {
        "next": 0
      }
    }
  },
  "testedAt": "2026-10-01T08:00:00.000Z"
}

Kto vstúpi a kedy odíde e-mail#

• Vstupujú len kontakty, ktorým sa môže písať (prihlásené, bez potlačenia a slabého súhlasu, v lehote zákaznickej výnimky) z e-shopu automatizácie.
• E-mail uzla odíde jednému kontaktu najviac raz za 24 hodín (nastavenie firmy) a len so zapnutým odosielaním firmy, v dennom limite. Pred odoslaním sa stav kontaktu kontroluje znovu; e-mail starší než 48 hodín v poradí neodíde.
• Scenár, ktorý by spúšťal sám seba, sa nedá uložiť (self_trigger); reťaz scenárov (udalosť jedného spúšťa druhý) končí po 3 krokoch.
• Beh spustený objednávkou skončí, keď sa objednávka zruší, vráti alebo zmaže.

Udalosti z vášho systému#

POST /contact-events zapíše udalosť existujúceho kontaktu (podľa contactId alebo email; nikdy kontakt nezaloží):

• {"type": "custom", "name": "vip-dosiahnuty", "data": {...}}: vlastná udalosť pre spúšťač custom (názov a-z, 0-9 a -, najviac 50 znakov, nie se-).
• {"type": "cart", "shopId", "items": [{code, name, quantity, price, url}], "currency", "total"}: aktuálny stav košíka (prázdne items = košík vyprázdnený) pre cart_updated a podmienku cart_items_count.
• {"type": "visit", "shopId", "url", "visitType", "attributes"}: návšteva stránky pre page_visit.

Najviac 60 udalostí jedného kontaktu za 10 minút (429 rate_limited). Ukázka v recepte opusteného košíka.

Transakčné automatizácie (zmluvné e-maily)#

Na e-maily k uzavretej zmluve, napríklad upomienky splatnosti faktúr. Režim zapnete poľom "transactional": true pri POST /automations alebo PATCH /automations/{id} (rovnaké oprávnenie ako úprava automatizácií); prepnúť sa dá len scenár, ktorý nebeží (inak 409 conflict / status).

• Spúšťač smie byť len vlastná udalosť (trigger_event s event: "custom") a uzly len send_email, wait, condition a end. Iný graf vráti 400 validation / transactional (pri prepnutí) alebo graph (pri uložení) s params.issues a kódmi transactional_node, transactional_trigger.
• E-mail dostane každý existujúci kontakt bez ohľadu na súhlas s newsletterom alebo odhlásenie z neho. Tvrdý odraz, sťažnosť, neplatná adresa, limit mäkkých odrazov a blacklist ho zastavia vždy, pri vstupe aj tesne pred odoslaním.
• E-mail nemá odkaz na odhlásenie, hlavičku List-Unsubscribe ani pätičku newslettera. Šablóna preto nepotrebuje {{unsubscribe}} a nesmie ho mať (ani {{gf_footer}}, odkaz na nastavenie odberu alebo kupón; kód problému transactional_content). Otvorenia a prekliky sa merajú ako zvyčajne.
• Scenár patrí e-shopu udalosti: shopId pri POST /contact-events určuje, ktorá automatizácia sa spustí (bez neho sa použije hlavný e-shop kontaktu). Limit jedného e-mailu uzla za 24 hodín neplatí (dve faktúry jednej firmy s rovnakou splatnosťou dostanú dva e-maily); váš systém stráži opakovanie.
• Predmet e-mailu je obyčajný text bez skriptov: značky {{metadata.event.attributes.data.<kľúč>}} v ňom čítajú dáta udalosti (len jednoduché hodnoty), napríklad Faktúra {{metadata.event.attributes.data.invoiceNumber}}.
• Platobný QR kód: značka {{payment_qr}} vloží obrázok QR platby z data.spayd udalosti (reťazec SPAYD 1.0 s účtom ACC, český štandard pre platby v CZK), napríklad {% set d = metadata.event.attributes.data %}{% if d.spayd %}{{payment_qr}}{% endif %}. Obrázok je podpísaný odkaz /m/r/<token>.png na doméne odkazov, takže ho ukáže aj Gmail a Outlook; bez platného reťazca sa nevloží nič.
• Právna poznámka (nie je právne stanovisko): upomienka k vystavenej faktúre nie je obchodné oznámenie (zákon 452/2021 Z. z., v Česku zákon 480/2004 Sb.), právnym základom je plnenie zmluvy. E-mail preto nesmie obsahovať marketing (ponuky tovaru, kupóny, bannery).