Preskočiť na obsah
API dokumentácia

Recept: meniny so zľavou

Cieľ: každý deň o 8:00 poslať kontaktom, ktoré majú meniny, prianie s jednorazovým zľavovým kódom.

Potrebujete: kľúč s rolou account_admin (zásobník kupónov je v module settings), zľavové kódy z e-shopu.

Ako Poštárna pozná meniny

  • Kontakt s vyplneným poľom nameDay (MM-DD) oslavuje v ten deň.
  • Kontakt bez neho oslavuje podľa prvého slova krstného mena (bez ohľadu na veľké písmená a diakritiku) v kalendári svojho jazyka: slovenský pre jazyk sk, kontakt bez jazyka podľa jazyka e-shopu, inak český. Kontakt bez mena meniny nemá.
  • Spúšťač trigger_date s kind: "name_day" prejde kontakty e-shopu raz denne v čase at (miestny čas firmy). offsetDays posunie deň (napríklad -1 = deň vopred).

1. Zásobník kupónov a kódy

Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Svátek",
  "shopId": "11",
  "mergeKey": "svatek",
  "note": "Sleva 15 % k svátku"
}
JSON
Odpoveď: 201 Created
{
  "id": "11",
  "name": "Svátek",
  "shopId": "11",
  "mergeKey": "svatek",
  "tag": "{{coupon_svatek}}",
  "note": "Sleva 15 % k svátku",
  "counts": {
    "total": 0,
    "free": 0,
    "assigned": 0,
    "used": 0
  },
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z"
}

Kódy vložte ako text, jeden na riadok (duplicitné a neplatné sa preskočia):

Požiadavka: POST /api/v1/tenants/{tenant}/coupon-stacks/11/codes
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks/11/codes" \
  -H "Authorization: Bearer $POSTARNA_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "text": "SVATEK-7Q2K\nSVATEK-9P4M\nSVATEK-3X8D\n"
}
JSON
Odpoveď: 200 OK
{
  "counts": {
    "added": 3,
    "duplicate": 0,
    "invalid": 0,
    "total": 3
  },
  "stack": {
    "id": "11",
    "name": "Svátek",
    "shopId": "11",
    "mergeKey": "svatek",
    "tag": "{{coupon_svatek}}",
    "note": "Sleva 15 % k svátku",
    "counts": {
      "total": 3,
      "free": 3,
      "assigned": 0,
      "used": 0
    },
    "createdAt": "2026-10-01T08:00:00.000Z",
    "updatedAt": "2026-10-01T08:00:00.000Z"
  }
}

2. Šablóna s kódom

{{ data.promoCode('Svátek') }} vezme pre každý e-mail nový voľný kód zo zásobníka s názvom „Svátek“ z príkladu (to isté robí značka {{coupon_svatek}} podľa kľúča). {{df_salution}} je oslovenie v 5. páde.

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": "Svátek",
  "subject": "Všechno nejlepší k svátku, {{df_salution|default('milý zákazníku', true)}}",
  "preheader": "Dárek k svátku: 15 % sleva",
  "content": {
    "editor": "html",
    "design": null,
    "html": "<!doctype html><html><body><p>Dobrý den, {{df_salution|default('vážený zákazníku', true)}},</p><p>k dnešnímu svátku vám přejeme vše nejlepší. Dárkem je sleva 15 % s kódem <strong>{{ data.promoCode('Svátek') }}</strong>.</p><p><a href=\"https://www.example.cz/\">Nakoupit se slevou</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": "303",
  "name": "Svátek",
  "subject": "Všechno nejlepší k svátku, {{df_salution|default('milý zákazníku', true)}}",
  "preheader": "Dárek k svátku: 15 % sleva",
  "editor": "html",
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z",
  "tags": [],
  "size": 425,
  "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>k dnešnímu svátku vám přejeme vše nejlepší. Dárkem je sleva 15 % s kódem <strong>{{ data.promoCode('Svátek') }}</strong>.</p><p><a href=\"https://www.example.cz/\">Nakoupit se slevou</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/6/2dbee2ba-4435-418f-a8f4-da1f961a9d1a"
}

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": "Svátek",
  "shopId": "11",
  "graph": {
    "nodes": [
      {
        "id": "svatek",
        "type": "trigger_date",
        "config": {
          "kind": "name_day",
          "at": "08:00",
          "reentry": "parallel"
        }
      },
      {
        "id": "prani",
        "type": "send_email",
        "config": {
          "templateId": "303"
        }
      }
    ],
    "edges": [
      {
        "source": "svatek",
        "target": "prani"
      }
    ]
  }
}
JSON
Odpoveď: 201 Created
{
  "id": "83",
  "name": "Svátek",
  "shopId": "11",
  "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": "svatek",
        "type": "trigger_date",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "at": "08:00",
          "kind": "name_day",
          "reentry": "parallel"
        }
      },
      {
        "id": "prani",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "303"
        }
      }
    ],
    "edges": [
      {
        "source": "svatek",
        "target": "prani",
        "branch": "next"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}

4. Test bez odoslania

POST /automations/{id}/test ukáže, koľko kontaktov by spúšťač zobral dnes (scope: "today") a koľko by ich došlo do každého uzla. Nič sa neuloží ani neodošle:

Požiadavka: POST /api/v1/tenants/{tenant}/automations/83/test
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
Odpoveď: 200 OK
{
  "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"
}

5. Zapnutie a stav kódov

Požiadavka: POST /api/v1/tenants/{tenant}/automations/83/activate
curl -sS -X POST "https://www.postarna.cz/api/v1/tenants/$TENANT/automations/83/activate" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "id": "83",
  "name": "Svátek",
  "shopId": "11",
  "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": "svatek",
        "type": "trigger_date",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "at": "08:00",
          "kind": "name_day",
          "reentry": "parallel"
        }
      },
      {
        "id": "prani",
        "type": "send_email",
        "name": "",
        "note": "",
        "position": {
          "x": 0,
          "y": 0
        },
        "config": {
          "templateId": "303"
        }
      }
    ],
    "edges": [
      {
        "source": "svatek",
        "target": "prani",
        "branch": "next"
      }
    ]
  },
  "issues": [],
  "triggers": {}
}
Požiadavka: GET /api/v1/tenants/{tenant}/coupon-stacks/11
curl -sS -X GET "https://www.postarna.cz/api/v1/tenants/$TENANT/coupon-stacks/11" \
  -H "Authorization: Bearer $POSTARNA_API_KEY"
Odpoveď: 200 OK
{
  "id": "11",
  "name": "Svátek",
  "shopId": "11",
  "mergeKey": "svatek",
  "tag": "{{coupon_svatek}}",
  "note": "Sleva 15 % k svátku",
  "counts": {
    "total": 3,
    "free": 3,
    "assigned": 0,
    "used": 0
  },
  "createdAt": "2026-10-01T08:00:00.000Z",
  "updatedAt": "2026-10-01T08:00:00.000Z"
}

Varianty

  • Narodeniny: kind: "birthday" (pole birthday); 29. februára sa v iných rokoch oslavuje 28. februára.
  • Výročie z vlastného poľa: kind: "custom_date", field: "cf:<id>" dátového vlastného poľa.
  • Sviatky v kalendári firmy (Vianoce, Deň matiek): kind: "holiday", dates: ["12-24"]; prejde všetky kontakty e-shopu.
  • Výročie prvého nákupu: kind: "first_order", days: 365.