Tento článek byl vytvořen před více jak 2 roky a může obsahovat zastaralé informace.
Objednávky
- Základní informace
- Vytvoření objednávky
- Aktualizace objednávky
- Smazání objednávek
- Seznam objednávek
- HTML objednávka
- Stavy objednávky
Základní informace
Základní informace k API, autentizaci, stavové kódy, HTTP metody, datové typy a další najdete na API v2 základní informace
Vytvoření objednávky
Požadavek
-
URI: /api/v2/orders
-
HTTP metoda: POST
-
hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
-
tělo:
send_emails_yn
(bool) - poslání emailu který je navázán na stav objednávky, výchozí hodnota jetrue
send_sms_yn
(bool) - poslání SMS která je navázána na stav objednávky, výchozí hodnota jetrue
(SMS služba není standardně aktivní, více najdete v Nastavení SMS)orders
(array) - pole objektů s objednávkamiexternal_order_number
(string) - číslo objednávky z externího systémulanguage_id
(language) - jazyk objednávky, jazyk musí být vytvořen v administraci eshopuprices_with_vat_yn
(bool) - příznak jestli jsou ceny s DPH, pokud není zadáno bere se podle nastavení z administracestatus
(string) - název stavu objednávky z administrace (výchozí stav u nové objednávky je Přijatá), seznam stavů se dá zjistit pomocí metody GET, více v sekci Stavy objednávkypaid_date
(date) - datum zaplacení objednávkytracking_code
(string) - trackovací kód pro dopravuresolved_yn
(bool) - příznak pro vyřešenou objednávkuinternal_note
(string) - interní poznámkavariable_symbol
(string) - variabilní symbol (maximální délka 10 znaků, jen z číslice), pokud není uvedeno generuje se systémem z čísla objednávkycustomer
(object) - zákazníkemail
(email) - email zákazníkaphone
(string) - telefonfirstname_invoice
(string) - fakturační jménosurname_invoice
(string) - fakturační příjmenístreet_invoice
(string) - fakturační ulice a číslocity_invoice
(string) - fakturační městostate_invoice
(string) - fakturační okreszip_invoice
(string) - fakturační PSČcountry_id_invoice
(country) - fakturační zeměpostal_yn
(bool) - příznak doručovací adresy, pokud posíláte doručovací adresu musí mít hodnotutrue
firstname_postal
(string) - doručovací jménosurname_postal
(string) - doručovací přijmenístreet_postal
(string) - doručovací ulice a číslocity_postal
(string) - doručovací městostate_postal
(string) - doručovací okreszip_postal
(string) - doručovací PSČcountry_id_postal
(country) - doručovací zeměcompany_postal
(string) - doručovací název firmycompany_yn
(bool) - příznak jestli je zákazník firmacompany
(string) - název firmy, povinné pokud je firmaico
(string) - IČOdic
(string) - DIČvat_payer_yn
(bool) - příznak jestli je firma plátce DPHpricelist_name
(string) - název ceníkupricelist_percent
(int) - procenta slevy ceníku (pouze informativní, s procenty se nikde nepočítá)customer_note
(string) - poznámka zákazníka
products
(array) - pole objektů s produktycode
(string) - kód produktutitle
(string) - název produktuquantity
(float) - počet kusůunit
(string) - jednotkaprice_per_unit
(float) - cena za jednu jednotku produktuvat
(float) - hodnota DPH v %weight
(int) - váha jedné jednotky produktu v gramechinvoice_info
(string) - poznámka k produktu která se propisuje do fakturyparameters
(array) - pole objektů s parametry produktuname
(string) - název parametruvalue
(string) - hodnota parametru
shipment
(object) - dopravacode
(string) - kód dopravy, páruje se s kódem dopravy (ve vlastních polích) v administraciname
(string) - název dopravyprice
(float) - cena dopravyvat
(float) - hodnota DPH v %affiliate_id
(string) - ID pobočky dopravy
payment
(object) - platbacode
(string) - kód platby, páruje se s kódem platby (ve vlastních polích) v administraciname
(string) - název platbyprice
(float) - cena platbyvat
(float) - hodnota DPH v %eet_yn
(bool) - příznak jestli je se má poslat objednávka do EET
metas
(array) - pole objektů s vlastními polikey
(string) - klíč vlastního polevalue
(string) - hodnota vlastního pole
-
příklad požadavku
POST /api/v2/orders HTTP/1.1 Content-Type: application/json Authorization: Basic dGVzdDp0ZXN0 { "send_emails_yn": true, "send_sms_yn": true, "orders": [ { "external_order_number": "", "language_id": "", "prices_with_vat_yn": "", "status": "", "paid_date": "", "tracking_code": "", "resolved_yn": "", "internal_note": "", "variable_symbol": "", "customer": { "email": "", "phone": "", "firstname_invoice": "", "surname_invoice": "", "street_invoice": "", "city_invoice": "", "state_invoice": "", "zip_invoice": "", "country_id_invoice": "", "postal_yn": "", "firstname_postal": "", "surname_postal": "", "street_postal": "", "city_postal": "", "state_postal": "", "zip_postal": "", "company_postal": "", "country_id_postal": "", "company_yn": "", "company": "", "ico": "", "dic": "", "vat_payer_yn": "", "customer_note": "" }, "products": [ { "code": "", "title": "", "quantity": "", "unit": "", "price_per_unit": "", "vat": "", "weight": "", "invoice_info": "", "parameters": [ { "name": "", "value": "" } ] } ], "shipment": { "code": "", "name": "", "price": "", "vat": "", "affiliate_id": "" }, "payment": { "code": "", "name": "", "price": "", "vat": "", "eet_yn": "" }, "metas": [ { "key": "", "value": "" } ] } ] }
Odpověd
- tělo:
orders
(array) - pole objektů s objednávkyexternal_order_number
(string) - externí číslo objednávkyorder_number
(string) - číslo objednávky, pokud se objednávka nevytvoří, vracínull
order_url
(string) - URL adresa kde se nachází objednávkacreated_yn
(bool) - příznak jestli se objednávka vytvořilamessages
(array) - pole objektů chybových zpráv a upozornění při zpracování objednávkyobject
(string) - název objektu (část JSONu) kterého se zpráva týkáproperty
(string) - hodnota které se zpráva týkámessage
(string) - text zprávy
-
příklad odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: application/json { "orders": [ { "order_number": "", "order_url": "", "created": "", "messages": [ { "object": "", "property": "", "message": "" } ] } ] }
Aktualizace objednávek
Požadavek
- URI: /api/v2/orders
- HTTP metoda: PUT
- hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
- tělo:
- objednávky se párují podle čísla
order_number
. Při změně stavu se posílají emaily (pokud je nějaký email u stavu objednávky nastaven). V odpovědi jsou všechny objednávky které byly v požadavku. send_emails_yn
(bool) - poslání emailu při změně stavu (pokud je nějaký email nastaven), výchozí hodnota jetrue
orders
(array) - pole objektů s objednávkamiorder_number
(string) - číslo objednávkystatus
(string) - název stavu objednávky, stav musí být vytvořen v administraci, seznam stavů se dá zjistit pomocí metody GET/api/v2/orders/states
paid_date
(date) - datum zaplacení objednávkytracking_code
(string) - trackovací kód pro dopravuresolved_yn
(bool) - příznak pro vyřešenou objednávkuinternal_note
(string) - interní poznámkametas
(array) - pole objektů s vlastními polikey
(string) - klíč vlastního polevalue
(string) - hodnota vlastního pole
- objednávky se párují podle čísla
-
příklad požadavku
PUT /api/v2/orders HTTP/1.1 Content-Type: application/json Authorization: Basic dGVzdDp0ZXN0 { "send_emails_yn": "", "orders": [ { "order_number": "", "status": "", "paid_date": "", "tracking_code": "", "resolved_yn": "", "internal_note": "", "metas": [ { "key": "", "value": "" } ] } ] }
Odpověď
- tělo:
orders
(array) - pole objektů s objednávkyorder_number
(string) - číslo objednávkyorder_url
(string) - URL adresa kde se nachází objednávkaupdated_yn
(bool) - příznak jestli se objednávka aktualizovalamessages
(array) - pole objektů chybových zpráv a upozornění při zpracování objednávkyobject
(string) - název objektu (část JSONu) kterého se zpráva týkáproperty
(string) - hodnota které se zpráva týkámessage
(string) - text zprávy
-
příklad odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: application/json { "orders": [ { "order_number": "", "order_url": "", "updated_yn": "", "messages": [ { "object": "", "property": "", "message": "" } ] } ] }
Smazání objednávek
- URI: /api/v2/orders/?order_number=
{order_number}
&order_numbers={order_numbers}
- HTTP metoda: DELETE
- hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
- parametry (musí být definovám alespoň jeden parametr):
order_number
(string) - číslo objednávkyorder_numbers
(string) - čísla objednávek oddělená středníkem;
Odpověď
- tělo:
orders
(array) - pole objektů s objednávkyorder_number
(string) - číslo objednávkydeleted_yn
(bool) - příznak jestli je objednávka smazanámessages
(array) - pole objektů chybových zpráv a upozornění při zpracování objednávkyobject
(string) - název objektu (část JSONu) kterého se zpráva týkáproperty
(string) - hodnota které se zpráva týkámessage
(string) - text zprávy
-
příklad odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: application/json { "orders": [ { "order_number": "", "deleted": "", "messages": [ { "object": "", "property": "", "message": "" } ] } ] }
Seznam objednávek
- URI: /api/v2/orders/
{order_number}
?order_numbers={order_numbers}
&creation_time_from={creation_time_from}
&last_update_time_from={last_update_time_from}
&page={page}
&status={status}
&paid_yn={paid_yn}
- HTTP metoda: GET
- hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
- parametry - slouží pro filtrování výstupu (musí být definovám alespoň jeden parametr, neplatí pro
page
):order_number
(string) - číslo objednávkyorder_numbers
(string) - čísla objednávek oddělená středníkem;
creation_time_from
(date) - vrátí objednávky vytvořené od tohoto datalast_update_time_from
(date) - vrátí objednávky změněné od tohoto datapaid_yn
(bool) - pokud je 1, vrátí zaplacené objednávkystatus
(string) - stav objednávky, pokud bude prázdný, vrátí objednávky kde není žádný stavlanguage
(language) - jazyková mutace na které objednávka vzniklaemail
(string) - email zákazníka objednávkypage
(int) - stránka, pokud není definováno, vrací vždy stranu 1order_by
(string) - řazení, možné hodnoty jsou:- creation_time - seřadí podle času vytvoření
- last_update_time - seřadí podle času změny
order_dir
(string) - směr řazení, možné hodnoty jsou:- asc - vzestupně
- desc - sestupně
Odpověď
Seznam objednávek je dostupný po jednotlivých stranách, výstup je omezen na 100 položek na stránku.
-
tělo:
current_page
(int) - aktuální stranacurrent_page_items
(int) - počet položek na aktuální straněnumber_of_pages
(int) - celkový počet strannumber_of_items
(int) - celkový počet položekorders
(array) - pole objektů s objednávkamiorder_number
(string) - číslo objednávkycase_number
(string) - číslo obchodního případuexternal_order_number
(string) - číslo objednávky z externího systémulanguage_id
(language) - jazyk objednávkycurrency_id
(currency) - měna objednávkydefault_currency_rate
(currency) - kurz pro výchozí měnu. Přepočet ceny do výchozí měny provedete jako: cena * (1 /default_currency_rate
)prices_with_vat_yn
(bool) - příznak jestli jsou ceny s DPHstatus
(string) - název stavu objednávkypaid_date
(date) - datum zaplacení objednávkytracking_code
(string) - trackovací kód pro dopravuresolved_yn
(bool) - příznak pro vyřešenou objednávkuinternal_note
(string) - interní poznámkalast_update_time
(date) - datum aktualizacecreation_time
(date) - datum vytvořenívariable_symbol
(string) - variabilní symboltotal_weight
(int) - celková váha objednávkyorder_total
(float) - celková cena s DPHinvoice_number
(string) - číslo fakturyadmin_url
(string) - URL do detailu objednávky v administracicustomer
(object) - zákazníkemail
(email) - email zákazníkaphone
(string) - telefonfirstname_invoice
(string) - fakturační jménosurname_invoice
(string) - fakturační příjmenístreet_invoice
(string) - fakturační ulice a číslocity_invoice
(string) - fakturační městostate_invoice
(string) - fakturační okreszip_invoice
(string) - fakturační PSČcountry_id_invoice
(country) - fakturační zeměpostal_yn
(bool) - příznak doručovací adresyfirstname_postal
(string) - doručovací jménosurname_postal
(string) - doručovací přijmenístreet_postal
(string) - doručovací ulice a číslocity_postal
(string) - doručovací městostate_postal
(string) - doručovací okreszip_postal
(string) - doručovací PSČcountry_id_postal
(country) - doručovací zeměcompany_postal
(string) - doručovací název firmycompany_yn
(bool) - příznak jestli je zákazník firmacompany
(string) - název firmyico
(string) - IČOdic
(string) - DIČvat_payer_yn
(bool) - příznak jestli je firma plátce DPHcustomer_note
(string) - poznámka zákazníkaagreements
(array) - pole objektů se souhlasyname
(string) - název souhlasuvalid_to
(date) - čas do kdy je souhlas platnýstatus
(bool) - stav souhlasu
products
(array) - pole objektů s produktyproduct_id
(int) - ID produktu z databáze (pouze orientačně, pro párování produktů sloužícode
)option_set_id
(int) - ID varianty z databáze (pouze orientačně, pro párování produktů sloužícode
). Bude vyplněno pouze tehdy, pokud je položka varianta produktu.code
(string) - kód produktu nebo varianty produktutitle
(string) - název produktuquantity
(float) - počet jednotekunit
(string) - jednotkaprice_per_unit
(float) - cena za jeden kus produktuprice
(float) - celková cena za produktvat
(float) - hodnota DPH v %weight
(int) - váha jedné jednotky produktu v gramechavailability
(string) - dostupnost produktu ve chvíli kdy byl objednáninvoice_info
(string) - poznámka k produktu která se propisuje do fakturyparameters
(array) - pole objektů s parametry produktuname
(string) - název parametruvalue
(string) - hodnota parametru
discount_voucher
(object) - slevový kupóncode
(string) - kód slevového kuponutype
(string) - typ slevy, možné hodnoty jsoupercent
neboprice
amount
(float) - výše slevy, pokud je typ slevypercent
jsou to procenta, pokudprice
je to cenadiscounts
(array) - pole objektů se slevami rozpočínanými pro jednotliv hladiny DPHprice
(float) - hodnota slevyvat
(float) - DPH v %
quantity_discount
(object) - množstevní slevatype
(string) - typ slevy, možné hodnoty jsoupercent
neboprice
amount
(float) - výše slevy, pokud je typ slevypercent
jsou to procenta, pokudprice
je to cenadiscounts
(array) - pole objektů se slevami rozpočínanými pro jednotliv hladiny DPHprice
(float) - hodnota slevyvat
(float) - DPH v %
loyalty_points
(object) - věrnostní bodyone_point_for
(float) - hodnota jednoho boduamount
(float) - výše slevy, pokud je typ slevypercent
jsou to procenta, pokudprice
je to cenadiscounts
(array) - pole objektů se slevami rozpočínanými pro jednotliv hladiny DPHprice
(float) - hodnota slevyvat
(float) - DPH v %
shipment
(object) - dopravacode
(string) - kód dopravy, páruje se s kódem dopravy (ve vlastních polích) v administraciname
(string) - název dopravyprice
(float) - cena dopravyvat
(float) - hodnota DPH v %affiliate_id
(string) - ID pobočky dopravy
payment
(object) - platbacode
(string) - kód platby, páruje se s kódem platby (ve vlastních polích) v administraciname
(string) - název platbyprice
(float) - cena platbyvat
(float) - hodnota DPH v %eet_yn
(bool) - příznak jestli je se má poslat objednávka do EET
metas
(array) - pole objektů s vlastními polikey
(string) - klíč vlastního poletype
(string) - typ vlastního pole (hodnoty mohou být: radio, checkbox, input, date, email, number, select, multiselect, textarea, formatted)value
(string) - hodnota vlastního pole, v případě kdy je hodnota vlastního pole společná pro všechny jazykyvalues
(array) - pole objektů s hodnotami, v případě kdy není hodnota vlastního pole společná pro všechny jazykylanguage
(language) - specifikace jazykové mutacevalue
(string) - hodnota
-
příklad odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: application/json { "current_page": "", "current_page_items": "", "number_of_pages": "", "number_of_items": "", "orders": [ { "order_number": "", "external_order_number": "", "language_id": "", "prices_with_vat_yn": "", "status": "", "paid_date": "", "tracking_code": "", "resolved_yn": "", "internal_note": "", "last_update_time": "", "creation_time": "", "variable_symbol": "", "total_weight": "", "order_total": "", "invoice_number": "", "customer": { "email": "", "phone": "", "firstname_invoice": "", "surname_invoice": "", "street_invoice": "", "city_invoice": "", "state_invoice": "", "zip_invoice": "", "country_id_invoice": "", "postal_yn": "", "firstname_postal": "", "surname_postal": "", "street_postal": "", "city_postal": "", "state_postal": "", "zip_postal": "", "country_id_postal": "", "company_postal": "", "company_yn": "", "company": "", "ico": "", "dic": "", "vat_payer_yn": "", "customer_note": "", "agreements": [ { "name": "", "valid_to": "", "status": "" } ], }, "products": [ { "product_id": "", "option_set_id": "", "code": "", "title": "", "unit": "", "quantity": "", "price_per_unit": "", "price": "", "vat": "", "weight": "", "invoice_info": "", "parameters": [ { "name": "", "value": "" } ] } ], "discount_voucher": { "code": "", "type": "", "amount": "", "discounts": [ { "vat": "", "price": "" } ] }, "quantity_discount": { "type": "", "amount": "", "discounts": [ { "vat": "", "price": "" } ] }, "loyalty_points": { "one_point_for": "", "amount": "", "discounts": [ { "vat": "", "price": "" } ] }, "shipment": { "name": "", "price": "", "vat": "", "affiliate_id": "" }, "payment": { "name": "", "price": "", "vat": "", "eet_yn": "" } } ] }
HTML objednávka
Vrací dokument objednávky ve formátu HTML
-
URI: /api/v2/orders/
{order_number}
/html -
HTTP metoda: GET
-
hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
-
parametry:
order_number
(string) - číslo objednávky
-
hlavičky odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: text/html
Stavy objednávky
Vrací seznam stavů objednávek. V požadavku pro aktualizaci nebo vytvoření objednávky se dá použít název stavu v jakémkoliv jazyce.
- URI: /api/v2/orders/states
- HTTP metoda: GET
- hlavičky:
Authorization: Basic dGVzdDp0ZXN0
Content-Type: application/json
- tělo:
states
(array) - pole objektů se stavytype
(string) - typ stavu, pokud je hodnotanull
, tak se jedná o vlastní stav, jinak to jsou systémové stavy:- Received - Přijatá
- Canceled - Storno
- PaymentSuccessful - Platba úspěšná
- PaymentFailed - Platba selhala
- PaymentCanceled - Platba zrušena
- PaymentInProcess - Platba probíhá
- Unresolved - Nedořešená
color
(string) - barva pro odlišení stavu v HTML HEX formátunames
(object) - názvy stavu objednávky v jednotlivých jazycích, klíč v objektu je kód jazyka podle ISO 8601 a hodnota je název stavu např.{ "cz": "Přijatá" }
-
příklad odpovědi (HTTP 200 OK)
HTTP/1.1 200 OK Content-Type: application/json { "states": [ { "type": "", "color": "", "names": { } } ] }