Objednávky, feedy a kupóny

Objednávky

Objednávky pohánějí spouštěče (order_created, order_completed, order_changed), podmínky (počet a hodnota objednávek, objednaný produkt), segmenty a konverze kampaní. Do Poštárny se dostanou třemi cestami: konektorem e-shopu, feedem objednávek (kind: shop_orders) nebo API.

`POST /orders`: založení nebo úprava

Objednávka se ukládá podle dvojice (shopId, id), kde id je číslo objednávky ve vašem e-shopu. První zápis vrátí 201 a change: "created", další 200 a updated nebo unchanged.

Požadavek: 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

Odpověď: 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": {}
  }
}

createdAt (povinné) a paidAt: ISO 8601 s časovou zónou.
email nebo contactId: kupující. Kupující bez kontaktu dostane nový kontakt ve stavu customer (bez marketingového souhlasu, e-maily nedostává).
status: název stavu ve vašem e-shopu (například „Zaplaceno“). Na kanonický stav ho převede mapa stavů (níže).
currency: smí být jen měna e-shopu; jiná = 400. Částky jako desetinné řetězce.
items: položky s id (kód produktu), name (povinné), quantity, unit, price {withVat, withoutVat, currency}, url, imageUrl, attributes (atributy z feedu, například Category, Brand; podle nich pracuje pravidlo order_attribute a podmínky na produkty).
deleted: true = objednávka byla smazána (běh po nákupu se ukončí).
Neznámé pole = 400 s jeho názvem.

Požadavek: 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

Odpověď: 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": {}
  }
}

Mapa stavů

Kanonický stav (`state`)	Skupina (`status`)
`new`, `unpaid`, `processing`	`pending`
`paid`, `shipped`, `delivered`	`completed` (nákup)
`cancelled`, `returned`	`cancelled`
`other`	`other`

GET /order-states ukáže pravidla mapy a v seen názvy stavů, které přišly v objednávkách, s jejich výsledným stavem; PUT /order-states pravidla nahradí: {"items": [{"sourceStatus": "Zaplaceno", "match": "exact", "state": "paid"}]} (match exact nebo prefix, nejvýš 500 pravidel). Přemapování se projeví i na uložených objednávkách. Název bez mapování je other a nikdy se nepočítá jako nákup.

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

Odpověď: 200 OK

{
  "states": [
    "new",
    "unpaid",
    "paid",
    "processing",
    "shipped",
    "delivered",
    "cancelled",
    "returned",
    "other"
  ],
  "items": [],
  "seen": []
}

Kdy objednávka spustí automatizaci

order_created: nová objednávka; order_completed: objednávka se poprvé dostala do skupiny completed; order_changed: změna stavu (volitelně jen do jednoho stavu).
Objednávky z prvního importu feedu objednávek (historie) a objednávky starší než 2 dny ve feedu automatizace nespouštějí. Objednávka zapsaná přes POST /orders je spouští.
Běh spuštěný objednávkou skončí, když se objednávka zruší, vrátí nebo smaže.
Každý e-shop má mít jediný zdroj objednávek (konektor, feed, nebo API); dva zdroje by uložily objednávky dvakrát.

Feedy

`kind`	Co je	Limit
`google_products`	produktový feed Google Merchant (XML): produkty pro šablony (`data.products`), párování položek objednávek, podmínky	20 MB, 50 000 položek
`shop_customers`	export zákazníků e-shopu (CSV nebo XML); zákazník není odběratel, nevzniká kontakt ani souhlas	100 MB, 500 000 záznamů
`shop_orders`	export objednávek e-shopu (CSV), jeden na e-shop; stahuje se každou hodinu, poslední 3 dny každých 10 minut	200 MB
`articles`	článkový feed (RSS 2.0 nebo Atom), například blog e-shopu, pro `data.articles`

Produktový feed má format google, heureka nebo zbozi (zvolí se při založení).

POST /feeds s {kind, name, shopId, url, autoRefresh}, POST /feeds/{id}/refresh stáhne hned, GET /feeds/{id}/items položky, GET /feeds/{id}/preview náhled.
Tajná část adresy (hash, token, key) se v odpovědích maskuje.
Feedy patří do modulu settings (klíč s rolí správce účtu).

Slevové kupóny

Zásobník (coupon stack) je sada jednorázových kódů jednoho e-shopu:

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"
}

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"
  }
}

V šabloně: {{coupon_<mergeKey>}} nebo {{ data.promoCode('<název zásobníku>') }}. Každý e-mail dostane nový volný kód a kód se kontaktu přiřadí.
POST /coupon-stacks/{id}/assign přiřadí kód kontaktu ručně, POST /coupon-stacks/{id}/used označí kódy jako použité, GET /contacts/{id}/coupons kódy kontaktu.
Podmínka promo_code (dostal nebo použil kód zásobníku).
Došlé kódy zastaví e-mail (customizationDataboxOutOfPromocodes); hlídejte counts.free.

Konverze

Objednávka po prokliku z e-mailu se přičte kampani nebo automatizaci jako konverze: GET /conversions (souhrn po druzích a měnách), GET /stats/campaigns/{id}/conversions, GET /stats/automations/{id}/conversions. Tržby jsou vždy po měnách.

Objednávky, feedy a kupóny

Objednávky#

POST /orders: založení nebo úprava#

Mapa stavů#

Kdy objednávka spustí automatizaci#

Feedy#

Slevové kupóny#

Konverze#

Objednávky

`POST /orders`: založení nebo úprava

Mapa stavů

Kdy objednávka spustí automatizaci

Feedy

Slevové kupóny

Konverze