Objednávky, feedy a kupóny

Objednávky

Objednávky poháňajú spúšťače (order_created, order_completed, order_changed), podmienky (počet a hodnota objednávok, objednaný produkt), segmenty a konverzie kampaní. Do Poštárne sa dostanú tromi cestami: konektorom e-shopu, feedom objednávok (kind: shop_orders) alebo API.

`POST /orders`: založenie alebo úprava

Objednávka sa ukladá podľa dvojice (shopId, id), kde id je číslo objednávky vo vašom e-shope. Prvý zápis vráti 201 a change: "created", ďalší 200 a updated alebo unchanged.

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

createdAt (povinné) a paidAt: ISO 8601 s časovou zónou.
email alebo contactId: kupujúci. Kupujúci bez kontaktu dostane nový kontakt v stave customer (bez marketingového súhlasu, e-maily nedostáva).
status: názov stavu vo vašom e-shope (napríklad „Zaplatené“). Na kanonický stav ho prevedie mapa stavov (nižšie).
currency: smie byť len mena e-shopu; iná = 400. Sumy ako desatinné reťazce.
items: položky s id (kód produktu), name (povinné), quantity, unit, price {withVat, withoutVat, currency}, url, imageUrl, attributes (atribúty z feedu, napríklad Category, Brand; podľa nich pracuje pravidlo order_attribute a podmienky na produkty).
deleted: true = objednávka bola zmazaná (beh po nákupe sa ukončí).
Neznáme pole = 400 s jeho názvom.

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

Mapa stavov

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 pravidlá mapy a v seen názvy stavov, ktoré prišli v objednávkach, s ich výsledným stavom; PUT /order-states pravidlá nahradí: {"items": [{"sourceStatus": "Zaplatené", "match": "exact", "state": "paid"}]} (match exact alebo prefix, najviac 500 pravidiel). Prekrytie sa prejaví aj na uložených objednávkach. Názov bez mapovania je other a nikdy sa nepočíta ako nákup.

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": []
}

Kedy objednávka spustí automatizáciu

order_created: nová objednávka; order_completed: objednávka sa prvý raz dostala do skupiny completed; order_changed: zmena stavu (voliteľne len do jedného stavu).
Objednávky z prvého importu feedu objednávok (história) a objednávky staršie než 2 dni vo feede automatizáciu nespúšťajú. Objednávka zapísaná cez POST /orders ju spúšťa.
Beh spustený objednávkou skončí, keď sa objednávka zruší, vráti alebo zmaže.
Každý e-shop by mal mať jediný zdroj objednávok (konektor, feed, alebo API); dva zdroje by uložili objednávky dvakrát.

Feedy

`kind`	Čo je	Limit
`google_products`	produktový feed Google Merchant (XML): produkty pre šablóny (`data.products`), párovanie položiek objednávok, podmienky	20 MB, 50 000 položiek
`shop_customers`	export zákazníkov e-shopu (CSV alebo XML); zákazník nie je odberateľ, nevzniká kontakt ani súhlas	100 MB, 500 000 záznamov
`shop_orders`	export objednávok e-shopu (CSV), jeden na e-shop; sťahuje sa každú hodinu, posledné 3 dni každých 10 minút	200 MB
`articles`	článkový feed (RSS 2.0 alebo Atom), napríklad blog e-shopu, pre `data.articles`

Produktový feed má format google, heureka alebo zbozi (zvolí sa pri založení).

POST /feeds s {kind, name, shopId, url, autoRefresh}, POST /feeds/{id}/refresh stiahne hneď, GET /feeds/{id}/items položky, GET /feeds/{id}/preview náhľad.
Tajná časť adresy (hash, token, key) sa v odpovediach maskuje.
Feedy patria do modulu settings (kľúč s rolou správcu účtu).

Zľavové kupóny

Zásobník (coupon stack) je sada jednorazových kódov jedného e-shopu:

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

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

V šablóne: {{coupon_<mergeKey>}} alebo {{ data.promoCode('<názov zásobníka>') }}. Každý e-mail dostane nový voľný kód a kód sa kontaktu priradí.
POST /coupon-stacks/{id}/assign priradí kód kontaktu ručne, POST /coupon-stacks/{id}/used označí kódy ako použité, GET /contacts/{id}/coupons kódy kontaktu.
Podmienka promo_code (dostal alebo použil kód zásobníka).
Dochádzajúce kódy zastavia e-mail (customizationDataboxOutOfPromocodes); sledujte counts.free.

Konverzie

Objednávka po prekliku z e-mailu sa pripočíta kampani alebo automatizácii ako konverzia: GET /conversions (súhrn po druhoch a menách), GET /stats/campaigns/{id}/conversions, GET /stats/automations/{id}/conversions. Tržby sú vždy po menách.

Objednávky, feedy a kupóny

Objednávky#

POST /orders: založenie alebo úprava#

Mapa stavov#

Kedy objednávka spustí automatizáciu#

Feedy#

Zľavové kupóny#

Konverzie#

Objednávky

`POST /orders`: založenie alebo úprava

Mapa stavov

Kedy objednávka spustí automatizáciu

Feedy

Zľavové kupóny

Konverzie