Dokumentace API - Objednávky

Základní informace

Základní informace k API, autentizaci, stavovým kódům, HTTP metodám, datovým typům 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
    • creation_time (date) - čas vytvoření 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
      • pricelist_name (string) - název ceníku
      • pricelist_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 produkty
      • code (string) - kód produktu
      • ean (string) - EAN 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": "",
                      "ean": "",
                      "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 /api/v2/orders/states
    • 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
    • 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": "",
              "internal_note": "",
              "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} &creation_time_to={creation_time_to} &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:
  • 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
  • creation_time_to (date) - vrátí objednávky vytvořené do tohoto data včetně
  • last_update_time_from (date) - vrátí objednávky změněné od tohoto data
  • paid_yn (bool) - pokud je 1, vrátí zaplacené objednávky
  • status (string) - stav objednávky, pokud bude prázdný, vrátí objednávky kde není žádný stav
  • language (language) - jazyková mutace na které objednávka vznikla
  • email (string) - email zákazníka objednávky
  • page (int) - stránka, pokud není definováno, vrací vždy stranu 1
  • order_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í 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_id (int) - ID stavu objednávky
    • 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
    • oss_yn (bool) - příznak jestli byla objednávka vytvořena v režimu OSS
    • 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 s DPH
    • order_total_before_round (float) - celková cena s DPH před zaokrouhlením
    • order_total_rest (float) - hodnota zaokrouhlení celkové ceny s DPH
    • invoice_number (string) - číslo faktury
    • admin_url (string) - URL do detailu objednávky v administraci
    • 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
      • ean (string) - EAN 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) - celková cena za produkt
      • vat (float) - hodnota DPH v %
      • weight (int) - váha jedné jednotky produktu v gramech
      • availability (string) - dostupnost produktu ve chvíli kdy byl objednán
      • invoice_info (string) - poznámka k produktu která se propisuje do faktury
      • parameters (array) - pole objektů s parametry produktu
        • name (string) - název konfigurace
        • value (string) - hodnota parametru
        • configurations (array) - pole objektů s konfiguracemi produktu
          • name (string) - název parametru
          • values (array) - pole hodnot
            • value (string) - hodnota
            • operation (string) - operace (+, -)
            • cena (float) - cena konfigurace (je již připočtena k ceně produktu)
    • 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 (cena) jednoho bodu
      • amount (float) - výše slevy
      • 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
      • type (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 jazyky
      • values (array) - pole objektů s hodnotami, v případě kdy není hodnota vlastního pole společná pro všechny jazyky
        • language (language) - specifikace jazykové mutace
        • value (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_id": "",
              "status": "",
              "paid_date": "",
              "tracking_code": "",
              "resolved_yn": "",
              "internal_note": "",
              "last_update_time": "",
              "creation_time": "",
              "variable_symbol": "",
              "total_weight": "",
              "order_total": "",
              "order_total_before_round": "",
              "order_total_rest": "",
              "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": "",
                      "ean": "",
                      "title": "",
                      "unit": "",
                      "quantity": "",
                      "price_per_unit": "",
                      "price": "",
                      "vat": "",
                      "weight": "",
                      "invoice_info": "",
                      "parameters": [
                          {
                              "name": "",
                              "value": ""
                          }
                      ],
                      "configurations": [
                          {
                              "name": "",
                              "values": [
                                  {
                                      "value": "",
                                      "operation": "",
                                      "price": ""
                                  }
                              ]
                          }
                      ]
                  }
              ],
              "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
    • id (int) - ID stavu
    • 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á
    • color (string) - barva pro odlišení stavu v HTML HEX formátu
    • 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": "",
              "color": "",
              "names": { }
          }
      ]
  }