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,
    "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á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_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á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, neplatí pro page):
    • 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
      • case_number (string) - číslo obchodního případu
      • 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
      • default_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 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
        • product_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 produktu
        • title (string) - název produktu
        • quantity (float) - počet jednotek
        • 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": [
                {
                    "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 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": { }
        }
    ]
}