Preskočiť na obsah
API dokumentácia

Recept: séria po nákupe

Cieľ: 3 dni po dokončení objednávky o 9:00 poslať poďakovanie s odkazom na hodnotenie; kto za 7 dní neklikne, dostane tip na použitie produktu.

Potrebujete: kľúč s rolou marketing_manager (objednávky sú v module contacts, automatizácia v campaigns), mapu stavov objednávok (rola account_admin pre PUT /order-states).

Graf

Graf
[objednavka] trigger_event order_completed (reentry parallel)
  → [3-dny] wait 3 days → [rano] wait time_of_day 09:00
  → [jak-chutna] send_email → [7-dni] wait 7 days
  → [klikl] condition email_activity clicked (jak-chutna)
       ├─ yes → koniec
       └─ no  → [tip] send_email
  • order_completed nastane, keď sa objednávka prvý raz dostane do skupiny completed (zaplatená, odoslaná, doručená).
  • reentry: "parallel": zákazník s druhou objednávkou dostane sériu znovu, aj keď tá prvá ešte beží.
  • Keď sa objednávka zruší, vráti alebo zmaže, beh skončí a ďalšie e-maily neodídu.

1. Mapa stavov objednávok

Poštárna potrebuje vedieť, ktoré vaše stavy znamenajú nákup. Pozrite sa, čo už pozná:

Požiadavka: GET /api/v1/tenants/{tenant}/order-states
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/order-states" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "states": [
    "new",
    "unpaid",
    "paid",
    "processing",
    "shipped",
    "delivered",
    "cancelled",
    "returned",
    "other"
  ],
  "items": [],
  "seen": []
}

Chýbajúce stavy doplníte cez PUT /order-states (pozrite mapa stavov).

2. Šablóny

Dáta objednávky, ktorá beh spustila, sú v e-maile v metadata.order (položky v metadata.order.items):

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": "Po nákupu: jak chutná",
  "subject": "Jak vám chutná?",
  "preheader": "Dejte nám vědět, jak jste spokojeni",
  "content": {
    "editor": "html",
    "design": null,
    "html": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p>{% set o = metadata.order %}{% if o %}<p>děkujeme za objednávku {{ o.eshop_code }}.</p><ul>{% for item in o.items %}<li>{{ item.name }}</li>{% endfor %}</ul>{% endif %}<p><a href=\"https://www.example.cz/recenze\">Napsat hodnocení</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": "304",
  "name": "Po nákupu: jak chutná",
  "subject": "Jak vám chutná?",
  "preheader": "Dejte nám vědět, jak jste spokojeni",
  "editor": "html",
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "tags": [],
  "size": 462,
  "archived": false,
  "archivedAt": null,
  "readOnly": false,
  "usage": {
    "campaigns": 0,
    "automations": 0
  },
  "lastUsedAt": null,
  "check": {
    "errors": [],
    "warnings": [],
    "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>{% set o = metadata.order %}{% if o %}<p>děkujeme za objednávku {{ o.eshop_code }}.</p><ul>{% for item in o.items %}<li>{{ item.name }}</li>{% endfor %}</ul>{% endif %}<p><a href=\"https://www.example.cz/recenze\">Napsat hodnocení</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/7/558d86a4-2556-4849-b817-02b81558d85f"
}
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": "Po nákupu: tip na přípravu",
  "subject": "Tip, jak připravit kávu doma",
  "preheader": "Tři kroky k lepší kávě",
  "content": {
    "editor": "html",
    "design": null,
    "html": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>tady jsou tři tipy, jak si doma připravit lepší kávu.</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": "305",
  "name": "Po nákupu: tip na přípravu",
  "subject": "Tip, jak připravit kávu doma",
  "preheader": "Tři kroky k lepší kávě",
  "editor": "html",
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "tags": [],
  "size": 288,
  "archived": false,
  "archivedAt": null,
  "readOnly": false,
  "usage": {
    "campaigns": 0,
    "automations": 0
  },
  "lastUsedAt": null,
  "check": {
    "errors": [],
    "warnings": [],
    "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>tady jsou tři tipy, jak si doma připravit lepší kávu.</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/7/eafe9af1-437a-4904-be51-713bcd0113d9"
}

3. Automatizácia

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": "Po nákupu",
  "shopId": "13",
  "graph": {
    "nodes": [
      {
        "id": "objednavka",
        "type": "trigger_event",
        "config": {
          "event": "order_completed",
          "reentry": "parallel"
        }
      },
      {
        "id": "3-dny",
        "type": "wait",
        "config": {
          "mode": "duration",
          "value": 3,
          "unit": "days"
        }
      },
      {
        "id": "rano",
        "type": "wait",
        "config": {
          "mode": "time_of_day",
          "time": "09:00"
        }
      },
      {
        "id": "jak-chutna",
        "type": "send_email",
        "config": {
          "templateId": "304"
        }
      },
      {
        "id": "7-dni",
        "type": "wait",
        "config": {
          "mode": "duration",
          "value": 7,
          "unit": "days"
        }
      },
      {
        "id": "klikl",
        "type": "condition",
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "email_activity",
                "operator": "clicked",
                "nodeId": "jak-chutna"
              }
            ]
          }
        }
      },
      {
        "id": "tip",
        "type": "send_email",
        "config": {
          "templateId": "305"
        }
      }
    ],
    "edges": [
      {
        "source": "objednavka",
        "target": "3-dny"
      },
      {
        "source": "3-dny",
        "target": "rano"
      },
      {
        "source": "rano",
        "target": "jak-chutna"
      },
      {
        "source": "jak-chutna",
        "target": "7-dni"
      },
      {
        "source": "7-dni",
        "target": "klikl"
      },
      {
        "source": "klikl",
        "target": "tip",
        "branch": "no"
      }
    ]
  }
}
JSON
Odpoveď: 201 Created
{
  "id": "84",
  "name": "Po nákupu",
  "shopId": "13",
  "status": "draft",
  "version": 1,
  "activeSince": null,
  "firstActivatedAt": null,
  "pausedReason": null,
  "tags": [],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats": {
    "entered": 0,
    "active": 0,
    "sent": 0
  },
  "description": "",
  "graph": {
    "nodes": [
      {
        "id": "objednavka",
        "type": "trigger_event",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "event": "order_completed",
          "reentry": "parallel"
        }
      },
      {
        "id": "3-dny",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "duration",
          "unit": "days",
          "value": 3
        }
      },
      {
        "id": "rano",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "time_of_day",
          "time": "09:00"
        }
      },
      {
        "id": "jak-chutna",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "304"
        }
      },
      {
        "id": "7-dni",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "duration",
          "unit": "days",
          "value": 7
        }
      },
      {
        "id": "klikl",
        "type": "condition",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "email_activity",
                "nodeId": "jak-chutna",
                "operator": "clicked"
              }
            ]
          }
        }
      },
      {
        "id": "tip",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "305"
        }
      }
    ],
    "edges": [
      {
        "source": "objednavka",
        "target": "3-dny",
        "branch": "next"
      },
      {
        "source": "3-dny",
        "target": "rano",
        "branch": "next"
      },
      {
        "source": "rano",
        "target": "jak-chutna",
        "branch": "next"
      },
      {
        "source": "jak-chutna",
        "target": "7-dni",
        "branch": "next"
      },
      {
        "source": "7-dni",
        "target": "klikl",
        "branch": "next"
      },
      {
        "source": "klikl",
        "target": "tip",
        "branch": "no"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}
Požiadavka: POST /api/v1/tenants/{tenant}/automations/84/activate
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/84/activate" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "id": "84",
  "name": "Po nákupu",
  "shopId": "13",
  "status": "active",
  "version": 1,
  "activeSince": "2026-10-01T08:00:00.000Z",
  "firstActivatedAt": "2026-10-01T08:00:00.000Z",
  "pausedReason": null,
  "tags": [],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "stats": {
    "entered": 0,
    "active": 0,
    "sent": 0
  },
  "description": "",
  "graph": {
    "nodes": [
      {
        "id": "objednavka",
        "type": "trigger_event",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "event": "order_completed",
          "reentry": "parallel"
        }
      },
      {
        "id": "3-dny",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "duration",
          "unit": "days",
          "value": 3
        }
      },
      {
        "id": "rano",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "time_of_day",
          "time": "09:00"
        }
      },
      {
        "id": "jak-chutna",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "304"
        }
      },
      {
        "id": "7-dni",
        "type": "wait",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "mode": "duration",
          "unit": "days",
          "value": 7
        }
      },
      {
        "id": "klikl",
        "type": "condition",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "definition": {
            "type": "group",
            "match": "all",
            "rules": [
              {
                "type": "email_activity",
                "nodeId": "jak-chutna",
                "operator": "clicked"
              }
            ]
          }
        }
      },
      {
        "id": "tip",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "305"
        }
      }
    ],
    "edges": [
      {
        "source": "objednavka",
        "target": "3-dny",
        "branch": "next"
      },
      {
        "source": "3-dny",
        "target": "rano",
        "branch": "next"
      },
      {
        "source": "rano",
        "target": "jak-chutna",
        "branch": "next"
      },
      {
        "source": "jak-chutna",
        "target": "7-dni",
        "branch": "next"
      },
      {
        "source": "7-dni",
        "target": "klikl",
        "branch": "next"
      },
      {
        "source": "klikl",
        "target": "tip",
        "branch": "no"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}

4. Objednávky z e-shopu

Pri vytvorení objednávky a pri každej zmene stavu pošlite celú objednávku. Kupujúci bez kontaktu dostane kontakt v stave customer, ktorý e-maily nedostáva; séria tak prijde len zákazníkom s marketingovým súhlasom.

Požiadavka: POST /api/v1/tenants/{tenant}/orders
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "id": "2026001234",
  "shopId": "13",
  "createdAt": "2026-10-01T09:30:00+02:00",
  "paidAt": "2026-10-01T09:31:00+02:00",
  "email": "karel.vesely@example.cz",
  "status": "Zaplaceno",
  "eshopCode": "2026001234",
  "orderUrl": "https://www.example.cz/objednavka/2026001234",
  "currency": "CZK",
  "totalWithVat": "1290.00",
  "totalWithoutVat": "1066.12",
  "items": [
    {
      "id": "KAVA-1KG",
      "name": "Káva Kolumbie 1 kg",
      "quantity": 1,
      "unit": "ks",
      "price": {
        "withVat": "1290.00",
        "withoutVat": "1066.12",
        "currency": "CZK"
      },
      "url": "https://www.example.cz/kava-kolumbie",
      "attributes": {
        "Category": "Káva",
        "Brand": "Example"
      }
    }
  ]
}
JSON
Odpoveď: 201 Created
{
  "change": "created",
  "order": {
    "id": "5001",
    "externalId": "2026001234",
    "eshopCode": "2026001234",
    "eshopName": "Example.cz",
    "shopId": "13",
    "createdAt": "2026-10-01T07:30:00.000Z",
    "paidAt": "2026-10-01T07:31:00.000Z",
    "email": "karel.vesely@example.cz",
    "contactId": "1205",
    "state": "paid",
    "status": "completed",
    "sourceStatus": "Zaplaceno",
    "orderUrl": "https://www.example.cz/objednavka/2026001234",
    "currency": "CZK",
    "totalWithVat": "1290.00",
    "totalWithoutVat": "1066.12",
    "itemCount": 1,
    "items": [
      {
        "id": "1",
        "productCode": "KAVA-1KG",
        "name": "Káva Kolumbie 1 kg",
        "description": "",
        "price": {
          "withVat": "1290.00",
          "withoutVat": "1066.12",
          "currency": "CZK"
        },
        "quantity": 1,
        "unit": "ks",
        "url": "https://www.example.cz/kava-kolumbie",
        "imageUrl": "",
        "attributes": {
          "Brand": "Example",
          "Category": "Káva"
        },
        "paired": false
      }
    ],
    "conversion": null,
    "deleted": false,
    "receivedAt": "2026-10-01T08:00:00.000Z",
    "updatedAt": "2026-10-01T08:00:00.000Z",
    "seller": {},
    "orderDelivery": {}
  }
}

Zmena stavu (pozor, zápis nahrádza celú objednávku, posielajte všetky polia):

Požiadavka: POST /api/v1/tenants/{tenant}/orders
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/orders" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "id": "2026001234",
  "shopId": "13",
  "createdAt": "2026-10-01T09:30:00+02:00",
  "paidAt": "2026-10-01T09:31:00+02:00",
  "email": "karel.vesely@example.cz",
  "status": "Předáno zákazníkovi",
  "eshopCode": "2026001234",
  "currency": "CZK",
  "totalWithVat": "1290.00",
  "items": [
    {
      "id": "KAVA-1KG",
      "name": "Káva Kolumbie 1 kg",
      "quantity": 1,
      "price": {
        "withVat": "1290.00",
        "currency": "CZK"
      }
    }
  ]
}
JSON
Odpoveď: 200 OK
{
  "change": "updated",
  "order": {
    "id": "5001",
    "externalId": "2026001234",
    "eshopCode": "2026001234",
    "eshopName": "Example.cz",
    "shopId": "13",
    "createdAt": "2026-10-01T07:30:00.000Z",
    "paidAt": "2026-10-01T07:31:00.000Z",
    "email": "karel.vesely@example.cz",
    "contactId": "1205",
    "state": "paid",
    "status": "completed",
    "sourceStatus": "Předáno zákazníkovi",
    "orderUrl": "",
    "currency": "CZK",
    "totalWithVat": "1290.00",
    "totalWithoutVat": null,
    "itemCount": 1,
    "items": [
      {
        "id": "2",
        "productCode": "KAVA-1KG",
        "name": "Káva Kolumbie 1 kg",
        "description": "",
        "price": {
          "withVat": "1290.00",
          "withoutVat": null,
          "currency": "CZK"
        },
        "quantity": 1,
        "unit": "",
        "url": "",
        "imageUrl": "",
        "attributes": {},
        "paired": false
      }
    ],
    "conversion": null,
    "deleted": false,
    "receivedAt": "2026-10-01T08:00:00.000Z",
    "updatedAt": "2026-10-01T08:00:00.000Z",
    "seller": {},
    "orderDelivery": {}
  }
}
Požiadavka: GET /api/v1/tenants/{tenant}/orders/5001
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/orders/5001" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "id": "5001",
  "externalId": "2026001234",
  "eshopCode": "2026001234",
  "eshopName": "Example.cz",
  "shopId": "13",
  "createdAt": "2026-10-01T07:30:00.000Z",
  "paidAt": "2026-10-01T07:31:00.000Z",
  "email": "karel.vesely@example.cz",
  "contactId": "1205",
  "state": "paid",
  "status": "completed",
  "sourceStatus": "Předáno zákazníkovi",
  "orderUrl": "",
  "currency": "CZK",
  "totalWithVat": "1290.00",
  "totalWithoutVat": null,
  "itemCount": 1,
  "items": [
    {
      "id": "2",
      "productCode": "KAVA-1KG",
      "name": "Káva Kolumbie 1 kg",
      "description": "",
      "price": {
        "withVat": "1290.00",
        "withoutVat": null,
        "currency": "CZK"
      },
      "quantity": 1,
      "unit": "",
      "url": "",
      "imageUrl": "",
      "attributes": {},
      "paired": false
    }
  ],
  "conversion": null,
  "deleted": false,
  "receivedAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "seller": {},
  "orderDelivery": {}
}

Varianty

  • Len prvý nákup: do série pridajte za spúšťač podmienku orders_count ("operator": "eq", "value": 1).
  • Podľa kategórie: podmienka ordered_product_by_attribute s "limitToTriggerEvent": true a "attribute": "Category" vyberie len objednávky s produktom danej kategórie.
  • Kúpte si znovu: samostatná automatizácia so spúšťačom trigger_reorder pošle pripomenutie, keď zákazníkovi dochádza obvyklý interval medzi nákupmi.