Preskočiť na obsah
API dokumentácia

Zoznamy a segmenty

ZoznamSegment
Členstvovýslovné: kontakty do neho pridáte (ručne, formulárom, importom, automatizáciou)podľa podmienok: kontakt je členom, dokým podmienky spĺňa
E-shopjeden e-shop, alebo celá firmavždy jeden e-shop
Typické použitieodber newslettera, VIP klub, kontakty z akcie„minuli vyše 3 000 Kč za rok“, „neotvorili 90 dní“
Kampaňánoáno
Podmienka v automatizáciicontact_in_listpravidlá segmentu priamo v podmienke

Zoznamy

  • GET /lists, POST /lists, PATCH /lists/{id}, DELETE /lists/{id}.
  • Ručné zoznamy (manualMembers: true): členov pridávate a odoberáte sami.
  • Zoznamy napojené na e-shop (systemKind shop_contacts, shop_newsletter, shop_unsubscribed) plní synchronizácia e-shopu; pridať alebo odobrať člena = 409 conflict / locked.
  • Formulárové zoznamy plnia formuláre, členov možno pridávať aj ručne.
  • publicName je názov zoznamu, ktorý kontakt uvidí na stránke nastavenia odberu.

Stavy členstva: confirmed (potvrdený), unconfirmed (čaká na potvrdenie odberu), unsubscribed (odhlásil sa z tohto zoznamu), removed (odobraný).

Požiadavka: POST /api/v1/tenants/{tenant}/lists
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "VIP zákazníci",
  "publicName": "Novinky pro VIP",
  "shopId": null,
  "notifyOnUnsubscribe": false,
  "notifyOnAdd": false,
  "note": ""
}
JSON
Odpoveď: 201 Created
{
  "id": "41",
  "name": "VIP zákazníci",
  "publicName": "Novinky pro VIP",
  "shopId": null,
  "systemKind": null,
  "locked": false,
  "manualMembers": true,
  "tags": [],
  "counts": {
    "total": 0,
    "byBucket": {
      "active": 0,
      "unconfirmed": 0,
      "unsubscribed": 0,
      "bounced": 0,
      "complained": 0,
      "blacklisted": 0
    }
  },
  "createdAt": "2026-10-01T08:00:00.000Z",
  "notifyOnUnsubscribe": false,
  "notifyOnAdd": false,
  "note": ""
}

Pridanie a odobranie členov

POST /lists/{id}/members s {"contactIds": [...]} (1 až 1 000 ID):

  • už člen = alreadyMember,
  • kontakt odhlásený z tohto zoznamu, odhlásený celkovo, nedoručiteľný alebo potlačený = skipped (nikdy ho znovu neprihlási),
  • ostatné = added (kontakt čakajúci na potvrdenie sa pridá ako unconfirmed).
Požiadavka: POST /api/v1/tenants/{tenant}/lists/41/members
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/lists/41/members" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "contactIds": [
    "1202"
  ]
}
JSON
Odpoveď: 200 OK
{
  "added": 1,
  "alreadyMember": 0,
  "skipped": 0
}
  • POST /lists/{id}/members/remove člena odoberie (stav removed), POST /lists/{id}/members/unsubscribe ho z tohto zoznamu odhlási.
  • Pridanie do zoznamu môže spustiť zapnutú automatizáciu so spúšťačom list_added.

Segmenty

Segment patrí jednému e-shopu a vyhodnocuje sa nad kontaktmi s týmto hlavným e-shopom. Definícia je strom skupín A (all) / ALEBO (any) a pravidiel:

Definícia segmentu
{"type": "group", "match": "all", "rules": [
  {"type": "list", "operator": "in", "listId": "43"},
  {"type": "group", "match": "any", "rules": [
    {"type": "order_value", "operator": "gte", "amount": "3000", "currency": "CZK", "shopId": "15", "days": "365"},
    {"type": "field", "field": "lastClickAt", "operator": "in_last_days", "value": "30"}]}]}
  • Najviac 8 úrovní skupín a 50 pravidiel. Prázdna podskupina je chyba; prázdny koreň zodpovedá všetkým kontaktom e-shopu (uložiť však ide len segment s aspoň jedným pravidlom).
  • Hodnoty pravidiel sú reťazce: počet dní "30" (1 až 3 650), suma "1500.50", dátum "2026-09-30".
  • Dni sú kalendárne dni v časovej zóne firmy: „za posledných 30 dní“ = od dnes minus 30 dní vrátane dneška; „nie za posledných N dní“ platí aj pre prázdny dátum (nikdy neotvoril).
  • Objednávky sa počítajú len dokončené; order_value sčíta len jednu menu (currency je povinná).
  • refresh: daily (vyhodnocuje sa živo) alebo static (snímka členov pri každom uložení).

Typy pravidiel: field (pole kontaktu), list (členstvo), order_count, order_value, last_order, order_attribute (kód, kategória alebo značka v objednávke), engagement (A až E, N), purpose (platný súhlas), custom_field, campaign (doručené, otvorené, kliknuté), segment (člen iného segmentu). Všetky polia a operátory: Referencia automatizácií › Pravidlá segmentov.

Živý náhľad počtu

POST /segments/preview spočíta kontakty bez uloženia: matched (spĺňa podmienky), mailable (z nich tí, ktorým možno písať), total (všetky kontakty e-shopu).

Požiadavka: POST /api/v1/tenants/{tenant}/segments/preview
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments/preview" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "shopId": "15",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "operator": "in",
        "listId": "43"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "type": "order_value",
            "operator": "gte",
            "amount": "3000",
            "currency": "CZK",
            "shopId": "15",
            "days": "365"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "operator": "in_last_days",
            "value": "30"
          }
        ]
      }
    ]
  }
}
JSON
Odpoveď: 200 OK
{
  "matched": 0,
  "mailable": 0,
  "total": 0
}

Uloženie

Požiadavka: POST /api/v1/tenants/{tenant}/segments
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Aktivní a utrácející",
  "shopId": "15",
  "refresh": "daily",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "operator": "in",
        "listId": "43"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "type": "order_value",
            "operator": "gte",
            "amount": "3000",
            "currency": "CZK",
            "shopId": "15",
            "days": "365"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "operator": "in_last_days",
            "value": "30"
          }
        ]
      }
    ]
  }
}
JSON
Odpoveď: 201 Created
{
  "id": "31",
  "name": "Aktivní a utrácející",
  "publicName": "",
  "shopId": "15",
  "refresh": "daily",
  "matched": 0,
  "mailable": 0,
  "computedAt": "2026-10-01T08:00:00.000Z",
  "ruleCount": 3,
  "tags": [],
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "list",
        "listId": "43",
        "operator": "in"
      },
      {
        "type": "group",
        "match": "any",
        "rules": [
          {
            "days": "365",
            "type": "order_value",
            "amount": "3000",
            "shopId": "15",
            "currency": "CZK",
            "operator": "gte"
          },
          {
            "type": "field",
            "field": "lastClickAt",
            "value": "30",
            "operator": "in_last_days"
          }
        ]
      }
    ]
  },
  "signatureHtml": ""
}

Chybné pravidlo vráti 400 s cestou k poľu: definition.<indexy od koreňa>.<pole>. Tu mena nepatrí e-shopu:

Požiadavka: POST /api/v1/tenants/{tenant}/segments
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/segments" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Chybný",
  "shopId": "15",
  "refresh": "daily",
  "definition": {
    "type": "group",
    "match": "all",
    "rules": [
      {
        "type": "order_value",
        "operator": "gte",
        "amount": "3000",
        "currency": "EUR",
        "shopId": "15"
      }
    ]
  }
}
JSON
Odpoveď: 400 Bad Request
{
  "error": {
    "code": "validation",
    "message": "definition.0.currency"
  }
}
  • Odkazy medzi segmentmi (segment) smú viesť len na segment rovnakého e-shopu, nesmú vytvoriť cyklus ani reťazec dlhší než 5 (definition.segmentCycle, definition.segmentDepth).
  • E-shop uloženého segmentu sa nemení (400 shop). Názov je vo firme jedinečný (409 name).