Co to vlastně je?

Naše API je souborem několika různých webových služeb, které umožňují přímé propojení systémů našich zákazníků s naším interním systémem. Tímto způsobem je možné automatizovat nejrůznější činnosti od objednání přepravy přes tisk štítků na balíky až po přijetí informace o doručení objednávky.

Příklad použití

Pokud Vám zatím není úplně jasné co propojení systémů prináší, představte si následující příklad:

Jste provozovatel eshopu a chcete svým zákazníkům dopřát rychlé doručení kurýrní společností. Na svém webu tedy v možnostech přepravy nabízíte Messenger jako jednu z možností. Pokud si Váš zákazník tuto možnost vybere a vy nemáte napojený Váš systém na naše služby, musíte nám dát nějak vědět, že máme převézt zboží od Vás k Vašemu zákazníkovi.

Můžete nám tedy buď zavolat nebo vytvořit objednávku na webu. Jedno i druhé ale vyžaduje něčí čas a práci. Pokud ovšem napojíte Váš systém přímo na náš pomocí zde popsaného API, pak ihned potom co u Vás zákazník nakoupí, může Váš systém zcela automaticky a bez práce objednat přepravu kurýrem od Vás k zákazníkovi. Dobré, že?

Popis rozhraní

Všechny naše služby popsané na těchto stránkách jsou typu REST, jedná se tedy o webové služby, které lze zavolat pomocí HTTP protokolu. Věříme, že díky jednoduchosti konceptu REST služeb pro Vás bude implementace snadná a bezproblémová.

Umístění služeb

Naše služby jsou dostupné na dvou rozdílných doménách, jedna vede na testovací a jedna na produkční prostředí. Služby na obou doménách je možné volat pouze šifrovaným zůsobem přes HTTPS.

Testovací rozhraní

Pro začátek je asi nejdůležitější testovací rozhraní. Jedná se přesnou kopii toho produkčního ovšem je napojeno na testovací server. Toto prostředí poskytujeme především proto, abyste Vy - naši zákazníci - mohli v klidu zkoušet integraci našeho API. Na testovací služby tedy můžete posílat prakticky libovolná data a zkoušet, zda komunikace mezi Vaším a naším serverem probíhá bez problémů.

Testovací rozhraní je dostupné na doméně

						
https://api-test.messenger.cz/
						
					

Nepředpokládáme, že by toto rozhraní měl kdokoli dlouhodobě používat. Po úspěšném napojení na naše služby je typicky žádoucí v co nejkratším čase přejít na produkční rozhraní a začít naše služby skutečně naplno využívat. Z tohoto důvodu negarantujeme u testovacího rozhraní vysokou dostupnost a lze očekávat příležitostné výpadky.
Testovací server běží proti databázi, která je kopií databáze produkční a každé ráno se z ní replikuje, takže i testovací verze poskytuje "čerstvá" data.

Produkční rozhraní

Produkční rozhraní je dostupné na doméně

							
https://api.messenger.cz/
							
						

Vzhledem k tomu, že produkční a testovací verze rozhraní jsou zcela identické, je běžné a žádoucí, aby se komunikace mezi servery odladila na testovací verzi a pak jen změnou volané adresy z https://api-test.messenger.cz na https://api.messenger.cz došlo k přepnutí na produkční verzi.

Služby s přihlášením

Prakticky všechny naše webové služby vyžadují přihlášení, abychom věděli s kým komunikujeme. Podporujeme dvě možnosti předávání přihlašovacích údajů, které jsou níže detailně rozebrány.

HTTP Basic

Preferovanou variantou je použití HTTP Basic přihlašování. Tento přístup ve zkratce využívá hlavičky HTTP požadavku, pomocí kterých předá našemu serveru Vaše uživatelské jméno a heslo. Ten je pak z těchto hlaviček vyčte a pomocí uvedených údajů Vás přihlásí.

Všechny naše služby využívající tento způsob přihlášení jsou vystaveny na URL začínající takto:

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

Zbytek této adresy se různí podle toho v jakém formátu si přejete vrátit odpověď (JSON nebo XML) a také podle toho, kterou konkrétní službu chcete volat.

Přihlášení pomocí parametrů

Jako alternativu k výše popsanému způsobu přihlašování Vám také umožňujeme posílat přihlašovací údaje přímo jako parametry volané metody. Tento způsob podporujeme částečně kvůli zpětné kompatibilitě našeho API a také proto, že je implementačně jednodušší.

Všechny naše služby využívající tento způsob přihlášení jsou vystaveny na URL začínající takto:

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

Zbytek této adresy se opět různí podle toho v jakém formátu si přejete vrátit odpověď (JSON nebo XML) a také podle toho, kterou konkrétní službu chcete volat.

Dodatečné parametry

Pro úspěšné volání kterékoli naší služby s využitím přihášení pomocí parametrů je potřeba do dané služby navíc ke všem povinným parametrům připojit ještě další parametry, konkrétně tyto:

Výstupní formáty

Pro Vaše pohodlí podporujeme různé výstupní formáty, volba je jen na Vás.

Podporované formáty

Většina našich služeb vrací strukturovaná data. Taková data však lze reprezentovat různým způsobem. Protože Vás nechceme omezovat, tak všechny naše služby, která vrací strukturovaná data, umí vrátit buď JSON nebo XML.

Výběr formátu

Výběr Vámi preferovaného formátu je jednoduchý, stačí jen zvolit správnou URL. Každá služba, která umí více než jeden výstupní formát, je dostupná na dvou různých URL. Ty jsou vždy identické až na jednu konkrétní část, která specifikuje požadovaný formát.

Příklad

Vezměme si třeba službu pro import zásilek. Ta je dostupná na adrese:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/[VYSTUPNI-FORMAT]/import/importParcel
						
					

Část OUTPUT-FORMAT je potřeba nahradit za výstupní formát, který preferujete, tj. buď JSON nebo XML.

Chcete-li dostat na výstupu JSON, zavoláte následující URL:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/JSON/import/importParcel
						
					

Pokud si přejete dostat na výstupu XML, je potřeba zavolat následující URL:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/XML/import/importParcel