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 je true
    • send_sms_yn (bool) - poslání SMS která je navázána na stav objednávky, výchozí hodnota je true (SMS služba není standardně aktivní, více najdete v Nastavení SMS)
    • orders (array)- pole objektů s objednávkami
      • external_order_number (string) - číslo objednávky z externího systému
      • language_id (language) - jazyk objednávky, jazyk musí být vytvořen v administraci eshopu
      • prices_with_vat_yn (bool) - příznak jestli jsou ceny s DPH, pokud není zadáno bere se podle nastavení z administrace
      • status (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ávky
      • paid_date (date) - datum zaplacení objednávky
      • tracking_code (string) - trackovací kód pro dopravu
      • resolved_yn (bool) - příznak pro vyřešenou objednávku
      • internal_note (string) - interní poznámka
      • variable_symbol (string) - variabilní symbol (maximální délka 10 znaků, jen z číslice), pokud není uvedeno generuje se systémem z čísla objednávky
      • customer (object) - zákazník
        • email (email) - email zákazníka
        • phone (string) - telefon
        • firstname_invoice (string) - fakturační jméno
        • surname_invoice (string) - fakturační příjmení
        • street_invoice (string) - fakturační ulice a číslo
        • city_invoice (string) - fakturační město
        • state_invoice (string) - fakturační okres
        • zip_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 hodnotu true
        • firstname_postal (string) - doručovací jméno
        • surname_postal (string) - doručovací přijmení
        • street_postal (string) - doručovací ulice a číslo
        • city_postal (string) - doručovací město
        • state_postal (string) - doručovací okres
        • zip_postal (string) - doručovací PSČ
        • country_id_postal (country) - doručovací země
        • company_postal (string) - doručovací název firmy
        • company_yn (bool) - příznak jestli je zákazník firma
        • company (string) - název firmy, povinné pokud je firma
        • ico (string) - IČO
        • dic (string) - DIČ
        • vat_payer_yn (bool) - příznak jestli je firma plátce DPH
        • customer_note (string) - poznámka zákazníka
      • products (array) - pole objektů s produkty
        • code (string) - kód produktu
        • title (string) - název produktu
        • quantity (float) - počet kusů
        • unit (string) - jednotka
        • price_per_unit (float) - cena za jednu jednotku produktu
        • vat (float) - hodnota DPH v %
        • weight (int) - váha jedné jednotky produktu v gramech
        • invoice_info (string) - poznámka k produktu která se propisuje do faktury
        • parameters (array)- pole objektů s parametry produktu
          • name (string) - název parametru
          • value (string) - hodnota parametru
      • shipment (object)- doprava
        • code (string) - kód dopravy, páruje se s kódem dopravy (ve vlastních polích) v administraci
        • name (string) - název 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 se s kódem platby (ve vlastních polích) v administraci
        • name (string) - název platby
        • price (float) - cena platby
        • vat (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 poli
        • key (string) - klíč vlastního pole
        • value (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,
        "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ávky
      • external_order_number (string) - externí číslo objednávky
      • order_number (string) - číslo objednávky, pokud se objednávka nevytvoří, vrací null
      • order_url (string) - URL adresa kde se nachází objednávka
      • created_yn (bool) - příznak jestli se objednávka vytvořila
      • messages (array)- pole objektů chybových zpráv a upozornění při zpracování objednávky
        • object (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 je true
    • orders (array)- pole objektů s objednávkami
      • order_number (string) - číslo objednávky
      • status (string) - název stavu objednávky, stav musí být vytvořen v administraci, seznam stavů se dá zjistit pomocí metody GET /order-state
      • paid_date (date) - datum zaplacení objednávky
      • tracking_code (string) - trackovací kód pro dopravu
      • resolved_yn (bool) - příznak pro vyřešenou objednávku
      • metas (array)- pole objektů s vlastními poli
        • key (string) - klíč vlastního pole
        • value (string) - hodnota vlastního pole
  • 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": "",
                "metas": [
                    {
                        "key": "",
                        "value": ""
                    }
                ]
            }
        ]
    }
    

Odpověď

  • tělo:
    • orders (array)- pole objektů s objednávky
      • order_number (string) - číslo objednávky
      • order_url (string) - URL adresa kde se nachází objednávka
      • updated_yn (bool) - příznak jestli se objednávka aktualizovala
      • messages (array)- pole objektů chybových zpráv a upozornění při zpracování objednávky
        • object (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": "",
                "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ávky
    • order_numbers (string) - čísla objednávek oddělená středníkem ;

Odpověď

  • tělo:
    • orders (array)- pole objektů s objednávky
      • order_number (string) - číslo objednávky
      • deleted_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ávky
        • object (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 (musí být definovám alespoň jeden parametr):
    • order_number (string) - číslo objednávky
    • order_numbers (string) - čísla objednávek oddělená středníkem ;
    • creation_time_from (date) - vrátí objednávky vytvořené od tohoto data
    • last_update_time_from (date) - vrátí objednávky změněné od tohoto data
    • page (int) - stránka, pokud není definováno, vrací vždy stranu 1
    • status*(string)* - stav objednávky, pokud bude prázdný, vrátí objednávky kde není žádný stav
    • paid_yn (bool) - pokud je 1, vrátí zaplacené objednávky

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í strana
    • current_page_items (int) - počet položek na aktuální straně
    • number_of_pages (int) - celkový počet stran
    • number_of_items (int) - celkový počet položek
    • orders (array)- pole objektů s objednávkami
      • order_number (string) - číslo objednávky
      • external_order_number (string) - číslo objednávky z externího systému
      • language_id (language) - jazyk objednávky
      • currency_id (currency) - měna objednávky
      • prices_with_vat_yn (bool) - příznak jestli jsou ceny s DPH
      • status (string) - název stavu objednávky
      • paid_date (date) - datum zaplacení objednávky
      • tracking_code (string) - trackovací kód pro dopravu
      • resolved_yn (bool) - příznak pro vyřešenou objednávku
      • internal_note (string) - interní poznámka
      • last_update_time (date) - datum aktualizace
      • creation_time (date) - datum vytvoření
      • variable_symbol (string) - variabilní symbol
      • total_weight (int) - celková váha objednávky
      • order_total (float) - celková cena
      • invoice_number (string) - číslo faktury
      • order_html_url (string) - URL na HTML objednávky
      • customer (object)- zákazník
        • email (email) - email zákazníka
        • phone (string) - telefon
        • firstname_invoice (string) - fakturační jméno
        • surname_invoice (string) - fakturační příjmení
        • street_invoice (string) - fakturační ulice a číslo
        • city_invoice (string) - fakturační město
        • state_invoice (string) - fakturační okres
        • zip_invoice (string) - fakturační PSČ
        • country_id_invoice (country) - fakturační země
        • postal_yn (bool) - příznak doručovací adresy
        • firstname_postal (string) - doručovací jméno
        • surname_postal (string) - doručovací přijmení
        • street_postal (string) - doručovací ulice a číslo
        • city_postal (string) - doručovací město
        • state_postal (string) - doručovací okres
        • zip_postal (string) - doručovací PSČ
        • country_id_postal (country) - doručovací země
        • company_postal (string) - doručovací název firmy
        • company_yn (bool) - příznak jestli je zákazník firma
        • company (string) - název firmy
        • ico (string) - IČO
        • dic (string) - DIČ
        • vat_payer_yn (bool) - příznak jestli je firma plátce DPH
        • customer_note (string) - poznámka zákazníka
        • agreements (array)- pole objektů se souhlasy
          • name (string) - název souhlasu
          • valid_to (date) - čas do kdy je souhlas platný
          • status (bool) - stav souhlasu
      • products (array)- pole objektů s produkty
        • code (string) - kód produktu
        • title (string) - název produktu
        • quantity (float) - počet kusů
        • unit (string) - jednotka
        • price_per_unit (float) - cena za jeden kus produktu
        • price (float) - cena za jeden kus produktu
        • vat (float) - hodnota DPH v %
        • weight (int) - váha jedné jednotky produktu v gramech
        • invoice_info (string) - poznámka k produktu která se propisuje do faktury
        • parameters (array)- pole objektů s parametry produktu
          • name (string) - název parametru
          • value (string) - hodnota parametru
      • discount_voucher (object)- slevový kupón
        • code (string) - kód slevového kuponu
        • type (string) - typ slevy, možné hodnoty jsou percent nebo price
        • amount (float) - výše slevy, pokud je typ slevy percent jsou to procenta, pokud price je to cena
        • discounts (array)- pole objektů se slevami rozpočínanými pro jednotliv hladiny DPH
          • price (float) - hodnota slevy
          • vat (float) - DPH v %
      • quantity_discount (object)- množstevní sleva
        • type (string) - typ slevy, možné hodnoty jsou percent nebo price
        • amount (float) - výše slevy, pokud je typ slevy percent jsou to procenta, pokud price je to cena
        • discounts (array)- pole objektů se slevami rozpočínanými pro jednotliv hladiny DPH
          • price (float) - hodnota slevy
          • vat (float) - DPH v %
      • loyalty_points (object)- věrnostní body
        • one_point_for (float) - hodnota jednoho bodu
        • amount (float) - výše slevy, pokud je typ slevy percent jsou to procenta, pokud price je to cena
        • discounts (array)- pole objektů se slevami rozpočínanými pro jednotliv hladiny DPH
          • price (float) - hodnota slevy
          • vat (float) - DPH v %
      • shipment (object)- doprava
        • code (string) - kód dopravy, páruje se s kódem dopravy (ve vlastních polích) v administraci
        • name (string) - název 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 se s kódem platby (ve vlastních polích) v administraci
        • name (string) - název platby
        • price (float) - cena platby
        • vat (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 poli
        • key (string) - klíč vlastního pole
        • value (string) - hodnota vlastního pole
  • 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": [
                    {
                        "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 stavy
      • type (string) - typ stavu, pokud je hodnota null, 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á
      • names (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": "",
                "names": { }
            }
        ]
    }