Recept: opustený košík

Cieľ: zákazníkovi, ktorý si niečo vložil do košíka a do 2 hodín neobjednal, poslať pripomenutie. Keď košík medzitým vyprázdni alebo objedná, e-mail neodíde.

Potrebujete: kľúč s rolou marketing_manager alebo account_admin (moduly content a campaigns plný prístup, contacts pre kontakty), overeného odosielateľa e-shopu, ID e-shopu (GET /shops).

Ako to funguje

Graf

[kosik] trigger_event cart_updated (reentry restart)
   └─ next → [pockat] wait 2 hours
                └─ next → [stale-v-kosiku] condition: košík nie je prázdny A neobjednal od vstupu
                             ├─ yes → [email] send_email (šablóna Opustený košík)
                             └─ no  → (koniec, kontakt scenár opustí)

Každá zmena košíka (POST /contact-events typ cart) je udalosť cart_updated. Vďaka reentry: "restart" ďalšia zmena košíka ukončí rozbehnutý beh a čakanie začne znovu, takže zákazník dostane jedno pripomenutie až 2 hodiny po poslednej zmene.
Podmienka cart_items_count číta posledný stav košíka: prázdny košík (alebo košík, ktorý sa od objednávky nezmenil) má 0 položiek.
ordered_since_entry: no vylúči kontakty, ktoré od vstupu do scenára objednali.

1. Šablóna e-mailu

V e-maile automatizácie sú dáta udalosti, ktorá beh spustila, v metadata.event.attributes (pri košíku itemCount, total, currency, shopId):

Požiadavka: POST /api/v1/tenants/{tenant}/templates

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/templates" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Opuštěný košík",
  "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku",
  "preheader": "Váš košík na vás počká ještě pár dní",
  "content": {
    "editor": "html",
    "design": null,
    "html": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.</p><p><a href=\"https://www.example.cz/kosik/\">Dokončit objednávku</a></p><p style=\"font-size:12px\">{{cl_company}}, {{cl_address}}. <a href=\"{{unsubscribe}}\">Odhlásit odběr</a></p></body></html>"
  }
}
JSON

Odpoveď: 201 Created

{
  "id": "301",
  "name": "Opuštěný košík",
  "subject": "{{df_name|default('Dobrý den', true)}}, něco jste nechali v košíku",
  "preheader": "Váš košík na vás počká ještě pár dní",
  "editor": "html",
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "tags": [],
  "size": 465,
  "archived": false,
  "archivedAt": null,
  "readOnly": false,
  "usage": {
    "campaigns": 0,
    "automations": 0
  },
  "lastUsedAt": null,
  "check": {
    "errors": [],
    "warnings": [
      "subject_long"
    ],
    "checkedAt": "2026-10-01T08:00:00.000Z"
  },
  "content": {
    "editor": "html",
    "html": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>ve vašem košíku zůstalo {{ metadata.event.attributes.itemCount }} ks zboží za {{ metadata.event.attributes.total }} {{ metadata.event.attributes.currency }}.</p><p><a href=\"https://www.example.cz/kosik/\">Dokončit objednávku</a></p><p style=\"font-size:12px\">{{cl_company}}, {{cl_address}}. <a href=\"{{unsubscribe}}\">Odhlásit odběr</a></p></body></html>",
    "design": null,
    "version": 1,
    "updatedAt": "2026-10-01T08:00:00.000Z"
  },
  "settings": {
    "linkParams": [],
    "headers": [],
    "unsubscribePageId": null,
    "footerId": null
  },
  "draft": {
    "pending": false,
    "savedAt": null,
    "publishedAt": null
  },
  "activeUses": {
    "automations": 0,
    "emails": 0,
    "campaigns": 0
  },
  "publicUrl": "https://links.example.cz/template/1/72cf576a-85b2-474e-86e2-bfdbd1f4d38f"
}

2. Kontrola grafu bez uloženia

POST /automations/validate ukáže chyby (errors, graf sa nedá uložiť) a neúplné nastavenia (incomplete, nejde zapnúť). Tu chýba šablóna e-mailu:

Požiadavka: POST /api/v1/tenants/{tenant}/automations/validate

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

Odpoveď: 200 OK

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

3. Založenie automatizácie

Požiadavka: POST /api/v1/tenants/{tenant}/automations

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Opuštěný košík",
  "shopId": "1",
  "description": "Připomenutí košíku po 2 hodinách",
  "tags": [
    "e-shop"
  ],
  "graph": {
    "nodes": [
      {
        "id": "kosik",
        "type": "trigger_event",
        "name": "Změna košíku",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "event": "cart_updated",
          "shopId": "1",
          "reentry": "restart"
        }
      },
      {
        "id": "pockat",
        "type": "wait",
        "name": "Počkat 2 hodiny",
        "position": {
          "x": 0,
          "y": 150
        },
        "config": {
          "mode": "duration",
          "value": 2,
          "unit": "hours"
        }
      },
      {
        "id": "stale-v-kosiku",
        "type": "condition",
        "name": "Košík stále plný a bez objednávky",
        "position": {
          "x": 0,
          "y": 300
        },
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "cart_items_count",
                "operator": "gt",
                "value": 0,
                "shopId": "1"
              },
              {
                "type": "ordered_since_entry",
                "operator": "no",
                "shopId": "1"
              }
            ]
          }
        }
      },
      {
        "id": "email",
        "type": "send_email",
        "name": "Připomenutí",
        "position": {
          "x": 0,
          "y": 450
        },
        "config": {
          "templateId": "301",
          "trackOpens": true,
          "trackClicks": true
        }
      }
    ],
    "edges": [
      {
        "source": "kosik",
        "target": "pockat",
        "branch": "next"
      },
      {
        "source": "pockat",
        "target": "stale-v-kosiku",
        "branch": "next"
      },
      {
        "source": "stale-v-kosiku",
        "target": "email",
        "branch": "yes"
      }
    ]
  }
}
JSON

Odpoveď: 201 Created

{
  "id": "81",
  "name": "Opuštěný košík",
  "shopId": "1",
  "status": "draft",
  "version": 1,
  "activeSince": null,
  "firstActivatedAt": null,
  "pausedReason": null,
  "tags": [
    "e-shop"
  ],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats": {
    "entered": 0,
    "active": 0,
    "sent": 0
  },
  "description": "Připomenutí košíku po 2 hodinách",
  "graph": {
    "nodes": [
      {
        "id": "kosik",
        "type": "trigger_event",
        "name": "Změna košíku",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "event": "cart_updated",
          "shopId": "1",
          "reentry": "restart"
        }
      },
      {
        "id": "pockat",
        "type": "wait",
        "name": "Počkat 2 hodiny",
        "note": "",
        "position": {
          "x": 0,
          "y": 150
        },
        "config": {
          "mode": "duration",
          "unit": "hours",
          "value": 2
        }
      },
      {
        "id": "stale-v-kosiku",
        "type": "condition",
        "name": "Košík stále plný a bez objednávky",
        "note": "",
        "position": {
          "x": 0,
          "y": 300
        },
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "cart_items_count",
                "value": 0,
                "shopId": "1",
                "operator": "gt"
              },
              {
                "type": "ordered_since_entry",
                "shopId": "1",
                "operator": "no"
              }
            ]
          }
        }
      },
      {
        "id": "email",
        "type": "send_email",
        "name": "Připomenutí",
        "note": "",
        "position": {
          "x": 0,
          "y": 450
        },
        "config": {
          "templateId": "301",
          "trackOpens": true,
          "trackClicks": true
        }
      }
    ],
    "edges": [
      {
        "source": "kosik",
        "target": "pockat",
        "branch": "next"
      },
      {
        "source": "pockat",
        "target": "stale-v-kosiku",
        "branch": "next"
      },
      {
        "source": "stale-v-kosiku",
        "target": "email",
        "branch": "yes"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}

Automatizácia vznikne ako koncept (status: "draft", verzia 1). Odpoveď má v issues všetko, čo bráni zapnutiu; tu je prázdne.

4. Zapnutie

Požiadavka: POST /api/v1/tenants/{tenant}/automations/81/activate

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/activate" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"

Odpoveď: 200 OK

{
  "id": "81",
  "name": "Opuštěný košík",
  "shopId": "1",
  "status": "active",
  "version": 1,
  "activeSince": "2026-10-01T08:00:00.000Z",
  "firstActivatedAt": "2026-10-01T08:00:00.000Z",
  "pausedReason": null,
  "tags": [
    "e-shop"
  ],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats": {
    "entered": 0,
    "active": 0,
    "sent": 0
  },
  "description": "Připomenutí košíku po 2 hodinách",
  "graph": {
    "nodes": [
      {
        "id": "kosik",
        "type": "trigger_event",
        "name": "Změna košíku",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "event": "cart_updated",
          "shopId": "1",
          "reentry": "restart"
        }
      },
      {
        "id": "pockat",
        "type": "wait",
        "name": "Počkat 2 hodiny",
        "note": "",
        "position": {
          "x": 0,
          "y": 150
        },
        "config": {
          "mode": "duration",
          "unit": "hours",
          "value": 2
        }
      },
      {
        "id": "stale-v-kosiku",
        "type": "condition",
        "name": "Košík stále plný a bez objednávky",
        "note": "",
        "position": {
          "x": 0,
          "y": 300
        },
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "cart_items_count",
                "value": 0,
                "shopId": "1",
                "operator": "gt"
              },
              {
                "type": "ordered_since_entry",
                "shopId": "1",
                "operator": "no"
              }
            ]
          }
        }
      },
      {
        "id": "email",
        "type": "send_email",
        "name": "Připomenutí",
        "note": "",
        "position": {
          "x": 0,
          "y": 450
        },
        "config": {
          "templateId": "301",
          "trackOpens": true,
          "trackClicks": true
        }
      }
    ],
    "edges": [
      {
        "source": "kosik",
        "target": "pockat",
        "branch": "next"
      },
      {
        "source": "pockat",
        "target": "stale-v-kosiku",
        "branch": "next"
      },
      {
        "source": "stale-v-kosiku",
        "target": "email",
        "branch": "yes"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}

Keď niečo chýba (neoverený odosielateľ, chyba v obsahu šablóny, neúplný uzol), server vráti 400 validation / graph s params.issues.

5. Udalosti košíka z e-shopu

Pri každej zmene košíka prihláseného zákazníka pošlite aktuálny obsah. Kontakt nájde Poštárna podľa email alebo contactId; udalosť nikdy nezaloží nový kontakt (neznámy kontakt = 404).

Požiadavka: POST /api/v1/tenants/{tenant}/contacts

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contacts" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "email": "lucie.mala@example.cz",
  "shopId": "1",
  "purposeId": "1",
  "consentConfirmed": true,
  "firstName": "Lucie",
  "vocativeFirstName": "Lucie"
}
JSON

Odpoveď: 201 Created

{
  "id": "1201",
  "email": "lucie.mala@example.cz",
  "firstName": "Lucie",
  "lastName": "",
  "status": "subscribed",
  "engagement": "N",
  "excluded": false,
  "shopId": "1",
  "suppressionReason": null,
  "blacklisted": false,
  "blacklistedAt": null,
  "state": null,
  "createdAt": "2026-10-01T08:00:00.000Z",
  "phone": "",
  "mobile": "",
  "titleBefore": "",
  "titleAfter": "",
  "salutation": "",
  "salutationFormal": "",
  "vocativeFirstName": "Lucie",
  "vocativeLastName": "",
  "gender": null,
  "language": "cs",
  "company": "",
  "companyId": "",
  "street": "",
  "city": "",
  "postalCode": "",
  "note": "",
  "affiliateId": "",
  "country": null,
  "birthday": null,
  "nameDay": null,
  "source": "manual",
  "consentBasis": "imported",
  "statusAt": "2026-10-01T08:00:00.000Z",
  "consentAt": "2026-10-01T08:00:00.000Z",
  "consentWeak": false,
  "softBounces": 0,
  "lastSentAt": null,
  "lastOpenAt": null,
  "lastClickAt": null,
  "suppressedAt": null,
  "engagementAt": null,
  "suppressionNote": null,
  "customFields": {},
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats90d": {
    "received": 0,
    "opened": 0,
    "clicked": 0,
    "bestHour": null
  },
  "lists": [],
  "recentActivities": [
    {
      "id": "consent-1",
      "type": "status_change",
      "at": "2026-10-01T08:00:00.000Z",
      "title": "purpose_assigned"
    }
  ],
  "orders": [],
  "orderTotals": [],
  "editedFields": [],
  "sources": []
}

Požiadavka: POST /api/v1/tenants/{tenant}/contact-events

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contact-events" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "type": "cart",
  "email": "lucie.mala@example.cz",
  "shopId": "1",
  "currency": "CZK",
  "total": "589.00",
  "items": [
    {
      "code": "KAVA-250",
      "name": "Káva Brazílie 250 g",
      "quantity": 2,
      "price": "249.00",
      "url": "https://www.example.cz/kava-brazilie"
    },
    {
      "code": "FILTR-02",
      "name": "Papírové filtry",
      "quantity": 1,
      "price": "91.00"
    }
  ]
}
JSON

Odpoveď: 201 Created

{
  "id": "9004"
}

Vyprázdnený košík (alebo dokončenú objednávku) pošlite ako prázdne items:

Požiadavka: POST /api/v1/tenants/{tenant}/contact-events

curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/contact-events" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "type": "cart",
  "contactId": "1201",
  "shopId": "1",
  "items": []
}
JSON

Odpoveď: 201 Created

{
  "id": "9005"
}

Najviac 60 udalostí jedného kontaktu za 10 minút (429 rate_limited). Posielajte stav košíka po zmene, nie pri každom zobrazení stránky.
Objednávku zapíšte cez POST /orders; podmienka ordered_since_entry ju uvidí.

6. Sledovanie

Počty po uzloch (waiting = kontakty, ktoré práve čakajú):

Požiadavka: GET /api/v1/tenants/{tenant}/automations/81/counts

curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/81/counts" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"

Odpoveď: 200 OK

{
  "nodes": {},
  "runs": {
    "active": 0,
    "completed": 0,
    "exited": 0
  }
}

História jedného kontaktu: GET /automations/{id}/runs?contactId=1201. Priechod kontaktu bez odoslania: POST /automations/{id}/trace s {"contactId": "1201"}.

7. Úprava bežiacej automatizácie

Bežiaci scenár sa dá uložiť len s "confirmRunning": true, inak 409 confirm:

Požiadavka: PUT /api/v1/tenants/{tenant}/automations/81/graph

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

Odpoveď: 409 Conflict

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

Varianty

Dve pripomenutia: za e-mail pridajte wait (1 deň), znovu rovnakú podmienku a druhý send_email, napríklad so zľavou ({{ data.promoCode('Košík') }}).
Len stáli zákazníci: do podmienky pridajte pravidlo segmentu order_count ("operator": "gte", "value": "1"), alebo filter na vlastné pole kontaktu.
Cieľ scenára: uzol goal s pravidlom ordered_since_entry: yes ukončí beh, hneď ako zákazník objedná, kdekoľvek je.

Recept: opustený košík

Ako to funguje#

1. Šablóna e-mailu#

2. Kontrola grafu bez uloženia#

3. Založenie automatizácie#

4. Zapnutie#

5. Udalosti košíka z e-shopu#

6. Sledovanie#

7. Úprava bežiacej automatizácie#

Varianty#

Ako to funguje

1. Šablóna e-mailu

2. Kontrola grafu bez uloženia

3. Založenie automatizácie

4. Zapnutie

5. Udalosti košíka z e-shopu

6. Sledovanie

7. Úprava bežiacej automatizácie

Varianty