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)