Přeskočit na obsah
API dokumentace

Recept: svátky se slevou

Cíl: každý den v 8:00 poslat kontaktům, které mají svátek, přání s jednorázovým slevovým kódem.

Potřebujete: klíč s rolí account_admin (zásobník kupónů je v modulu settings), slevové kódy z e-shopu.

Jak Poštárna pozná svátek

  • Kontakt s vyplněným polem nameDay (MM-DD) slaví v ten den.
  • Kontakt bez něj slaví podle prvního slova křestního jména (bez ohledu na velká písmena a diakritiku) v kalendáři svého jazyka: slovenský pro jazyk sk, kontakt bez jazyka podle jazyka e-shopu, jinak český. Kontakt bez jména svátek nemá.
  • Spouštěč trigger_date s kind: "name_day" projde kontakty e-shopu jednou denně v čase at (místní čas firmy). offsetDays posune den (například -1 = den předem).

1. Zásobník kupónů a kódy

Požadavek: 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
Odpověď: 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 jako text, jeden na řádek (duplicitní a neplatné se přeskočí):

Požadavek: 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
Odpověď: 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. Šablona s kódem

{{ data.promoCode('Svátek') }} vezme pro každý e-mail nový volný kód ze zásobníku s názvem „Svátek“ (totéž dělá značka {{coupon_svatek}} podle klíče). {{df_salution}} je oslovení v 5. pádě.

Požadavek: 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
Odpověď: 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. Automatizace

Požadavek: 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
Odpověď: 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 odeslání

POST /automations/{id}/test ukáže, kolik kontaktů by spouštěč vzal dnes (scope: "today") a kolik by jich došlo do každého uzlu. Nic se neuloží ani neodešle:

Požadavek: 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
Odpověď: 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. Zapnutí a stav kódů

Požadavek: 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"
Odpověď: 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žadavek: 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"
Odpověď: 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

  • Narozeniny: kind: "birthday" (pole birthday); 29. února se v jiných letech slaví 28. února.
  • Výročí z vlastního pole: kind: "custom_date", field: "cf:<id>" datového vlastního pole.
  • Svátky v kalendáři firmy (Vánoce, Den matek): kind: "holiday", dates: ["12-24"]; projde všechny kontakty e-shopu.
  • Výročí prvního nákupu: kind: "first_order", days: 365.