API v2 Objednávky :: Internetové obchody UPgates.sk

Vytvorené 14. 08. 2018

Objednávky

Základné informácie
Vytvorenie objednávky
Aktualizácia objednávky
Zmazanie objednávok
Zoznam objednávok
HTML objednávka
Stavy objednávky

Základné informácie

Základné informácie k API, autentizáciu, stavové kódy, HTTP metódy, dátové typy a ďalšie nájdete na API v2 základné informácie

Vytvorenie objednávky

Požiadavka

URI: / api / v2 / orders
HTTP metóda: POST
hlavičky:
- Authorization: Basic dGVzdDp0ZXN0
- Content-Type: application / json
telo:
- send_emails_yn (bool) - poslanie emailu ktorý je naviazaný na stav objednávky, predvolená hodnota true
- send_sms_yn (bool) - poslanie SMS ktorá je naviazaná na stav objednávky, predvolená hodnota true (SMS služba nie je štandardne aktívny, viac nájdete v Nastavenie SMS)
- orders (array) - pole objektov s objednávkami
  - external_order_number (string) - číslo objednávky z externého systému
  - language_id (language) - jazyk objednávky, jazyk musí byť vytvorený v administrácii eshopu
  - prices_with_vat_yn (bool) - príznak či sú ceny s DPH, pokiaľ nie je zadané berie sa podľa nastavenia z administrácie
  - status (string) - názov stavu objednávky z administrácie (východiskový stav u novej objednávky je Prijatá), zoznam stavov sa dá zistiť pomocou metódy GET, viac v sekcii Stavy objednávky
  - paid_date (date) - dátum zaplatenia objednávky
  - tracking_code (string) - trackovací kód pre dopravu
  - resolved_yn (bool) - príznak pre vyriešenú objednávku
  - internal_note (string) - interná poznámka
  - variable_symbol (string) - variabilný symbol (maximálna dĺžka 10 znakov, len z číslice), pokiaľ nie je uvedené generuje so systémom z čísla objednávky
  - customer (object) - zákazník
    - email (email) - email zákazníka
    - phone (string) - telefón
    - firstname_invoice (string) - fakturačnú meno
    - surname_invoice (string) - fakturačnú priezvisko
    - street_invoice (string) - fakturačnú ulice a číslo
    - city_invoice (string) - fakturačnú mesto
    - state_invoice (string) - fakturačnú okres
    - zip_invoice (string) - fakturačnú PSČ
    - country_id_invoice (country) - fakturačnú krajiny
    - postal_yn (bool) - príznak doručovacej adresy, ak posielate doručovaciu adresu musí mať hodnotu true
    - firstname_postal (string) - doručovacia meno
    - surname_postal (string) - doručovacia priezvisko
    - street_postal (string) - doručovacia ulice a číslo
    - city_postal (string) - doručovacia mesto
    - state_postal (string) - doručovacia okres
    - zip_postal (string) - doručovacia PSČ
    - country_id_postal (country) - doručovacia krajiny
    - company_postal (string) - doručovacia názov firmy
    - company_yn (bool) - príznak či je zákazník firma
    - company (string) - názov firmy, povinné ak je firma
    - ico (string) - IČO
    - dic (string) - DIČ
    - vat_payer_yn (bool) - príznak či je firma platcu DPH
    - customer_note (string) - poznámka zákazníka
  - products (array) - pole objektov s produktmi
    - code (string) - kód produktu
    - title (string) - názov produktu
    - quantity (float) - počet kusov
    - unit (string) - jednotka
    - price_per_unit (float) - cena za jednu jednotku produktov
    - vat (float) - hodnota DPH v%
    - weight (int) - váha jednej jednotky produktu v gramoch
    - invoice_info (string) - poznámka k produktu ktorá sa prepisujú do faktúry
    - parameters (array) - pole objektov s parametrami produktu
      - name (string) - názov parametra
      - value (string) - hodnota parametra
  - shipment (object) - doprava
    - code (string) - kód dopravy, páruje sa s kódom dopravy (vo vlastných poliach) v administrácii
    - name (string) - názov dopravy
    - price (float) - cena dopravy
    - vat (float) - hodnota DPH v%
    - affiliate_id (string) - ID pobočky dopravy
  - payment (object) - platba
    - code (string) - kód platby, páruje sa s kódom platby (vo vlastných poliach) v administrácii
    - name (string) - názov platby
    - price (float) - cena platby
    - vat (float) - hodnota DPH v%
    - eet_yn (bool) - príznak či je so má poslať objednávka do EET
  - metas (array) - pole objektov s vlastnými poľami
    - key (string) - kľúč vlastného poľa
    - value (string) - hodnota vlastného poľa

príklad požiadavke

 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": ""
                }
            ]
        }
    ]
}

Odpoveď

telo:
- orders (array) - pole objektov s objednávky
  - external_order_number (string) - externé číslo objednávky
  - order_number (string) - číslo objednávky, ak sa objednávka nevytvorí, vracia null
  - order_url (string) - URL adresa kde sa nachádza objednávka
  - created_yn (bool) - príznak či sa objednávka vytvorila
  - messages (array) - pole objektov chybových správ a upozornenia pri spracovaní objednávky
    - object (string) - názov objektu (časť JSON) ktorého sa správa týka
    - property (string) - hodnota ktorej sa správa týka
    - message (string) - text správy

príklad odpovede (HTTP 200 OK)

 HTTP / 1.1 200 OK
Content-Type: application / json

{
    "Orders": [
        {
            "Order_number": "",
            "Order_url": "",
            "Created": "",
            "Messages": [
                {
                    "Object": "",
                    "Property": "",
                    "Message": ""
                }
            ]
        }
    ]
}

Aktualizácia objednávok

Požiadavka

URI: / api / v2 / orders
HTTP metóda: PUT
hlavičky:
- Authorization: Basic dGVzdDp0ZXN0
- Content-Type: application / json
telo:
- objednávky sa párujú podľa čísla order_number. Pri zmene stavu sa posielajú emaily (ak je nejaký email u stave objednávky nastavený). V odpovedi sú všetky objednávky ktoré boli v požiadavke.
- send_emails_yn (bool) - poslanie emailu pri zmene stavu (ak je nejaký email nastavený), predvolená hodnota true
- orders (array) - pole objektov s objednávkami
  - order_number (string) - číslo objednávky
  - status (string) - názov stavu objednávky, stav musí byť vytvorený v administrácii, zoznam stavov sa dá zistiť pomocou metódy GET / order-state
  - paid_date (date) - dátum zaplatenia objednávky
  - tracking_code (string) - trackovací kód pre dopravu
  - resolved_yn (bool) - príznak pre vyriešenú objednávku
  - metas (array) - pole objektov s vlastnými poľami
    - key (string) - kľúč vlastného poľa
    - value (string) - hodnota vlastného poľa

príklad požiadavku

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": ""
                }
            ]
        }
    ]
}

Odpoveď

telo:
- orders (array) - pole objektov s objednávky
  - order_number (string) - číslo objednávky
  - order_url (string) - URL adresa kde sa nachádza objednávka
  - updated_yn (bool) - príznak či sa objednávka aktualizovala
  - messages (array) - pole objektov chybových správ a upozornenia pri spracovaní objednávky
    - object (string) - názov objektu (časť JSON) ktorého sa správa týka
    - property (string) - hodnota ktorej sa správa týka
    - message (string) - text správy

príklad odpovede (HTTP 200 OK)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "orders": [
        {
            "order_number": "",
            "order_url": "",
            "updated": "",
            "messages": [
                {
                    "object": "",
                    "property": "",
                    "message": ""
                }
            ]
        }
    ]
}

Zmazanie objednávok

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": ""
                }
            ]
        }
    ]
}

Zoznam objednávok

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
parametre (musí byť definovám aspoň jeden parameter):
- order_number (string) - číslo objednávky
- order_numbers (string) - čísla objednávok oddelená bodkočiarkou ;
- creation_time_from (date) - vráti objednávky vytvorené od tohto dátumu
- last_update_time_from (date) - vráti objednávky zmenené od tohto dátumu
- page (int) - stránka, pokiaľ nie je definované, vracia vždy stranu 1
- status * (string) * - stav objednávky, ak bude prázdny, vráti objednávky kde nie je žiadny stav
- paid_yn (bool) - ak je 1, vráti zaplatené objednávky

Odpoveď

Zoznam objednávok je dostupný po jednotlivých stranách, výstup je obmedzený na 100 položiek na stránku.

telo:
- current_page (int) - aktuálna strana
- current_page_items (int) - počet položiek na aktuálnej strane
- number_of_pages (int) - celkový počet strán
- number_of_items (int) - celkový počet položiek
- orders (array) - pole objektov s objednávkami
  - order_number (string) - číslo objednávky
  - external_order_number (string) - číslo objednávky z externého systému
  - language_id (language) - jazyk objednávky
  - currency_id (currency) - mena objednávky
  - prices_with_vat_yn (bool) - príznak či sú ceny s DPH
  - status (string) - názov stavu objednávky
  - paid_date (date) - dátum zaplatenia objednávky
  - tracking_code (string) - trackovací kód pre dopravu
  - resolved_yn (bool) - príznak pre vyriešenú objednávku
  - internal_note (string) - interná poznámka
  - last_update_time (date) - dátum aktualizácie
  - creation_time (date) - dátum vytvorenia
  - variable_symbol (string) - variabilný symbol
  - total_weight (int) - celková váha objednávky
  - order_total (float) - celková cena
  - invoice_number (string) - číslo faktúry
  - order_html_url (string) - URL na HTML objednávky
  - customer (object) - zákazník
    - email (email) - email zákazníka
    - phone (string) - telefón
    - firstname_invoice (string) - fakturačnú meno
    - surname_invoice (string) - fakturačnú priezvisko
    - street_invoice (string) - fakturačnú ulice a číslo
    - city_invoice (string) - fakturačnú mesto
    - state_invoice (string) - fakturačnú okres
    - zip_invoice (string) - fakturačnú PSČ
    - country_id_invoice (country) - fakturačnú krajiny
    - postal_yn (bool) - príznak doručovacej adresy
    - firstname_postal (string) - doručovacia meno
    - surname_postal (string) - doručovacia priezvisko
    - street_postal (string) - doručovacia ulice a číslo
    - city_postal (string) - doručovacia mesto
    - state_postal (string) - doručovacia okres
    - zip_postal (string) - doručovacia PSČ
    - country_id_postal (country) - doručovacia krajiny
    - company_postal (string) - doručovacia názov firmy
    - company_yn (bool) - príznak či je zákazník firma
    - company (string) - názov firmy
    - ico (string) - IČO
    - dic (string) - DIČ
    - vat_payer_yn (bool) - príznak či je firma platcu DPH
    - customer_note (string) - poznámka zákazníka
    - agreements (array) - pole objektov sa súhlasy
      - name (string) - názov súhlasu
      - valid_to (date) - čas do kedy je súhlas platný
      - status (bool) - stav súhlasu
  - products (array) - pole objektov s produktmi
    - code (string) - kód produktu
    - title (string) - názov produktu
    - quantity (float) - počet kusov
    - 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 jednej jednotky produktu v gramoch
    - invoice_info (string) - poznámka k produktu ktorá sa prepisujú do faktúry
    - parameters (array) - pole objektov s parametrami produktu
      - name (string) - názov parametra
      - value (string) - hodnota parametra
  - discount_voucher (object) - zľavový kupón
    - code (string) - kód zľavového kupónu
    - type (string) - typ zľavy, možné hodnoty sú percent alebo price
    - amount (float) - výška zľavy, ak je typ zľavy percent sú to percentá, ak price je to cena
    - discounts (array) - pole objektov so zľavami rozpočínanými pre jednotliv hladiny DPH
      - price (float) - hodnota zľavy
      - vat (float) - DPH v%
  - quantity_discount (object) - množstevná zľava
    - type (string) - typ zľavy, možné hodnoty sú percent alebo price
    - amount (float) - výška zľavy, ak je typ zľavy percent sú to percentá, ak price je to cena
    - discounts (array) - pole objektov so zľavami rozpočínanými pre jednotliv hladiny DPH
      - price (float) - hodnota zľavy
      - vat (float) - DPH v%
  - loyalty_points (object) - vernostné body
    - one_point_for (float) - hodnota jedného bodu
    - amount (float) - výška zľavy, ak je typ zľavy percent sú to percentá, ak price je to cena
    - discounts (array) - pole objektov so zľavami rozpočínanými pre jednotliv hladiny DPH
      - price (float) - hodnota zľavy
      - vat (float) - DPH v%
  - shipment (object) - doprava
    - code (string) - kód dopravy, páruje sa s kódom dopravy (vo vlastných poliach) v administrácii
    - name (string) - názov dopravy
    - price (float) - cena dopravy
    - vat (float) - hodnota DPH v%
    - affiliate_id (string) - ID pobočky dopravy
  - payment (object) - platba
    - code (string) - kód platby, páruje sa s kódom platby (vo vlastných poliach) v administrácii
    - name (string) - názov platby
    - price (float) - cena platby
    - vat (float) - hodnota DPH v%
    - eet_yn (bool) - príznak či je so má poslať objednávka do EET
  - metas (array) - pole objektov s vlastnými poľami
    - key (string) - kľúč vlastného poľa
    - value (string) - hodnota vlastného poľa

príklad odpovede (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

Vracia dokument objednávky vo formáte HTML

URI: / api / v2 / orders / {order_number} / html
HTTP metóda: GET
hlavičky:
- Authorization: Basic dGVzdDp0ZXN0
- Content-Type: application / json
parametre:
- order_number (string) - číslo objednávky

hlavičky odpovede (HTTP 200 OK)

 HTTP / 1.1 200 OK
Content-Type: text / html

Stavy objednávky

Vracia zoznam stavov objednávok. V požiadavke pre aktualizáciu alebo vytvorenie objednávky sa dá použiť názov stavu v akomkoľvek jazyku.

URI: / api / v2 / orders / states
HTTP metóda: GET
hlavičky:
- Authorization: Basic dGVzdDp0ZXN0
- Content-Type: application / json
telo:
- states (array) - pole objektov so stavmi
  - type (string) - typ stave, ak je hodnota null, tak sa jedná o vlastné stav, inak to sú systémové stavy:
    - Received - Prijatá
    - canceled - Storno
    - PaymentSuccessful - Platba úspešná
    - PaymentFailed - Platba zlyhala
    - PaymentCanceled - Platba zrušená
    - PaymentInProcess - Platba prebieha
    - Unresolved - Nedoriešená
  - names (object) - názvy stavu objednávky v jednotlivých jazykoch, kľúč v objekte je kód jazyka podľa ISO 8601 a hodnota je názov stave napr. { "cz": "Prijatá"}

príklad odpovede (HTTP 200 OK)

HTTP/1.1 200 OK
Content-Type: application/json

{
    "states": [
        {
            "type": "",
            "names": { }
        }
    ]
}

Objednávky

Základné informácie

Vytvorenie objednávky

Požiadavka

Odpoveď

Aktualizácia objednávok

Požiadavka

Odpoveď

Zmazanie objednávok

Odpověď

Zoznam objednávok

Odpoveď

HTML objednávka

Stavy objednávky

Ďalšie články v tejto kategórii

API v2 Základné informácie

API v2 Produkty

API v2 Zákazníci

API v2 Objednávky

API v2 Faktúry

Dokumenty API pre aktualizáciu objednávok