O co jde?

Zásilky v průběhu přepravy mění své stavy. Tracking Vám umožní mít vždy aktuální stav ve svém systému. Nemusíte tak pro kontrolu navštěvovat náš systém a také můžete na změnu stavu zásilky například upozornit zákazníka.

Jak to funguje?

Jednoduše. Libovolným způsobem k nám do systému nahrajete své zásilky (přes webové stránky, pomocí importovací API, ...). Poté máte dvě možnosti. První variantou je, že při jakékoliv změně stavu zásilky náš systém zavolá Vaše API , které obdrží informaci o změně. Jedná se tedy z naší strany o proaktivní způsob, kdy náš systém informuje vás v okamžiku vzniku události. Druhou možností je zavolat naší službu, která Vám vrátí informace o stavech Vašich zásilek.

Technická specifikace

1. Náš systém volá Vaše API

Náš systém volá Vaše API , kde oznamuje u jaké konkrétní zásilky se změnil stav. Na Vaší straně nám prosím oznamte úspěch či selhání nahlášení změny pomocí stavového kódu v odpovědi (více o stavových kódech zde). Za úspěšné nahlášení považujeme libovolný kód v rozmezí 200-299.

Jak se to nastavuje?

Velmi jednoduše. Nejprve si připravíte službu ve Vašem API a její URL nám zašlete společně s formátem dat, který očekává. To je vše.

Výstupní parametry

Při hlášení změny stavu zásilky Vám zašleme následující sadu parametrů. Tato sekce popisuje význam jednotlivých polí. Konkrétní příklady ve formátech JSON a XML naleznete níže.

Parametr Vnořený parametr Formát Hodnota Popis
routeStateTracking id celé číslo Naše ID zásilky. Náš identifikátor zásilky. Jedná se o stejné ID, které jste od nás obdrželi při importování zásilky pomocí importovacího API.
code text Vaše ID zásilky. Kód zásilky můžete zadat během importování (viz nepovinné parametry zde), při objednávce na našich webových stránkách nebo při objednávce po telefonu.
stateId celé číslo ID stavu zásilky ID stavu slouží pro jednoznačnou identifikaci stavu. Výčet jednotlivých stavů naleznete zde.
stateName text název stavu zásilky Textový název stavu zásilky. Výčet jednotlivých stavů neleznete zde.
typeId celé číslo ID typu zásilky Typ zásilky slouží pro rozlišení toho, jestli se jedná o normální cestu kurýra, nebo třeba o opakované doručení nebo vratku. Výčet jednotlivých typů naleznete zde.
time text ve formátu YYYY-MM-DD'T'hh:mm:ssTZD datum a čas změny stavu Formát YYYY-MM-DD'T'hh:mm:ssTZD representuje například text 2016-04-08T13:16:26+02:00. Více informací o formátu naleznete zde.
description text Popis změny stavu. V popisu změny stavu se typicky vyskytují dodatečné informace o změně. Například komu byla zásilka doruřena, od koho byla převzata apod.
routeId celé číslo Naše ID cesty v zásilce. Náš identifikátor cesty v zásilce. Pomocí něho se dají rozlišit třeba stavy zpátečky v zásilce.

Podporované služby

Podporujeme dvě metody, kterými Vám můžeme předat data. První je předání dat ve formátu JSON a druhou je formát XML . Až nám budete dávat URL adresu, kam máme data posílat, tak nám prosím sdělte i formát, jaký chcete dostávat. Struktura zasílaných dat je identická pro obě metody.

JSON

Na Vaší službu API provedeme HTTP POST požadavek s hlavičkou označující data ve formátu JSON . V těle požadavku naleznete vlastní data.

						
Content-Type: application/json
						
					
						
{  
   "id":1500661,
   "code":"X456987",
   "stateId":7,
   "stateName":"stornována",
   "time":"2016-04-08T13:16:26+02:00",
   "description":""
}
						
					

XML

Na Vaší službu API provedeme HTTP POST požadavek s hlavičkou označující data ve formátu XML . V těle požadavku naleznete vlastní data.

						
Content-Type: application/xml
						
					
						
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<routeStateTracking>
    <id>1500661</id>
    <code>X456987</code>
    <stateId>7</stateId>
    <stateName>stornována</stateName>
    <time>2016-04-08T13:16:26+02:00</time>
    <description></description>
</routeStateTracking>
						
					

2. Naše API

Zároveň kdykoliv můžete zavolat naše služby, které Vám vrátí informace o stavech Vašich zásilek.

Požadované parametry

Abychom Vám mohli poskytnout informace, které chcete, potřebujeme od Vás několik málo údajů.

Parametr Očekávaný formát Očekávaná hodnota Popis
orderIds pole čísel čísla objednávek, pro které chcete zjistit stavy Protože se jedná o pole a službu můžete volat metodou GET, je nutné v tomto případě parametr zopakovat tolikrát, kolik čísel objednávek do služby chcete poslat.

Dostupné služby

V současnosti podporujeme několik různých způsobů, jak naše služby zavolat

Služby s HTTP přihlašováním

Preferovanou variantou je volání jedné z trackovacích služeb, která využívá HTTP Basic přihlašování (více o těchto službách zde).
Tuto službu lze nalézt na adrese:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/data/trackOrders
						
					

Službu lze volat metodou GET, kde je potřeba předat parametry přímo v URL a metodou POST, kde parametry ve formátu JSON obsahuje tělo požadavku. Pro vyšší počty zásilek je doporučeno použít POST.

Příklad volání GET:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/data/trackOrders?orderIds=123456&orderIds=987654
						
					

Příklad volání POST:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/data/trackOrders
						
					

Příklad JSON pro POST:

						
	{
		"orderIds": [
			"123456","987654"
		]
	}
						
					

Služby bez HTTP přihlašování

Alternativní variantou je volání služby, která namísto HTTP Basic přihlašování přebírá přihlašovací parametry.
Tuto službu lze nalézt na adrese:

						
https://api.messenger.cz/MessengerWeb/PublicREST/data/trackOrders
						
					

Službu lze volat také metodou GET, kde je potřeba předat parametry přímo v URL a metodou POST, kde parametry ve formátu JSON obsahuje tělo požadavku. Pro vyšší počty zásilek je doporučeno použít POST.

Příklad volání GET:

						
https://api.messenger.cz/MessengerWeb/PublicREST/data/trackOrders?customerNumber=[ZAKAZNICKE-CISLO]&password=[HESLO]&orderIds=123456&orderIds=987654
						
					

Příklad volání POST:

						
https://api.messenger.cz/MessengerWeb/PublicREST/data/trackOrders
						
					

Příklad JSON pro POST:

						
		{
			"orderIds": [
				"123456","987654"
			],
			"customerNumber":[ZAKAZNICKE-CISLO],
			"password": "[HESLO]"
		}
						
					

Hodnoty přihlašovacích parametrů

V příkladu výše je potřeba nahradit [ZAKAZNICKE-CISLO] a [HESLO] za Vaše přihlašovací údaje.

Výstupní parametry

Pokud vše proběhne jak má, server Vám vrátí status 200 OK a parametry v následujícím formátu:

Parametr Formát Hodnota Popis
orders pole objektů jednotlivé objednávky a jejich stavy Čísla objednávek a informace k jejich stavům.
dataErrors pole textových hodnot chybové hlášky Případné chybové hlášky týkající se hodnot jednotlivých parametrů.

Formát jednotlivých objektů

Pro všechny Vámi zadané objednávky Vám vrátíme tyto informace:

Parametr Vnořený parametr Formát Hodnota Popis
orderId celé číslo Číslo objednávky Číslo Vaší objednávky, pro kterou jsme zjistili jednotlivé stavy.
code text Vaše ID zásilky. Kód zásilky můžete zadat během importování (viz nepovinné parametry zde), při objednávce na našich webových stránkách nebo při objednávce po telefonu.
states stateId celé číslo ID stavu zásilky ID stavu slouží pro jednoznačnou identifikaci stavu. Výčet jednotlivých stavů naleznete zde.
stateName text název stavu zásilky Textový název stavu zásilky. Výčet jednotlivých stavů neleznete zde.
typeId celé číslo ID typu zásilky Typ zásilky slouží pro rozlišení toho, jestli se jedná o normální cestu kurýra, nebo třeba o opakované doručení nebo vratku. Výčet jednotlivých typů naleznete zde.
timestamp celé číslo čas provedení akce Jedná se o univerzální reprezentaci času, kde hodnota udává počet milisekund od 00:00 1.1.1970
description text Popis změny stavu. V popisu změny stavu se typicky vyskytují dodatečné informace o změně. Například komu byla zásilka doručena, od koho byla převzata apod.
routeId celé číslo Naše ID cesty v zásilce. Náš identifikátor cesty v zásilce. Pomocí něho se dají rozlišit třeba stavy zpátečky v zásilce.

Parametr states

Toto pole může obsahovat několik záznamů s výše zmíněnými parametry. Jedná se o výčet všech stavů k dané zásilce.

Formát výstupních parametrů v případě úspěchu

Data se vráti ve formátu JSON a například pro dvě zásilky mohou vypadat takto:

						
{
    "orders": [
        {
            "orderId": 1234567,
            "code": "",
            "states": [
                {
                    "stateId": 1,
                    "stateName": "přijata",
                    "typeId": 1,
                    "timeStamp": 1645173600000,
                    "description": "",
                    "routeId": 321654321
                },
                {
                    "stateId": 2,
                    "stateName": "přiřazena",		
                    "typeId": 1,
                    "timeStamp": 1645173600000,
                    "description": "Kurýr(999) Kdosi Nějaký",
                    "routeId": 321654321
                },
                {
                    "stateId": 3,
                    "stateName": "vyzvednuta",
                    "typeId": 1,
                    "timeStamp": 1645173660000,
                    "description": "DEPO",
                    "routeId": 321654321
                }
            ]
        },
        {
            "orderId": 9876543,
            "code": "",
            "states": [
                {
                    "stateId": 1,
                    "stateName": "přijata",		
                    "typeId": 1,
                    "timeStamp": 1645188240000,
                    "description": "",
                    "routeId": 456123789
                },
                {
                    "stateId": 2,
                    "stateName": "přiřazena",
                    "typeId": 1,
                    "timeStamp": 1645188240000,
                    "description": "Kurýr(9999) Kdosi Nějaký",
                    "routeId": 456123789
                }
            ]
        }
    ],
	"dataErrors": [],
}
						
					

Formát výstupních parametrů v případě neúspěchu

Může se stát, že něco neproběhne v pořádku a může se Vám vrátit některý z následujících kódů:

Kód Popis
400 Bad Request Nenalezeny žádné objednávky k zadaným id.
401 Unauthorized Neplatné přihlašovací údaje
413 Request Entity Too Large Příliš mnoho dotazovaných id objednávek.
429 Too Many Requests Přesažen limit maximálního počtu volání naší služby za minutu.

Stavy zásilek

ID Název Popis
1 přijata Přijatá objednávka.
2 přiřazena Objednávka je přiřazena určitému kurýrovi. Není vyzvednutá, doručená, stornovaná atp.
3 vyzvednuta Objednávka již byla vyzvednuta kurýrem.
4 doručena Objednávka byla kurýrem doručena.
5 nedoručena Nepodařilo se doručit objednávku - nedoručena (např. klient nezastižen a znovu se již doručovat nebude)
6 uzavřena Konečný stav objednávky.
7 stornovaná Zrušená bez doručení.
8 chyba
9 marné doručení Nepodařilo se doručit objednávku. Zákazník nebyl zastižen. V budoucnu bude pokus o znovudoručení.
10 odmítl převzít Záskazník byl zastižen, ale nechtěl či odmítnul objednávku převzít.
11 nešlo vyzvednout Nebyla zastižena osoba, která měla zásilku předat.
12 fakturovaná Cesta byla vyfakturovaná.
13 odebrána z faktury Cesta byla vyfakturovaná a poté odebrána z faktury
14 odebrána Objednávka je odebrána určitému kurýrovi. Není vyzvednutá, doručená, stornovaná atp.
15 doručena do depa Zásilka byla doručena do depa.
16 vyzvednuta z depa Zásilka byla vyzvednuta z depa a je doručována kurýrem.
17 v procesu Zásilka je v procesu doručování k adresátovi.
18 vrací se zpět Zásilka se vrací odesílateli, protože se ji nepodařilo doručit.

Typy zásilek

ID Název Popis
1 normální zásilka Výchozí typ zásilky.
2 marné vyzvednutí Zásilku se nepodařilo vyzvednout, kurýr tedy jede k vyzvednutí opakovaně.
3 marné doručení (jiná adresa) Zásilku se nepodařilo doručit, kurýr ji tedy doručuje na nově zadanou adresu.
4 marné doručení (později) Zásilku se nepodařilo doručit, kurýr ji tedy zkouší doručit znovu na původní adresu.
5 interní stav
6 interní stav
7 asistence Speciální cesta kurýra kvůli asistenci u objednávky.
8 hotovost Speciální cesta kurýra pro vyzvednutí hotovosti.
9 vratka Zásilka se vrací odesílateli, protože se ji nepodařilo doručit.