Vložení objednávky

Endpoint vytvoření objednávky umožní vložit novou objednávku do Shoptetu. Hlavní použití je pro import starých objednávek z jiných systémů nebo založení objednávky, která vznikla v jiném systému (např. přes Heuréku). Endpoint je poměrně složitý kvůli množství položek, validacím a variabilitě eshopů, proto mu věnujeme samostatný článek.

Popis endpointu naleznete v Apiary. Tady najdete příklady, jaké parametry posílat do Shoptet API, když chcete vytvořit různé varianty obsahu objednávky.

V objednávce se objevují různé typy položek a zde si ukážeme, jak je správně používat pokud chcete založit konkrétní objednávky.

Typ položky určíte atributem itemType, který může nabývat těchto hodnot:

Příznaky product, bazar, service, gift nemají vliv na stav produktu v objednávce, proto nekontrolujeme zda typ produktu v databázi souhlasí s předaným typem.

Minimální příklad

Minimální objednávka s doručením musí obsahovat tři položky: dopravu, platbu a kupované zboží. Jednotlivá položka objednávky musí obsahovat minimálně atributy itemType, vatRate a jeden údaj z dvojice itemPriceWithVat nebo itemPriceWithoutVat. Ceny se uvádějí jako jednotkové.

{
  "itemType":"shipping",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Systém Shoptet je možné používat i jako pokladnu na provozovně. V takovém případě v systému vznikají objednávky bez samostatných položek pro dopravu a platbu. Přes API můžete vytvořit objednávku z pokladny také. V poli data v takovém případě pošlete "cashDeskOrder": true a objednávka bude vytvořena v režimu pokladny. V tomto režimu nemusíte u objednávky vyplňovat email zákazníka a mezi položkami objednávky není třeba uvádět dopravu a platbu. V režimu pokladny tedy stačí mít v položkách objednávky jen produkty, které se prodávají (tedy minimálně jednu položku).

Stavy objednávky a položek

V systému Shoptet má svůj stav každá objednávka i její jednotlivé položky. Tyto stavy se mohou lišit. Základní stavy objednávek jsou společné pro všechny eshopy, ale každý eshop si může nadefinovat další vlastní stavy podle svých potřeb. Seznam stavů objednávek získáte přes API v endpointu /api/orders/statuses.

Stav objednávky i jednotlivých položek můžete určit i přes API. Slouží k tomu atribut statusId. Stav objednávky se může a nemusí propisovat do položek objednávky, proto si jeho chování rozebereme podrobněji.

V odpovědi endpointu /api/orders/statuses najdete atribut defaultStatus, to bude dále status označovaný jako výchozí. Dál pro náš případ bude důležitý atribut changeOrderItems u jednotlivých stavů. Tento atribut určuje zda se má stav objednávky automaticky propsat do všech položek. Pro náš příklad si představme, že ze seznamu stavů objednávek získáme následující odpověď (zjednodušeno):

{
  "data": {
    "defaultStatus": 5,
    "statuses": [
      {
        "id": 1,
        "name": "Nevyřízená",
        "changeOrderItems": true
      },
      {
        "id": 2,
        "name": "Zabaleno",
        "changeOrderItems": false
      },
      {
        "id": 5,
        "name": "Nová",
        "changeOrderItems": false
      },
    ]
  }
}

A předpokládejme následující request (opět zjednodušeno):

{
    "data": {
        "externalCode": "201900232323",
        "statusId": "X", # tuto hodnotu budeme měnit
    "items": [
        {
            "itemType": "product",
            "code": "product-A",
                "statusId": "2"
        },
        {
            "itemType": "product",
            "code": "product-B"
        }
    ]
    }
}

Stavy objednávek se pak budou propisovat následovně (čtěte po řádcích):

StatusId objednávky (X) product-A product-B
null (atribut neuveden), doplní se výchozí 5 2 5 (výchozí)
1 ("changeOrderItems": true) 2 1
2 ("changeOrderItems": false) 2 5 (výchozí)
5 ("changeOrderItems": false) 2 5 (výchozí)

Dohledávání informací o produktech a kontrola jejich existence

Každou položku objednávky s uvedeným atributem code zkouší systém dohledat v aktuální databázi eshopu. Pokud položku najde doplní z nalezených informací případné chybějící parametry o položce (jméno, hmotnost, výrobce, záruku). Pokud položku nenajde skončí s chybou, že nezná položku s určitým code. Pokud potřebujete založit i položky, které na eshopu neexistují, můžete kontrolu existence potlačit pomocí GET parametru suppressProductChecking=true.

Položka objednávky je jednoznačně identifikována pomocí code. Můžete ale uvést i upřesňující productGuid, kterým specifikujete, ke kterému produktu daný code patří. Tato informace slouží pouze pro přesnější dohledávání. Pokud byste tedy uvedli neplatnou kombinaci code a productGuid dostanete informaci o neplatném code nebo productGuid.

Ukázky vstupů pro vytvoření objednávky

Běžný produkt

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Bazarový produkt

{
  "itemType":"bazar",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Služba

{
  "itemType":"service",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
}

Dárek

{
  "itemType":"gift",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "0.00",  # za dárek se neplatí
  "priceRatio": "0.0000"
}

Sada produktů

{
  "itemType":"product-set",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "300.00"
}

Sada produktů musí být dohledatelná v databázi, odkud doplňujeme obsah sady produktů. Při importu historických objednávek můžete tuto kontrolu potlačit použitím parametru suppressProductChecking=true, v takovém případě se neznámá sada produktů vloží do objednávky jako běžný produkt s odpovídající cenou.

Slevový kupón na procentuální slevu

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00", # Cena před slevou.
  "priceRatio": "0.9700" # Koeficient, kterým se bude cena násobit. 3% ~ 0.03 => 0.9700.
},
{
  "itemType":"product",
  "code": "24-FIA",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00", # Cena před slevou.
  "priceRatio": "0.9700" # Koeficient, kterým se bude cena násobit. 3% ~ 0.03 => 0.9700.
},
{
  "itemType":"discount-coupon",  # Pro discount-coupon neposíláme "code".
  "name": "Slevový kupón AKCE-LETO, sleva 3%", # Název položky objednávky.
  "itemPriceWithoutVat": "0.00", # Slevový kupón je zdarma.
  "vatRate":"21.00"
}

Slevový kupón na konkrétní částku (produkty v jedné sazbě DPH)

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00" # Cena před slevou.
},
{
  "itemType":"product",
  "code": "24-FIA",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00" # Cena před slevou.
},
{
  "itemType":"discount-coupon",  # Pro discount-coupon neposíláme "code".
  "name": "Slevový kupón AKCE-LETO-FIX, sleva 25 Kč", # Název položky objednávky.
  "itemPriceWithVat": "-25.00", # Sleva na přesnou částku se uvádí u kupónu.
  "vatRate":"21.00" # Stejná jako vatRate položek objednávky.
}

Slevový kupón na dopravu zdarma

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"
},
{
  "itemType":"shipping", # Pro shipping neposíláme "code".
  "vatRate":"21.00",
  "itemPriceWithoutVat": "0.00" # Doprava je zdarma.
},
{
  "itemType":"discount-coupon",  # Pro discount-coupon neposíláme "code".
  "name": "Slevový kupón AKCE-DOPRAVA - Doprava zdarma", # Název položky objednávky.
  "itemPriceWithVat": "0.00", # Slevový kupón je zdarma.
  "vatRate":"21.00" # Stejná jako vatRate položek objednávky.
}

Sleva (Eshopař ji přidává v administraci)

{
  "itemType":"product",
  "code": "32/ZEL",
  "vatRate":"21.00",
  "itemPriceWithoutVat": "100.00"  # Původní cena položky.
},
{
  "itemType":"volume-discount",  # Pro volume-discount neposíláme "code".
  "name": "Sleva", # Název položky objednávky.
  "itemPriceWithVat": "-45.00", # Provozovatel eshopu dal dodatečnou slevu 45 Kč.
  "vatRate":"0.00"
}

Slevový kupón, sleva a různé sazby DPH

Slevový kupón pošlete s libovolnou sazbou DPH a slevu opět s 0.00. V detailu objednávky v administraci eshopu je pak objednávka automaticky vidět se slevami rozpadlými podle různých sazeb DPH.

Facebook
Twitter