Objednávky

Práca s objednávkami.

GET /interface/{db}/eshop/v1/objednavky/zoznam

Rozhranie dodáva zoznam objednávok. Iba tie, ktoré vytvoril e-shop.

  • Status: implementované
  • Bearer: áno

GET /interface/{db}/eshop/v1/objednavky/detail

Rozhranie dodáva detail k objednávke. Základné parametre a jednotlivé položky objednávky.

  • Status: implementované
  • Bearer: áno

Nová objednávka (v. 1)

Vytvorenie novej objednávky.

  • URL: POST /interface/{db}/eshop/v1/objednavky/vytvor
  • Status: implementované
  • Bearer: áno

Nová objednávka (v. 2)

Vytvorenie novej objednávky. Voči predchádzajúcej verzii umožňuje nastaviť polia fu_id (forma úhrady), sposob_id (spôsob dopravy), ks_id (konštantný symbol) a lehota_id (dodacia lehota).

  • URL: POST /interface/{db}/eshop/v2/objednavky/vytvor
  • Status: implementované (2.1.0)
  • Bearer: áno

Popis správania jednotlivých parametrov.

  • firma_id - Ak je objednávka na konkrétnu firmu, musí byť toto vyplnené na záznam v číselníku firiem.
    • Musí byť vyplnená alebo firma, alebo osoba a dané záznamy musia existovať v príslušnej tabuľke.
  • osoba_id - Ak je objednávka na konkrétnu osobu, musí byť toto vyplnené na záznam v číselníku osôb.
  • datum - Dátum vytvorenia objednávky. Povinný údaj.
  • poznamka(neobnedzená) - Poznámka k objednávke. Nepovinný údaj.
  • objednavka_orig(50) - Číslo objednávky napríklad v e-shope. Nepovinný údaj.
  • fu_id - Forma úhrady. Podľa /interface/{db}/eshop/v1/objednavky/forma_uhrady. Nepovinný údaj.
  • sposob_id - Spôsob dopravy. Podľa /interface/{db}/eshop/v1/objednavky/sposob_dopravy. Nepovinný údaj.
  • ks_id - Konštantný symbol. Podľa /interface/{db}/eshop/v1/objednavky/konstantny_symbol. Nepovinný údaj.
  • lehota_id - Dodacia lehota. Podľa /interface/{db}/eshop/v1/objednavky/dodacia_lehota.
    • Ak je ID nasmerované na záznam, kde pole dni je <0, N>, potom sa v objednávke posunie dátum dodania na dátum vytvorenia+N.
    • Ak je v zázname pole dni=-1 (na konkrétny deň), v tejto implementácii je to počítane ako dátum vytvorenia+0. Ak by bolo treba vkladať konkrétny deň, treba o to požiadať a my to upravíme v programe.

Riadok objednávky:

  • karta_id - ID skladovej karty. Ak ho nevyplníte, považuje sa riadok za textovú položku a treba vyplniť mj, dph a nazov.
    • Ak sa karta nenájde, API vráti chybu 400.
    • Ak je skladová karta ako zrušená, API vráti chybu 400 (od API 2.7.1, program 5.50.0.51).
  • sklad_id (od API 2.7.1, program 5.50.0.51) - Požadovaný sklad. Za bežných okolností je tento parameter nepovinný a API sem doplní sklad, ktorý je dohodnutý v nastavení API. Ak viete, z ktorého skladu sa má tovar použiť, potom môžete nastaviť tento parameter ku každému riadku objednávky.
    • Ak sa sklad nenájde, API vráti chybu 400.
    • Ak je sklad ako zrušený, API vráti chybu 400.
    • Ak skladová karta nie je nastavená pre tento sklad, API vráti chybu 400.
  • mnozstvo - Požadované množstvo.
  • cena - Požadovaná cena.
  • zlava - Požadovaná zľava. Ak zľava nie je, nastavte 0.
  • mj - Požadovaná množstvená jednotka. Vyplňujte iba v prípade textovej položky.
  • dph - DPH. Vyplňujte iba v prípade textovej položky.
  • nazov - Názov položky. Vyplňujte iba v prípade textovej položky.

Príklad objednávky s jednou položkou

Objednávka predpokladá, že existuje firma s id=2 a skladová karta s id=1. Objednávajú sa 2 kusy s jednotkovou cenou bez DPH 5 EUR. Poskytuje sa zľava 1%.

{
 "datum": "2018-07-02T00:00:00.000Z",
 "poznamka": "string",
 "objednavka_orig": "origstring",
 "firma_id": 2,
 "osoba_id": 0,
 "fu_id": 2,
 "sposob_id": 1,
 "ks_id": "0008",
 "items": [
   {
     "karta_id": 1,
     "mnozstvo": 2,
     "cena": 5,
     "zlava": 1
   }
 ]
}

Príklad objednávky s viac položkami

Objednávka predpokladá, že existuje firma s id=2 a skladová karta s id=1 a 2. Na jednu položku je zľava a na druhú nie.

{
 "datum": "2018-07-11T00:00:00.000Z",
 "poznamka": "string",
 "objednavka_orig": "origstring",
 "firma_id": 2,
 "osoba_id": 0,
 "items": [
   {
     "karta_id": 1,
     "mnozstvo": 2,
     "cena": 5,
     "zlava": 1
   },
   {
     "karta_id": 2,
     "mnozstvo": 2,
     "cena": 1,
     "zlava": 0
   }
 ]
}

Príklad čisto textovej objednávky, ktorá objednáva dopravu

Objednávka predpokladá, že existuje firma s id=2. V objednávke je jedna textová položka s názvom, cenou a DPH. Bude podporované od API 1.3.0.

{
 "datum": "2018-08-01T00:00:00.000Z",
 "poznamka": "Príklad čisto textovej objednávky, ktorá objednáva dopravu.",
 "objednavka_orig": "origstring",
 "firma_id": 2,
 "osoba_id": 0,
 "items": [
   {
     "karta_id": null,
     "mnozstvo": 2,
     "mj": "ks",
     "cena": 5,
     "zlava": 0,
     "dph": 20,
     "nazov": "Dopravné náklady"
   }
 ]
}

Príklad kombinovanej objednávky s jednou skladovou kartou a jednou textovou zľavou

Objednávka predpokladá, že existuje firma s id=2. V objednávke je jedna skladová karta s id=1. V objednávke je jedna textová položka s názvom, cenou a DPH. Cena je záporná, pretože predstavuje poskytnutú zľavu. Bude podporované od API 1.3.0.

{
 "datum": "2018-08-01T00:00:00.000Z",
 "poznamka": "Príklad čisto textovej objednávky, ktorá objednáva skladovú kartu a poskytuje textovú zľavu.",
 "objednavka_orig": "origstring",
 "firma_id": 2,
 "osoba_id": 0,
 "items": [
   {
     "karta_id": 1,
     "mnozstvo": 2,
     "cena": 10,
     "zlava": 0
   },
   {
     "karta_id": null,
     "mnozstvo": 1,
     "mj": "ks",
     "cena": -2,
     "zlava": 0,
     "dph": 20,
     "nazov": "Celková zľava na objednávku"
   }
 ]
}

Príklad s adresou dodania

Objednávka predpokladá, že existuje firma s id=2. V objednávke je jedna skladová karta s id=1. Ak sa pripojí parameter dodanie, na faktúre sa objaví aj adresa dodania. Podporované od API 1.3.0 a Optivus verzia 5.24.0.x.

{
 "datum": "2018-08-01T00:00:00.000Z",
 "poznamka": "Príklad objednávky s adresou dodania. Pomenovanie je voliteľné, ak sa dá null, použije implicitné pomenovanie.",
 "objednavka_orig": "origstring",
 "firma_id": 2,
 "osoba_id": 0,
 "dodanie": {
   "pomenovanie": "Adresa dodania",
   "adresat": "Róbert Ulbricht",
   "ulica": "Partizánska 71",
   "mesto": "97401 Banská Bystrica"
 },
 "items": [
   {
     "karta_id": 1,
     "mnozstvo": 2,
     "cena": 10,
     "zlava": 0
   }
 ]
}

Príplatky, zľavy a darčekové poukážky

Špeciálne prípady:

  • Príplatky typu dobierka alebo kurier je možné do objednávky zadať vo forme textovej položky. Podstatné je, aby bola v textovej položke vyplnená cena, DPH, mj a názov. Množstvo v tomto prípade treba nastaviť na 1. Cena sa nastavuje ako kladné číslo.
  • Pre poskytnutie zľavy na celkovú objednávku treba do objednávky zadať vo forme textovej položky. Podstatné je, aby bola v textovej položke vyplnená cena, DPH, mj a názov. Množstvo v tomto prípade treba nastaviť na 1. Cena sa nastavuje ako záporné číslo.
  • Darčekové poukážky treba do objednávky zadať vo forme textovej položky. Podstatné je, aby bola v textovej položke vyplnená cena, DPH, mj a názov. Množstvo v tomto prípade treba nastaviť na 1. Cena sa nastavuje ako záporné číslo.
  • Adresa dodania sa vyplní ako špeciálny parameter dodanie. Toto vyžaduje Optivus v. 5.24.0.x, aby to fungovalo (momentálne ešte nie je vydaný). Vyplnia sa štyri parametre.
    • Prvý parameter je textový popis a môže sa nastaviť ako reťazec Adresa dodania.
    • Druhý parameter je meno osoby alebo názov cieľovej firmy. Ak je to osoba vo firme, tak treba dať do jedného reťazca aj osobu aj firmu.
    • Tretí parameter je ulica.
    • Štvrtý parameter je PSČ a mesto.

GET /interface/[db]/eshop/v1/objednavky/stav

Zistenie stavu konkrétnej objednávky.

  • Status: implementované
  • Bearer: áno

Zmena stavu objednávky

Zmena stavu konkrétnej objednávky.

  • URL: POST /interface/{db}/eshop/v1/objednavky/setstav
  • Status: implementované (2.7.1)
  • Bearer: áno

Parametre:

  • id - ID objednávky.
  • id_stav - Nový stav. Stav musí pochádzať z číselníka stavov pre objednavky.

GET /interface/[db]/eshop/v1/objednavky/stavy

Získanie číselníka stavov.

  • Status: implementované
  • Bearer: áno

GET /interface/[db]/eshop/v1/objednavky/dokumenty

Získanie zoznamu dokumentov k objednávke. Obvykle to bude iba faktúra.

  • Status: implementované
  • Bearer: áno

Stiahnutie súboru k objednávke

Získanie konkrétneho súboru k objednávke.

  • URL: GET /interface/{db}/eshop/v1/objednavky/dokumenty/subor
  • Status: implementované
  • Bearer: áno

Ako sa vytvorí faktúra k objednávke

Faktúra je jeden z možných druhov dokumentov. Vytvorí sa nasledovným postupom.

Prvým krokom je vytvorenie objednávky cez API v zozname objednávok v Optivuse. To sa robí funkciou Nová objednávka. Po vytvorení objednávky si ju užívateľ v Optivuse nájde a vytvorí z nej faktúru. Aby bolo možné teraz túto faktúru preniesť ako dokument do API, musí sa daná faktúra vytlačiť. Nie je potrebné ju fyzicky tlačiť, ale potrebujete si zobraziť dialóg na tlač faktúry. Na ňom sa nachádza tlačidlo ESH Fakt.... Pomocou tlačidla môžete vložiť report faktúry k objednávke, ktorá je na danú faktúru napojená.

Dialóg reportu s tlačidlom

Optivus si overí, či môže do PDF vygenerovať aktuálny report a či ho má vložiť k objednávke.

Kontrolná otázka

Potom si môžete skontrolovať, či v detailoch objednávky vidíte daný dokument.

Kontrolná otázka

Príklad získania dokumentu

V tomto postupe je popísané, ako sa dostať ku konkrétnemu súboru s faktúrou, ktorá je vygenerovaná k objednávke. Postupuje sa v nasledovných bodoch.

  • .../objednavky/zoznam - Získa sa zoznam objednávok.
  • .../objednavky/dokumenty - Získa sa zoznam dokumentov k objednavke.
  • .../objednavky/dokumenty/subor - Získa sa konkrétny súbor faktúry k objednávke.

Zoznam objednávok

Request.

https://remote-server/interface/ostra/eshop/v1/objednavky/zoznam?limit=100

Response. Tu to vrátilo jednu objednávku. Podstatná je položka objednavka_id, ktorá má hodnotu 69607.

{
    "items": [
        {
            "Row#": "1",
            "cena": 6.16,
            "cena_dph": 1.03,
            "cena_zaklad": 5.13,
            "cislo": "OP2018/07065",
            "datum": "2018-12-19T10:35:46.000Z",
            "datum_vybavenia": "2018-12-19T00:00:00.000Z",
            "firma_id": 7463,
            "id_stav": 3,
            "objednavka_id": 69607,
            "objednavka_orig": "",
            "osoba_id": 11035,
            "vybavena": true,
            "zrusena": false
        }
    ],
    "paging": {
        "limit": 333,
        "maximum": 1,
        "offset": 0
    }
}

Zoznam dokumentov k objednavke

Request.

https://remote-server/interface/ostra/eshop/v1/objednavky/dokumenty?objednavka_id=69607

Response. Tu to vrátilo zoznam dokumentov. Obvykle bude iba jeden dokument, ktorým je faktúra. V tejto ukážke sú to tri dokumenty. Nemusíme skúmať, prečo všetky tri dokumenty obsahujú podľa názvu ten istý dokument. Pravdepodobne to užívateľ v Optivuse tak urobil, pravdepodobne z neznalosti, lebo program ho určite upozornil, že už tam jeden dokument má urobený. Podstatná je položka id_dokument, ktorá má hodnotu 1, 2 alebo 3.

{
    "items": [
        {
            "Row#": "1",
            "crc": -195060123,
            "datum": "2018-12-19T11:28:42.577Z",
            "filename": "FV2018_02779.pdf",
            "id_dokument": 1,
            "objednavka_id": 69607,
            "velkost": 38798,
            "version": "265230890"
        },
        {
            "Row#": "2",
            "crc": 1798742948,
            "datum": "2018-12-19T11:29:49.243Z",
            "filename": "FV2018_02779.pdf",
            "id_dokument": 2,
            "objednavka_id": 69607,
            "velkost": 38798,
            "version": "265241240"
        },
        {
            "Row#": "3",
            "crc": 221535193,
            "datum": "2018-12-19T11:40:31.347Z",
            "filename": "FV2018_02779.pdf",
            "id_dokument": 3,
            "objednavka_id": 69607,
            "velkost": 38798,
            "version": "265303421"
        }
    ],
    "paging": {
        "limit": 100,
        "maximum": 3,
        "offset": 0
    }
}

Konkrétny súbor faktúry k objednávke

Nasleduje záverečný krok, ktorý dodá obsah súboru.

Request.

https://remote-server/interface/ostra/eshop/v1/objednavky/dokumenty/subor?id=1

Response. Tu to vrátilo konkrétny subor.

GET /interface/ostra/eshop/v1/objednavky/dokumenty/subor?id=1 HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Bearer sem daj bearer autentifikáciu
Connection: keep-alive
Host: remote-server
User-Agent: HTTPie/0.9.9

HTTP/1.1 200 OK
Connection: keep-alive
Content-Disposition: inline; filename="FV2018_02779.pdf"
Content-Length: 38798
Content-Type: application/pdf
Date: Wed, 19 Dec 2018 11:27:07 GMT
X-Powered-By: Express

+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+