Dokumentácia API - Objednávky

Základné informácie

Základné informácie k API, autentizácii, stavovým kódom, HTTP metódam, dátovým typom a ďalšie nájdete na API v2 základné informácie

Vytvorenie objednávky

Systém počas importu objednávok cez API porovnáva zákaznícke údaje v e-shope s tými v objednávke. Keď sa nájde zhodný zákazník s e-mailom, potom je priradený k danej objednávke.

Požiadavka

• URI: /api/v2/orders
• HTTP metóda: POST
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• telo:
  
  
• send_emails_yn (bool) - poslanie e-mailu, ktorý je naviazaný na stav objednávky, východisková hodnota je true
• send_sms_yn (bool) - poslanie SMS, ktorá je naviazaná na stav objednávky, východisková hodnota je true (SMS služba nie je štandardne aktívna, viac nájdete v Nastavení SMS)
• orders (array) - pole objektov s objednávkami
• external_order_number (string) - číslo objednávky z externého systému
• language_id (language) - jazyk objednávky, jazyk musí byť vytvorený v administrácii e-shopu
• prices_with_vat_yn (bool) - príznak, ak sú ceny s DPH, pokiaľ nie je zadaný berie sa podľa nastavenia z administrácie
• status (string) - názov stavu objednávky z administrácie (východiskový stav pri novej objednávke je Prijatá), zoznam stavov sa dá zistiť pomocou metódy GET, viac v sekcii Stavy objednávky
• paid_date (date) - dátum zaplatenia objednávky
• tracking_code (string) - trackovací kód pre dopravu
• resolved_yn (bool) - príznak pre vyriešenú objednávku
• internal_note (string) - interná poznámka
• variable_symbol (string) - variabilný symbol (maximálna dĺžka 10 znakov, len číslice). Pokiaľ nie je uvedené, generuje sa systémom z čísla obchodného prípadu. Možné hodnoty sú:
• case - doplní sa automaticky variabilný symbol z čísla obchodného prípadu
• order - doplní sa automaticky variabilný symbol z čísla objednávky
• variabilný symbol (maximálna dĺžka 10 znakov, len číslice) - doplní sa vlastná hodnota
• creation_time (date) - čas vytvorenia objednávky
• customer (object) - zákazník
• email (email) - e-mail zákazníka
• phone (string) - telefón
• firstname_invoice (string) - fakturačné meno
• surname_invoice (string) - fakturačné priezvisko
• street_invoice (string) - fakturačná ulica a číslo
• city_invoice (string) - fakturačné mesto
• state_invoice (string) - fakturačný okres
• zip_invoice (string) - fakturačné PSČ
• country_id_invoice (country) - fakturačná krajina
• postal_yn (bool) - príznak doručovacej adresy, pokiaľ posielate doručovacia adresa musí mať hodnotu true
• firstname_postal (string) - doručovacie meno
• surname_postal (string) - doručovacie priezvisko
• street_postal (string) - doručovacia ulica a číslo
• city_postal (string) - doručovacie mesto
• state_postal (string) - doručovací okres
• zip_postal (string) - doručovacie PSČ
• country_id_postal (country) - doručovacia krajina
• company_postal (string) - doručovací názov firmy
• company_yn (bool) - príznak, či je zákazník firma
• company (string) - názov firmy, povinné pokiaľ je firma
• ico (string) - IČO
• dic (string) - DIČ
• vat_payer_yn (bool) - príznak, ak je firma platca DPH
• pricelist_name (string) - názov cenníka
• pricelist_percent (int) - percentá zľavy cenníka (len informatívne, s percentami sa nikde nepočíta)
• customer_note (string) - poznámka zákazníka
• products (array) - pole objektov s produktmi
• code (string) - kód produktu
• code_supplier (string) - kód dodávateľa
• ean (string) - EAN produktu
• title (string) - názov produktu
• quantity (float) - počet kusov
• unit (string) - jednotka
• price_per_unit (float) - cena za jednu jednotku produktu
• vat (float) - hodnota DPH v %
• buy_price (float) - nákupná cena
• recycling_fee (float) - recyklačný poplatok
• weight (int) - váha jednej jednotky produktu v gramoch
• invoice_info (string) - poznámka k produktu, ktorá sa prepisuje do faktúry
• parameters (array) - pole objektov s parametrami produktu
• name (string) - názov parametra
• value (string) - hodnota parametra
• shipment (object) - doprava
• code (string) - kód dopravy, páruje sa s kódom dopravy (vo vlastných poliach) v administrácii
• name (string) - názov dopravy
• price (float) - cena dopravy
• vat (float) - hodnota DPH v %
• affiliate_id (string) - ID pobočky dopravy
• payment (object) - platba
• code (string) - kód platby, páruje sa s kódom platby (vo vlastných poliach) v administrácii
• name (string) - názov platby
• price (float) - cena platby
• vat (float) - hodnota DPH v %
• eet_yn (bool) - príznak, či sa má poslať objednávka do EET
• metas (array) - pole objektov s vlastnými poľami
• key (string) - kľúč vlastného poľa
• value (string) - hodnota vlastného poľa
• invoice (object) - faktúra, možnosť vygenerovania faktúry
• generate_yn (bool) - príznak o vygenerovaní faktúry, pokiaľ bude FALSE, nevygeneruje sa vôbec, ani v prípade, že je zapnuté automatické generovanie faktúry
• expiration_date (date) - dátum splatnosti, pokiaľ nie je vyplnené, berie sa aktuálny dátum + nastavená hodnota z administrácie
• date_of_issuance (date) - dátum vystavenia
• date_of_vat_revenue_recognition (date) - dátum zdaniteľného plnenia

príklad požiadavky

  POST /api/v2/orders HTTP/1.1

  Content-Type: application/json

  Authorization: Basic dGVzdDp0ZXN0

 

  

         

Odpoveď

• telo:
• orders (array) - pole objektov s objednávkami
• external_order_number (string) - externé číslo objednávky
• order_number (string) - číslo objednávky, pokiaľ sa objednávka nevytvorí, vracia null
• order_url (string) - URL adresa, kde sa nachádza objednávka
• created_yn (bool) - príznak, či sa objednávka vytvorila
• messages (array) - pole objektov chybových správ a upozornení pri spracovaní objednávky
• object (string) - názov objektu (časť JSON), ktorého sa správa týka
• property (string) - hodnota, ktorej sa správa týka
• message (string) - text správy

príklad odpovede (HTTP 200 OK)

  HTTP/1.1 200 OK

  Content-Type: application/json

Aktualizácia objednávok

Požiadavka

• URI: /api/v2/orders
• HTTP metóda: PUT
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• telo:
  
  
• objednávky sa párujú podľa čísla order_number. Pri zmene stavu sa posielajú e-maily (pokiaľ je nejaký e-mail pri stave objednávky nastavený). V odpovedi sú všetky objednávky, ktoré boli v požiadavke.
• send_emails_yn (bool) - poslanie e-mailu pri zmene stavu (pokiaľ je nejaký e-mail nastavený), východisková hodnota je true
• orders (array) - pole objektov s objednávkami
• order_number (string) - číslo objednávky
• status (string) - názov stavu objednávky, stav musí byť vytvorený v administrácii, zoznam stavov sa dá zistiť pomocou metódy GET /api/v2/orders/states
• status_id (int) - ID stavu objednávky, stav musí byť vytvorený v administrácii, zoznam stavov sa dá zistiť pomocou metódy GET /api/v2/orders/states
• paid_date (date) - dátum zaplatenia objednávky
• tracking_code (string) - trackovací kód pre dopravu
• resolved_yn (bool) - príznak pre vyriešenú objednávku
• internal_note (string) - interná poznámka
• metas (array) - pole objektov s vlastnými poľami
• key (string) - kľúč vlastného poľa
• value (string) - hodnota vlastného poľa
• invoice (object) - faktúra, možnosť vygenerovania faktúry
• generate_yn (bool) - príznak o vygenerovaní faktúry, pokiaľ bude FALSE, nevygeneruje sa vôbec, ani v prípade že je zapnuté automatické generovanie faktúry
• expiration_date (date) - dátum splatnosti, pokiaľ nie je vyplnený, berie sa aktuálny dátum + nastavená hodnota z administrácie
• date_of_issuance (date) - dátum vystavenia
• date_of_vat_revenue_recognition (date) - dátum zdaniteľného plnenia

príklad požiadavky

  PUT /api/v2/orders HTTP/1.1

  Content-Type: application/json

  Authorization: Basic dGVzdDp0ZXN0

       

Odpoveď

• telo:
• orders (array) - pole objektov s objednávkami
• order_number (string) - číslo objednávky
• order_url (string) - URL adresa, kde sa nachádza objednávka
• updated_yn (bool) - príznak, či sa objednávka aktualizovala
• messages (array) - pole objektov chybových správ a upozornení pri spracovaní objednávky
• object (string) - názov objektu (časť JSON), ktorého sa správa týka
• property (string) - hodnota, ktorej sa správa týka
• message (string) - text správy

príklad odpovede (HTTP 200 OK)

  HTTP/1.1 200 OK

  Content-Type: application/json

  

Zmazanie objednávok

• URI: /api/v2/orders/?order_number={order_number}&order_numbers={order_numbers}
• HTTP metóda: DELETE
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• parametre (musí byť definovaný aspoň jeden parameter):
• order_number (string) - číslo objednávky
• order_numbers (string) - čísla objednávok oddelené bodkočiarkou ;

Odpoveď

• telo:
• orders (array) - pole objektov s objednávkami
• order_number (string) - číslo objednávky
• deleted_yn (bool) - príznak, či je objednávka zmazaná
• messages (array) - pole objektov chybových správ a upozornení pri spracovaní objednávky
• object (string) - názov objektu (časť JSON), ktorého sa správa týka
• property (string) - hodnota, ktorej sa správa týka
• message (string) - text správy

príklad odpovede (HTTP 200 OK)

  HTTP/1.1 200 OK

  Content-Type: application/json

Zoznam objednávok

• URI: /api/v2/orders/{order_number} ?order_numbers={order_numbers} &creation_time_from={creation_time_from} &creation_time_to={creation_time_to} &last_update_time_from={last_update_time_from} &page={page} &status={status} &paid_yn={paid_yn}
• HTTP metóda: GET
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• parametre - slúžia pre filtrovanie výstupu:
• order_number (string) - číslo objednávky
• order_numbers (string) - čísla objednávok oddelené bodkočiarkou ;
• creation_time_from (date) - vráti objednávky vytvorené od tohto dátumu
• creation_time_to (date) - vráti objednávky vytvorené do tohto dátumu vrátane
• last_update_time_from (date) - vráti objednávky zmenené od tohto dátumu
• paid_yn (bool) - pokiaľ je 1, vráti zaplatené objednávky
• status (string) - stav objednávky, pokiaľ bude prázdny, vráti objednávky kde nie je žiadny stav
• status_id (int) - ID stavu objednávky
• language (language) - jazyková mutácia, na ktorej objednávka vznikla
• email (string) - e-mail zákazníka objednávky
• payment_type (string) - typ platby, možné hodnoty sú: cash - v hotovosti cashOnDelivery - dobierka command - prevodom moneybookers - skrill paypal - PayPal payu - PayU homecredit - Homecredit tatrapay - TatraPay tatracardpay - CardPay comgate - ComGate cetelem - Hello bank gopay - GoPay fio - Fio gpwebpay - GP webpay cofidis - Cofidis essox - Essox twisto - Twisto cashOnCashRegister - V hotovosti na pokladni cardOnCashRegister - Kartou na pokladni thepay - ThePay custom - Vlastné
• shipment_type (string) - typ dopravy, možné hodnoty sú:
• ceskaPosta - Česká pošta
• slovenskaPosta - Slovenská pošta
• ulozenka - Uloženka
• zasilkovna - Zásielkovňa
• dpd - DPD
• ppl - PPL
• gls - GLS
• custom - Vlastná doprava
• page (int) - stránka, pokiaľ nie je definované, vracia vždy stranu 1
• order_by (string) - radenie, možné hodnoty sú:
• creation_time - zoradí podľa času vytvorenia
• last_update_time - zoradí podľa času zmeny
• order_dir (string) - smer radenia, možné hodnoty sú:
• asc - vzostupne
• desc - zostupne

Odpoveď

Zoznam objednávok je dostupný po jednotlivých stranách, výstup je obmedzený na 100 položiek na stránku.

• telo:
  
  
• current_page (int) - aktuálna strana
• current_page_items (int) - počet položiek na aktuálnej strane
• number_of_pages (int) - celkový počet strán
• number_of_items (int) - celkový počet položiek
• orders (array) - pole objektov s objednávkami
• order_number (string) - číslo objednávky
• case_number (string) - číslo obchodného prípadu
• external_order_number (string) - číslo objednávky z externého systému
• language_id (language) - jazyk objednávky
• currency_id (currency) - mena objednávky
• default_currency_rate (currency) - kurz pre východiskovú menu. Prepočet ceny do východiskovej meny vykonáte ako: cena * (1 / default_currency_rate)
• prices_with_vat_yn (bool) - príznak, či sú ceny s DPH
• status_id (int) - ID stavu objednávky
• status (string) - názov stavu objednávky
• paid_date (date) - dátum zaplatenia objednávky
• tracking_code (string) - trackovací kód pre dopravu
• resolved_yn (bool) - príznak pre vyriešenú objednávku
• oss_yn (bool) - príznak, či bola objednávka vytvorená v režime OSS
• internal_note (string) - interná poznámka
• last_update_time (date) - dátum aktualizácie
• creation_time (date) - dátum vytvorenia
• variable_symbol (string) - variabilný symbol
• total_weight (int) - celková váha objednávky
• order_total (float) - celková cena s DPH
• order_total_before_round (float) - celková cena s DPH pred zaokrúhlením
• order_total_rest (float) - hodnota zaokrúhlenia celkovej ceny s DPH
• invoice_number (string) - číslo faktúry
• origin (string) - pôvod vytvorenia objednávky, možné hodnoty sú:
• admin - vytvorenie ručne v administrácii
• frontend - vytvorenie zákazníkom na e-shope
• api - vytvorenie poslaním údajov cez API
• cash-register - vytvorenie cez pokladňu
• admin_url (string) - URL do detailu objednávky v administrácii
• customer (object) - zákazník
• email (email) - e-mail zákazníka
• phone (string) - telefón
• code (string) - zákaznícke číslo
• firstname_invoice (string) - fakturačné meno
• surname_invoice (string) - fakturačné priezvisko
• street_invoice (string) - fakturačná ulica a číslo
• city_invoice (string) - fakturačné mesto
• state_invoice (string) - fakturačný okres
• zip_invoice (string) - fakturačné PSČ
• country_id_invoice (country) - fakturačná krajina
• postal_yn (bool) - príznak doručovacej adresy
• firstname_postal (string) - doručovacie meno
• surname_postal (string) - doručovacie priezvisko
• street_postal (string) - doručovacia ulica a číslo
• city_postal (string) - doručovacie mesto
• state_postal (string) - doručovací okres
• zip_postal (string) - doručovacie PSČ
• country_id_postal (country) - doručovacia krajina
• company_postal (string) - doručovací názov firmy
• company_yn (bool) - príznak, či je zákazník firma
• company (string) - názov firmy
• ico (string) - IČO
• dic (string) - DIČ
• vat_payer_yn (bool) - príznak, či je firma platca DPH
• customer_note (string) - poznámka zákazníka
• agreements (array) - pole objektov so súhlasmi
• name (string) - názov súhlasu
• valid_to (date) - čas dokedy je súhlas platný
• status (bool) - stav súhlasu
• products (array) - pole objektov s produktmi
• product_id (int) - ID produktu z databázy (len orientačne, pre párovanie produktov slúži code)
• option_set_id (int) - ID variantu z databázy (len orientačne, pre párovanie produktov slúži code). Bude vyplnené len vtedy, pokiaľ je položka variant produktu.
• code (string) - kód produktu alebo variantu produktu
• code_supplier (string) - kód dodávateľa produktu alebo variantu produktu
• ean (string) - EAN produktu alebo variantu produktu
• title (string) - názov produktu
• quantity (float) - počet jednotiek
• unit (string) - jednotka
• length (string) - množstvo
• length_unit (string) - jednotka množstva
• price_per_unit (float) - cena za jednu jednotku produktu (cena je s alebo bez DPH podľa príznaku prices_with_vat_yn)
• price (float) - celková cena za produkt (cena je s alebo bez DPH podľa príznaku prices_with_vat_yn)
• price_with_vat (float) - celková cena za produkt s DPH
• price_without_vat (float) - celková cena za produkt bez DPH
• vat (float) - hodnota DPH v %
• buy_price (float) - nákupná cena za jednu jednotku produktu
• weight (int) - váha jednej jednotky produktu v gramoch
• availability (string) - dostupnosť produktu vo chvíli, kedy bol objednaný
• invoice_info (string) - poznámka k produktu, ktorá sa prepisuje do faktúry
• parameters (array) - pole objektov s parametrami produktu
• name (string) - názov konfigurácie
• value (string) - hodnota parametra
• configurations (array) - pole objektov s konfiguráciami produktu
• name (string) - názov parametra
• values (array) - pole hodnôt
• value (string) - hodnota
• operation (string) - operácia (+, -)
• cena (float) - cena konfigurácie (je už pripočítaná k cene produktu)
• discount_voucher (object) - zľavový kupón
• code (string) - kód zľavového kupónu
• type (string) - typ zľavy, možné hodnoty sú percent alebo price
• amount (float) - výška zľavy, pokiaľ je typ zľavy percent sú to percentá, pokiaľ price je to cena
• discounts (array) - pole objektov so zľavami rozpočítanými pre jednotlivé hladiny DPH
• price (float) - hodnota zľavy
• vat (float) - DPH v %
• quantity_discount (object) - množstevná zľava
• type (string) - typ zľavy, možné hodnoty sú percent alebo price
• amount (float) - výška zľavy, pokiaľ je typ zľavy percent sú to percentá, pokiaľ price je to cena
• discounts (array) - pole objektov so zľavami rozpočítanými pre jednotlivé hladiny DPH
• price (float) - hodnota zľavy
• vat (float) - DPH v %
• loyalty_points (object) - vernostné body
• one_point_for (float) - hodnota (cena) jedného bodu
• amount (float) - výška zľavy
• discounts (array) - pole objektov so zľavami rozpočítanými pre jednotlivé hladiny DPH
• price (float) - hodnota zľavy
• vat (float) - DPH v %
• shipment (object) - doprava
• code (string) - kód dopravy, páruje sa s kódom dopravy (vo vlastných poliach) v administrácii
• name (string) - názov dopravy
• price (float) - cena dopravy
• vat (float) - hodnota DPH v %
• affiliate_id (string) - ID pobočky dopravy
• payment (object) - platba
• code (string) - kód platby, páruje sa s kódom platby (vo vlastných poliach) v administrácii
• name (string) - názov platby
• price (float) - cena platby
• vat (float) - hodnota DPH v %
• eet_yn (bool) - príznak, či sa má poslať objednávka do EET
• metas (array) - pole objektov s vlastnými poľami
• key (string) - kľúč vlastného poľa
• type (string) - typ vlastného poľa (hodnoty môžu byť: radio, checkbox, input, date, e-mail, number, select, multiselect, textarea, formatted)
• value (string) - hodnota vlastného poľa, v prípade kedy je hodnota vlastného poľa spoločná pre všetky jazyky
• values (array) - pole objektov s hodnotami, v prípade kedy nie je hodnota vlastného poľa spoločná pre všetky jazyky
• language (language) - špecifikácie jazykovej mutácie
• value (string) - hodnota

príklad odpovede (HTTP 200 OK)

PDF objednávka

Vracia dokument objednávky vo formáte PDF

• URI: /api/v2/orders/{order_number}/pdf
• HTTP metóda: GET
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• parametre:
  
  
• order_number (string) - číslo objednávky

hlavičky odpovede (HTTP 200 OK)

  HTTP/1.1 200 OK

  Content-Type: application/pdf

• 
  
  

Pridanie záznamu do histórie objednávky

Pridá záznam do histórie objednávky. Jedna požiadavka znamená pridanie jedného záznamu do histórie. Slúži hlavne pre systémy tretích strán, ktoré chcú informovať administrátora e-shopu o tom, že prebehla nejaká udalosť. Čas udalosti nemožno upravovať, pokiaľ chcete môžete si poslať čas v údajoch udalosti.

• URI: /api/v2/orders/{order_number}/history
• HTTP metóda: POST
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• parametre:
  
  
• order_number (string) - číslo objednávky
• telo:
  
  
• data (array) - pole objektov údajov histórie
• name (string) - názov, oreže sa na dĺžku max. 50 znakov a odstránia sa HTML značky
• value (string) - hodnota, oreže sa na dĺžku max. 500 znakov a odstránia sa HTML značky

História objednávky

Vracia zoznam udalostí z histórie objednávky. Údaje histórie môžu obsahovať HTML značky.

• URI: /api/v2/orders/{order_number}/history
• HTTP metóda: GET
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• parametre:
• order_number (string) - číslo objednávky

Odpoveď

• telo:
• number_of_items (int) - počet položiek histórie
• history (array) - pole objektov s udalosťami histórie
• event (string) - názov udalosti
• user_name (string) - meno užívateľa, ktorý udalosť vykonal
• changes (object) - pole objektov so zmenami
• name (string) - názov zmeny
• before (string) - hodnota pred zmenou
• after (string) - hodnota po zmene
• admin_yn (bool) - príznak či udalosť pochádza z e-shopu, alebo z administrácie. Pokiaľ pochádza udalosť z API, bude true
• data (array) - pole objektov s údajmi
• name (string) - názov
• value (string) - hodnota
• creation_time (datetime) - čas udalosti

Stavy objednávky

Vracia zoznam stavov objednávok. V požiadavke pre aktualizáciu alebo vytvorenie objednávky sa dá použiť názov stavu v akomkoľvek jazyku.

• URI: /api/v2/orders/states
• HTTP metóda: GET
• hlavičky:
• Authorization: Basic dGVzdDp0ZXN0
• Content-Type: application/json
• telo:
• states (array) - pole objektov so stavmi
• id (int) - ID stavu
• type (string) - typ stavu, pokiaľ je hodnota null, tak ide o vlastný stav, inak to sú systémové stavy:
• Received - Prijatá
• Canceled - Storno
• PaymentSuccessful - Platba úspešná
• PaymentFailed - Platba zlyhala
• PaymentCanceled - Platba zrušená
• PaymentInProcess - Platba prebieha
• Unresolved - Nedoriešená
• color (string) - farba pre odlíšenie stavu v HTML HEX formáte
• names (object) - názvy stavu objednávky v jednotlivých jazykoch, kľúč v objekte je kód jazyka podľa ISO 8601 a hodnota je názov stavu napr. { "cz": "Prijatá" }

príklad odpovede (HTTP 200 OK)