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?

Je to jen příklad...

Výše uvedený příklad je samozřejmě jen ilustrační. Nemusíte mít zrovna eshop, můžete často posílat třeba důležité dokumenty. Odvezeme prakticky cokoliv.

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.

Kopie 1:1

Jak už jsme zmínili, testovací rozhraní je přesnou kopií rozhraní produkčního. Dále v tomto textu budeme pro zjednodušení odkazovat na jednotlivé služby vždy jen pomocí URL na produkční rozhraní.
Mějte ovšem na paměti, že každá naše služba má svou kopii na rozhraní testovacím a pro testování tedy stačí zaměnit https://api.messenger.cz za https://api-test.messenger.cz.

Produkční rozhraní

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

							
https://api.messenger.cz/
							
						
Služby vystavené na této doméně jsou napojeny na produkční server, který vytváří "ostrá" data nad produkční databází. U API na této doméně je proto předpokládána vysoká dostupnost.

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.

Produkční API vytváří ostrá data

Pamatujte, že voláním produkčního API vytváříte reálnou objednávku, která má z našeho pohledu stejnou váhu jako kdybyste ji vytvořili třeba po telefonu. Dejte proto pozor, abyste pro vytváření testovacích dat používali výhradně testovací rozhraní.

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.

Přihlášení potřebujeme vždy

Námi používaný koncept REST rozhraní vyžaduje, aby každý požadavek na náš server obsahoval přihlašovací údaje. Architektura typu REST je ze své podstaty "bezestavová", tudíž si náš systém nemůže "pamatovat" Vaše přihlášení a je třeba posílat Vaše uživatelské jméno a heslo spolu s každým požadavkem.

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:

Parametr Očekávaný formát Očekávaná hodnota Popis
customerNumber celé číslo Vaše zákaznické číslo Slouží jako přihlašovací jméno.
password text Vaše heslo

I tento způsob je bezpečný

Přihlášení pomocí parametrů je stejně bezpečné jako přihlášení pomocí HTTP Basic. Sama o sobě není ani jedna z těchto metod bezpečná, ale pokud voláte naše služby pomocí HTTPS (což je doporučovaný způsob), je celá komunikace šifrovaná a tím pádem o své přihlašovací údaje nemusíte mít strach.

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
						
					

Zjednodušení

Pro jednoduchost budeme v tomto textu při uvádění URL ke službám vracejícím strukturovaná data vždy používat [VYSTUPNI‑FORMAT] pro označení té části URL, která specifikuje výstupní formát.