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.

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.

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ů.

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

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:

Formát jednotlivých objektů

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

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ů:

Stavy zásilek

Typy zásilek