API

poslední revize: 16.08.2023

Obecné informace

Adresa API požadavku se skládá z několika částí

Base URL: https://zp.toptrans.cz/api
Datový formát: json nebo xml
Datová entita: například order
Metoda: například price

Příklad kompletní URL pro metodu výpočtu ceny objednávky:

https://zp.toptrans.cz/api/json/order/price/

Přihlášení

Autentizace probíhá metodou Basic. Je proto důležité používat zabezpečený protokol HTTPS.

Použijte stejné přihlašovací údaje, jako používáte pro přihlášení do webové aplikace ZP2.

Data požadavku

Samotná data požadavku (vstupní parametry) se posílají přímo v těle POST požadavku, tzv. RAW POST data. Podle zvoleného formátu JSON nebo XML. Některé metody vstupní data neočekávají, v takovém případě je tělo POST prázdné.

U názvy atributů nezáleží na velikost písmen, takže atributy last_name, Last_Name a LAST_NAME jsou ekvivalentní.

Při zpracování vstupních dat se vnořené elementy (s výjimkou elementů s variabilním počtem dětí - u objednávek jsou to atributy packs a adrs) převádí na podtržítkovou notaci. Konkrétně například následující tři fragmenty XML jsou z pohledu zpracování ekvivalentní:

<discharge>
    <address>
        <city>Praha 6</city>
        <street>Jaselská</street>
    </address>
</discharge>

nebo

<discharge>
    <address_city>Praha 6</address_city>
    <address_street>Jaselská</address_street>
</discharge>

nebo

<discharge_address_city>Praha 6</discharge_address_city>
<discharge_address_street>Praha 6</discharge_address_street>

Totéž platí pro JSON variantu:

{
    "discharge": {
        "address": {
            "city": "Praha 6"
            "street": "Jaselská"
        }
    }
}

nebo

{
    "discharge": {
        "address_city": "Praha 6"
        "address_street": "Jaselská"
    }
}

nebo

{
    "discharge_address_city": "Praha 6"
    "discharge_address_street": "Jaselská"
}

Použijte tedy variantu, která vám nejlépe vyhovuje

Data odpovědi

Odpověď má tři hlavní atributy

status: Nabývá hodnoty ok nebo error (pokud došlo k chybě)
data: Výstupní data, liší se dle metody. Data můžou být vrácena i v případě chyby, ze které se podařilo zotavit.
errors: Pole obsahující chybové hlášky. V případě úspěchu (status=ok) je prázdné.

Reprezentace dat v JSON a XML

XML musí mít právě jeden kořenový element. Na jeho názvu v našem API nezáleží.

JSON objektu odpovídá XML struktura, kde jednoduše každý XML element jsou shodný jako klíč v JSON objektu. Například:

<root>
    <address>
        <city>Praha 6</city>
        <street>Jaselská</street>
    </address>
</root>

---

{
    "adddress": {
        "city": "Praha 6",
        "street": "Jaselská"
    }
}

Pole (klasické numericky indexované) je v XML reprezentováno rodičovským elementem s názvem v množném čísle (např. <packs>) a dětmi s názvem v jednotném čísle (např. <pack>):

<root>
    <packs>
        <pack>
            <quantity>1</quantity>
            <description>Jeden kus</description>
        </pack>
        <pack>
            <quantity>2</quantity>
            <description>Dva kusy</description>
        </pack>
    </packs>
</root>    

---

{
    "packs": [
        {
            "quantity": 1,
            "description": Jeden kus
        },
        {
            "quantity": 2,
            "description": Dva kusy
        }
    ]
}

Api metody

Číselníky

Metody vracející hodnoty z různých číselníků. Žádná z těchto metod nevyžaduje vstupní data. Zároveň jsou všechny tyto metody veřejné, tj. nevyžadují HTTP autentizaci. Pro všechny metody je shodná datová entita register, tj. příklad adresy, která vrací seznam všech typů obalů ve formátu JSON je

https://zp.toptrans.cz/api/json/register/pack

Seznam číselníků:

comfort: seznam hodnot pro službu Komfort na vykládce
comfort-loading: seznam hodnot pro službu Komfort na nakládce
term: termín - vyýběr základní přepravní služby
currency: měna
delivery-notes: Služba dodací listy zpět
freight-cash: Přepravné v hotovosti
pack: Číselník druhů obalů
returnable-pack: Typ vratného obalu

Výpočet ceny přepravy `order/price`

Povinné vstupní parametry. Základní parametry, bez kterých nelze cenu vypočítat.

loading_address_city
loading_address_zip
discharge_address_city -discharge_address_zip
kg nebo m3

Další parametry, které mají vliv na cenu přepravy:

cash_on_delivery_type: 0 (bez dobírka, výchozí), 1 (s dobírkou)
num_epals: počet euro palet
oversize: nadměrná zásilka, hodnota 0 (vypnuto, výchozí), 1 (zapnuto)
loading_comfort_id: ID služby Comfort na nakládce, hodnota viz číselník (API služba registers/comfort-loading)
discharge_comfort_id: ID služby Comfort na vykládce, hodnota viz číselník (API služba registers/comfort-discharge)
loading_floors: Počet pater při některých variantách služby Comfort na nakládce
discharge_floors: Počet pater při některých variantách služby Comfort na vykládce
twoway_shipment: Obousměrná zásilka, hodnota 0 (vypnuto, výchozí) nebo 1 (zapnuto)
yard: Služba sběrný dvůr, hodnota 0 (vypnuto, výchozí) nebo 1 (zapnuto)
return_pack_id: Druh vratného obalu, viz číselník (API služba registers/returnable-pack)
return_pack_count: Počet vratných obalů
loading_aviso: Tel. avizace na nakládce
discharge_aviso: Tel. avizace na vykládce

Pozn. Při výpočtu ceny lze vynechat obec a zadat jen PSČ nakládky a vykládky. Při vytváření objednávek toto možné není, proto důrazně dopuručujeme vždy volat metodu s oběma parametry.

Zadání objednávky `order/save`

Vytvoří neodeslanou objednávku v ZP. Objednávka zůstává jen v rámci ZP, dokud ji neodešlete metodou order/send.

Vstupní parametry

Vstupní parametry objednávky jsou popsány v sekci dokumentace data, kde budou i průběžně aktualizovány. Pokud jste již používali Import objednávek v rámci ZP, bude pro vás přechod na API snadný. XML vstup je totožný s jednou objednávkou v XML importu.

Další vstupní parametry, které neovlivňují data samotná, ale jejich zpracování:

strict: režim zpracování objednávky - viz níže Zpracování chyb

Výstupní parametry

id: ID nové objednávky

Zpracování chyb

Máte dvě možnosti, jak přistupovat k chybám při zpracovíní objednávky.

Přísný režim (výchozí): jakákoliv chyba při zpracování objednávky (chybějící parametry, nesprávný formát parametrů apod.) má za důsledek neuložení objednávky.
Volný řežim: funguje stejně jako import ze souboru - chybové objednávky se uloží a budete je muset opravit před odesláním do systému TOPIS.

Režim se nastaví vstupním parametrem strict. Výchozí hodnota je 1, tedy přísný režim

Seznam neodeslaných objednávek `order/list`

Tato metoda vrací kompletní data neodeslaných objednávek. Atributy konkrétní objednávky lze rozdělit do tří kategorií

Vstupní data zadaná zákazníkem, viz dokumentace datových entit
Atributy generované systémem, jako např. číslo objednávky, viz dokumentace datových entit
Další nedokumentované atributy. Jejich užitečnost pro vás je vesměs nízká a některé nemusí být zcela aktuální, proto je berte prosím s rezervou.

Tisk štítků neodeslaných objednávek `order/print-unsent-labels`

Vytiskne štítky všech nebo vybraných neodeslaných objednávek.

Vstupní parametry

ids: Seznam ID objednávek. Není-li uvedeno, vygenerují se všechny neodeslané objednávky
position: Určení pozice pro tisk prvního štítku. Pozice se určuje jako pořadí štítku na archu A4 v matici 2x7

Výstupem je přímo PDF soubor.

Odeslání objednávek `order/send`

Odešle objednávky do informačního systému Toptransu.

Vstupní parametry

Metoda přijímá dva vstupní parametry, oba nepovinné

ids: Seznam ID objednávek. Není-li uvedeno, odešlou se všechny objednávky
options: Upřesňující volby. Konkrétně
- position: Určení pozice pro tisk prvního štítku. Pozice se určuje jako pořadí štítku na archu A4 v matici 2x7 počítané po sloupcích od nuly (hodnota 0 až 13). Výchozí pozice je 0

Výstupní parametry

numOk: Celkem odeslaných objednávek
numObj: Počet klasických objednávek
numNahlaska: Počet objednávek s nakládkou na jiném středisku (nahláška)
numSkipped: Počet přeskočených objednávek
numErrors: Počet chybových objednávek (neodeslaných)
orderListObj: ID dávky objednávek
orderListNahl: ID dávky nahlášek
message: Lidsky čitelná zpráva o počtu odeslaných objednávek
files: Soubory (PDF pro tisk). každý soubor má atributy filename (název souboru) a data (Base64 zakódovaná binární data, po rozkódování obsah PDF souboru)

Smazání objednávky `order/delete`

Jediný vstupní parameter id - ID objednávky tak, jak bylo vraceno metodou order/save.

Objednávka nesmí být odeslaná.

V případě úspěch vrací jako výsledek stejné ID objednávky.

Archiv objednávek `order/archive`

Archiv je historie dávek odeslaných objednávek a jdou z něj zpětně stáhnout všechny dokumenty, které se generují při odeslání objednávek (zasilatelský příkaz, štítky, atd.). Odpovídá sekci Objednávky > Tisk/Archiv z zákaznickém programu.

Vstupní parametry

dateFrom - datum od (včetně).
dateTo - datum do (včetně).
limit - počet vrácených záznamů. Výchozí a zároveň maximální hodnota je 100.

Poznámky k výchozím hodnotám dateFrom a dateTo:

není-li uveden parametr dateFrom, časové obdhobí není omezeno a počet vrácených záznamů je omezen jen celkovým limitem záznamů na jeden API požadavek.
je-li uveden jen parametr dateFrom, vrací se jen záznamy pro tento konkrétní den
jsou-li uvedeny oba parametry, vrací se záznamy pro dané období (včetně okrajových dnů) a počet vrácených záznamů je omezen celkovým limitem záznamů na jeden API požadavek.

Výstup

Výstupem je pole odeslaných dávek s následujícími parametry

id: ID dávky (v interní terminologi orderList)
timestamp: Datum a čas odeslání
nahlaska: Označuje, že jde o dávku s nakládkou mimo domovské středisko
order_ids: Pole ID objednávek
order_numbers: Pole čísel objednávek (aka čísel přepravních listů)
item_numbers: Pole čísel kusů (štítků)
labels: Pole označení objednávek
num_orders: Celkový počet objednávek v dávce
sum_quantity: Celkový počet kusů v dávce
sum_kg: Celková hmotnost objednávek v dávce

Tisk z archivu

Jedná se o následující metody. Společným rysem je to, že HTTP odpověď není json/xml jako u ostatních metod, ale přímo příslušný soubor (PDF nebo CSV podle kontextu).

Všechny metody mají povinný vstupní paremetr id. Jedná se o ID odeslané dávky objednávek, tak jak ho vrací metody order/send nebo order/archive.

Některé metody mají volitelné parametry, je to u nich přímo uvedeno

order/print-list - generuje PDF se zasilatelským příkazem
order/print-roll - generuje PDF se soupiskou
order/print-labels - generuje PDF se štítky. Má volitelný parametr position, který určuje pozici štítku na archu A4 (popis viz vstupní paremetry metody order/send)
order/print-adr - Generuje PDF s ADR soupiskou. Není definováno pro objednávky, které nemají ADR.
order/print-labels-csv - generuje Štítky v CSV

Stav zásilek (vyhledávání) `order/search`

Slouží k hledání stavu objednávek a informacích o doručení.

Vstupní parametry

orderNumber - číslo objednávky
itemNumber - číslo kusu (balíku, štítku)
label - označení zásilky

Pro všechny vstupní parametry platí, že mohou obsahovat několik hodnot oddělených čárkou. Limit je 50.

Výstupní

Výstupem je pole nalezených záznamů s následujícími parametry:

orderNumber - číslo objednávky
loadingDate - datum nakládky ve formátu dd.mm.yyyy
itemFrom - první číslo kusu (balíku) v rámci objednávky
itemTo - poslední číslo balíku
label - označení
deliveryBranch - středisko, které doručuje zásilku
deliveryDriver - jméno a telefon řidiče doručujícího zásilku
deliveryDate - datum doručení (prázdné/null, pokud není zásilka doručena)
status - aktuální stav zásilky

Příklady

1. Číselník obalů

Jednoduše zavoláme adresu https://zp.toptrans.cz/api/json/register/pack. Výsledkem je JSON objekt:

{
    status: "ok",
    data: {
        1: "KUS",
        2: "KARTON",
        ...
        65: "BITO BOX",
        66: "SPIRO"
    },
    errors: [ ]
}

Analogicky pro formát XML voláme adrsu https://zp.toptrans.cz/api/xml/register/pack a výsledkem je XML dokument:

<?xml version="1.0" encoding="UTF-8"?>
<toptrans>
  <status>ok</status>
  <data>
    <item>1/2-PAL</item>
    <item>BALIK</item>
    ...
    <item>XKUS</item>
    <item>XOBÁLKA</item>
  </data>
  <errors/>
</toptrans>

2. Výpočet ceny

JSON

URL:

https://zp.toptrans.cz/api/json/order/price/

POST data:

{
    "loading_address_city": "Vetřní",
    "loading_address_zip": "38211",
    "discharge_address_city": "Praha 5",
    "discharge_address_zip": "15000",
    "kg": 100,
    "cash_on_delivery_type": 1,
    "num_epals": 2,
    "oversize": 1
}

Odpověď:

{
    "status": "ok",
    "data": {
        "PRICE": 1219, // cena
        "FORCED_TARIF_PRICE": false,
        "CURRENCY_ID": 1, // id měny
        "KG": "100", // hmotnost
        "M3": "0.8", // kubatura (může být automaticky doplněna podle hmotnosti)
        "DISCOUNT": 79.9, // sleva absolutní
        "DISCOUNT_PERCENT": 10, // sleva relativní
        "FREIGHT_CASH_ID": 1, // id přepravného v hotovosti (může být automaticky nastaveno na 2 nebo 3)
        "serviceInput": {} // vstupní data výpočtu ceny
        "serviceOutput": {} // výstupní data výpočtu ceny
    },
    "errors": []
}

XML

URL:

https://zp.toptrans.cz/api/xml/order/price/

POST data:

<compute>
    <loading_address_city>Vetřní</loading_address_city>
    <loading_address_zip>38211</loading_address_zip>
    <discharge_address_city>Praha 5</discharge_address_city>
    <discharge_address_zip>15000</discharge_address_zip>
    <kg>100</kg>
</compute>

Odpověď

<?xml version="1.0" encoding="UTF-8"?>
<toptrans>
  <status>ok</status>
  <data>
    <PRICE>719</PRICE>
    <FORCED_TARIF_PRICE/>
    <CURRENCY_ID>1</CURRENCY_ID>
    <KG>100</KG>
    <M3>0.8</M3>
    <DISCOUNT>79.9</DISCOUNT>
    <DISCOUNT_PERCENT>10</DISCOUNT_PERCENT>
    <FREIGHT_CASH_ID>1</FREIGHT_CASH_ID>
    <serviceInput>
        ...
    </serviceInput>
    <serviceOutput>
        ...
    </serviceOutput>
  </data>
  <errors/>
</toptrans>

3. Vytvoření objednávky

JSON

Příklad s chybou. Pokud doplníte parametr adrs[0].kg, objednávka projde bez chyb

URL:

https://zp.toptrans.cz/api/json/order/save/

POST data:

{
    "discharge": {
        "name": "Internet Mall, a.s.",
        "address_city": "Praha 7",
        "address_street": "U garáží",
        "address_house_num": "1611/1",
        "address_zip": "17000",
        "last_name": "Novotná",
        "phone": "777111222"
    },
    "kg": 88,
    "packs": [
        {
            "quantity": 1,
            "pack_id": 1,
            "description": "Jeden kus"
        },    
        {
            "quantity": 2,
            "pack_id": 33,
            "description": "Dva boxy"
        }
    ],
    "adrs": [
        {
            "un": "2222",
            "count": 1,
            "environment_danger": 1
        }
    ]
}

Odpověď

{
    "status": "error",
    "data": {},
    "errors": {
        "0": "ADR musí mít zadanou hmotnost (KG) a počet kusů (COUNT)"
    }
}

XML

URL:

https://zp.toptrans.cz/api/xml/order/save/

POST data:

<orders>
    <order>
        <label>TEST123456</label>
        <payer_select>1</payer_select>
        <loading_select>1</loading_select>

        <discharge>
            <address>
                <city>Prachatice</city>
                <street>Dlouhá 35</street>
                <zip>38301</zip>
            </address>
            <name>Jaroslav Novák</name>
            <first_name>Jaroslav</first_name>
            <last_name>Novák</last_name>
            <phone>777888999</phone>
            <email>jaroslav@novak.cz</email>
        </discharge>

        <term_id>1</term_id>
        <discharge_aviso>1</discharge_aviso>
        <cash_on_delivery>
            <price>899</price>
            <price_cur_id>1</price_cur_id>
            <account2>4022466192</account2>
            <bank>7500</bank>
        </cash_on_delivery>
        <kg>10</kg>
        <order_value>4290</order_value>
        <order_value_currency_id>1</order_value_currency_id>

        <packs>
            <pack>
                <quantity>1</quantity>
                <pack_id>2</pack_id>
                <description>Granitovy drez</description>
            </pack>
        </packs>
    </order>
</orders>

Odpověď

<?xml version="1.0" encoding="UTF-8"?>
<toptrans>
  <status>ok</status>
  <data>
      <id>123456</id>
  </data>
  <errors/>
</toptrans>

4. Seznam neodeslaných objednávek

XML

https://zp.toptrans.cz/api/xml/order/list

JSON

https://zp.toptrans.cz/api/json/order/list

5. Odeslání objednávek

XML

URL

https://zp.toptrans.cz/api/xml/order/send

Požadavek

<toptrans/>

Odpověď

<?xml version="1.0" encoding="UTF-8"?>
<toptrans>
  <status>ok</status>
  <data>
    <numOk>1</numOk>
    <numObj>1</numObj>
    <numNahlaska>0</numNahlaska>
    <numSkipped>0</numSkipped>
    <numErrors>0</numErrors>
    <orderListObj>7059753</orderListObj>
    <message>Počet odeslaných objednávek: 1</message>
    <files>
      <zasilatelsky-prikaz>
        <filename>zasilatelsky-prikaz-17720018911</filename>
        <data>...</data>
      </zasilatelsky-prikaz>
      <soupiska>
        <filename>soupiska-17720018911</filename>
        <data>...</data>
      </soupiska>
      <stitky>
        <filename>stitky-17720018911</filename>
        <data>...</data>
      </stitky>
    </files>
  </data>
  <errors/>
</toptrans>

JSON

https://zp.toptrans.cz/api/xml/order/send

4. Smazání neodeslané objednávky

XML

Příklad neúspěšného pokusu o smazání

URL

https://zp.toptrans.cz/api/xml/order/delete

Požadavek

<toptrans>
    <id>7904044</id>
</toptrans>

Odpověď

<?xml version="1.0" encoding="UTF-8"?>
<toptrans>
  <status>error</status>
  <data/>
  <errors>
    <error id="0">Order not found.</error>
  </errors>
</toptrans>

JSON

Příklad úspěšného pokusu

URL

https://zp.toptrans.cz/api/json/order/delete

Požadavek

{"id": 7904044}

Odpověď

{
    "status": "ok",
    "data": 7904044,
    "errors": []
}

5. Archiv odeslaných objednávek

JSON

URL

https://zp.toptrans.cz/api/json/order/archive/

Požadavek

{ "dateFrom": "2017-09-22", "dateTo": "2017-09-30", "limit": 2 }

Odpověď

{
    "status": "ok",
    "data": [
        {
            "id": 8597721,
            "timestamp": "26.09.2017 13:14",
            "nahlaska": 0,
            "order_ids": [ 100, 101 ],
            "order_numbers": [ 17720028291, 17720028292 ],
            "labels": [ "asdf1", "asdf2" ],
            "sum_quantity": 1,
            "sum_kg": 2,
            "num_orders": 1,
        },    
    ]
}

6. Stav zásilek

JSON

URL

https://zp.toptrans.cz/api/json/order/search/

Požadavek

{ "itemNumber": "6502033259,6502033714" }

Odpověď

{
    "status": "ok",
    "data": [
        {
            "orderNumber": 17765017006,
            "loadingDate": "03.10.2017",
            "itemFrom": null,
            "itemTo": 6502033714,
            "label": "11063",
            "deliveryBranch": "450 Mladá Boleslav telefonní číslo +420 326 727 335",
            "deliveryDriver": "Petr Blahovec (420)731073110",
            "deliveryDate": null,
            "status": "Na rozvozu"
        },
        {
            "orderNumber": 17765016777,
            "loadingDate": "02.10.2017",
            "itemFrom": null,
            "itemTo": 6502033259,
            "label": "11063",
            "deliveryBranch": "001 Praha telefonní číslo +420 267 101 606",
            "deliveryDriver": null,
            "deliveryDate": null,
            "status": "Na rozvozovém depu"
        }
    ],
    "errors": []
}

API

Obecné informace

Přihlášení

Data požadavku

Data odpovědi

Reprezentace dat v JSON a XML

Api metody

Číselníky

Výpočet ceny přepravy order/price

Zadání objednávky order/save

Vstupní parametry

Výstupní parametry

Zpracování chyb

Seznam neodeslaných objednávek order/list

Tisk štítků neodeslaných objednávek order/print-unsent-labels

Vstupní parametry

Odeslání objednávek order/send

Vstupní parametry

Výstupní parametry

Smazání objednávky order/delete

Archiv objednávek order/archive

Vstupní parametry

Výstup

Tisk z archivu

Stav zásilek (vyhledávání) order/search

Vstupní parametry

Výstupní

Příklady

1. Číselník obalů

2. Výpočet ceny

JSON

XML

3. Vytvoření objednávky

JSON

XML

4. Seznam neodeslaných objednávek

XML

JSON

5. Odeslání objednávek

XML

JSON

4. Smazání neodeslané objednávky

XML

JSON

5. Archiv odeslaných objednávek

JSON

6. Stav zásilek

JSON

Výpočet ceny přepravy `order/price`

Zadání objednávky `order/save`

Seznam neodeslaných objednávek `order/list`

Tisk štítků neodeslaných objednávek `order/print-unsent-labels`

Odeslání objednávek `order/send`

Smazání objednávky `order/delete`

Archiv objednávek `order/archive`

Stav zásilek (vyhledávání) `order/search`