Co je to?

Importér, nebo též importovací API či importovací služba, je rozhraní, skrze které lze automatizovaně vytvářet objednávky přepravy v našem systému.

Jak to funguje?

Jednoduše. Náš systém vystavuje webovou službu, která umí přijmout data potřebná k vytvoření objednávky přepravy. Pokud nám dáte vědět, že chcete využívat náš importér, tuto možnost pro Vás povolíme a pak stačí jen nakonfigurovat Váš systém tak, aby voláním naší služby automaticky vytvořil objednávku ve chvíli, kdy je to potřeba.

Proces, který vede k automatickému vytvoření v našem systému pak typicky vypadá takto:

1. Ve vašem systému se odehraje událost, která vyžaduje vytvoření objednávky přepravy. Např. máte-li eshop, pak touto událostí je nejčastěji to, že si Váš zákazník přeje expresně doručit objednané zboží.
2. Váš systém automaticky, bez zásahu člověka, zavolá naší importovací službu s potřebou sadou parametrů. V případě eshopu tyto parametry Váš systém vyčte z údajů, které Váš zákazník uvedl ve formuláři pro výběr doručení.
3. V našem systému okamžitě dojde ke zpracování Vámi odeslaných dat.
   • Pokud náš systém zjistí, že Vámi poslaná data nejsou v nějakém ohledu validní, objednávku nepřijme.
   • Jsou-li Vámi poslané údaje v pořádku, systém bez prodlení pokračuje s importem.
   • Nicméně je potřeba, aby data, které nám zasíláte byly ve správném tvaru a nepřekračovaly maximální povolenou délku (viz. Tabulky o parametrech níže). To zajistí bezproblémový import dat.
   • V případě, že systém přijme vaši objednávku a některé z dat, které jsme obdrželi nebudou validní, tím pádem systém nebude schopen vytvořit objednávku, budete kontaktováni našim dispečerem (obvykle během několika minut), který ochotně pomůže vzniklý problém vyřešit.
4. Náš systém vytvoří z Vámi zadaných dat objednávku přepravy.
5. Kurýr co nejdříve vyrazí, aby Vaši objednávku vyzvedl a doručil.

Technická specifikace

Požadované parametry

Abychom mohli Vaši objednávku úspěšně vytvořit, potřebujeme znát informace nezbytné pro realizaci přepravy. Tyto informace od Vás potřebujeme ve formě parametrů, které nám pošlete při volání importovací služby.

Povinné parametry

Následující parametry jsou povinné a nesmí tedy chybět při volání importéru. Bez kterékoli z těchto hodnot nemůžeme objednávku vytvořit. Názvy a očekávané formáty jednotlivých parametrů jsou uvedeny v tabulce níže.

Nepovinné parametry

Následující parametry nejsou povinné a v některých případech nemusí být při volání služby zadány. Záleží ovšem na tom co, kam a jak rychle budete chtít přepravovat. Na tom, zda budeme vzhledem k povaze Vámi plánovaných importů potřebovat i některé z těchto nepovinných parametrů se domluvíme v průběhu procesu napojování Vašeho systému.

Formát balíků

Skrze importér je možné nahrát do našeho systému i kompletní výčet balíků, ze kterých sestává Vaše zásilka. Aby bylo možné tuto informaci jednoduše předat v jednom parametru, používáme pro reprezentaci balíků speciální formát.

U každého balíku vyspecifikujete následující parametry:

• hmotnost (kg)
• délka (cm)
• šířka (cm)
• výška (cm)

Příklad:
Máme-li dva balíky, kde u prvního známe pouze hmotnost (2 kg) a u druhého všechny parametry (hmotnost 3 kg, rozměry 30 cm x 40 cm x 20 cm), pak je zapíšeme takto:

						
2,,,;3,30,40,20;
						
					

						
2,,,,Q51615645P1;3,30,40,20,Q848646556P2;
						
					

Dostupné služby

V současnosti podporujeme několik různých způsobů, jak k nám Vaše data naimportovat.

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

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

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

Na této URL naslouchají tři služby, dvě z nich lze zavolat metodou POST (doporučovaný způsob) a jednu metodou GET (alternativní způsob).

POST

Při volání výše uvedené URL metodou POST je třeba poslat parametry v BODY daného requestu. Tělo požadavku pak může obsahovat buď JSON nebo XML .

JSON

Pokud se rozhodnete posílat nám JSON , pak tento musí splňovat následující:

• jedná se o jediný objekt
• každý parametr se v objektu vyskytuje právě jednou
• každý parametr a jeho hodnota jsou reprezentovány právě jednou dvojicí klíč : hodnota

Požadavek také musí obsahovat následující hlavičku:

						
Content-Type: application/json
						
					

Příklad těla požadavku ve formátu JSON :

						
{  
   "importKey":"lpKKWrxZyyf0CSi",
   "ulice_odkud": "Libínská",
   "cislo_domu_odkud": "3127/1",
   "mesto_odkud": "Praha 5",
   "psc_odkud": "150 00",
   "kontaktni_osoba_odkud": "Kdosi Nějaký",
   "telefon_odkud": "605 123 456",
   "ulice_kam": "Libínská",
   "cislo_domu_kam": "1",
   "mesto_kam": "Praha",
   "psc_kam": "169 00",
   "dobirka": 0,
   "typ_prepravy": 106,
   "poznamka_odkud": "Test nevozit"
}
						
					

XML

Pokud byste nám data raději posílali jako XML , pak toto XML v těle požadavku musí splňovat následující:

• kořenový element má název importData
• každý parametr a jeho hodnota jsou reprezentovány právě jedním elementem, jehož název je název parametru a který obsahuje hodnotu daného parametru
• každý element reprezentující parametr je přímým potomkem kořenového elementu
• žádný element reprezentující parametr neobsahuje vnořené elementy

Požadavek také musí obsahovat následující hlavičku:

						
Content-Type: application/xml
						
					

Příklad těla požadavku ve formátu XML :

						
<?xml version="1.0" encoding="UTF-8" ?>
<importData>
	<importKey>lpKKWrxZyyf0CSi</importKey>
	<ulice_odkud>Libínská</ulice_odkud>
	<cislo_domu_odkud>3127/1</cislo_domu_odkud>
	<mesto_odkud>Praha 5</mesto_odkud>
	<psc_odkud>150 00</psc_odkud>
	<kontaktni_osoba_odkud>Kdosi Nějaký</kontaktni_osoba_odkud>
	<telefon_odkud>605 123 456</telefon_odkud>
	<ulice_kam>Libínská</ulice_kam>
	<cislo_domu_kam>1</cislo_domu_kam>
	<mesto_kam>Praha</mesto_kam>
	<psc_kam>169 00</psc_kam>
	<dobirka>0</dobirka>
	<typ_prepravy>106</typ_prepravy>
	<poznamka_odkud>Test nevozit</poznamka_odkud>
</importData>
						
					

GET

Při volání importovací URL metodou GET je třeba poslat parametry přímo v URL daného requestu. Víme sice, že když REST služba něco vytváří, měla by být volána pouze metodou POST . To také doporučujeme. Nicméně chápeme, že tento způsob (metodou GET ) je implementačně jednodušší a snažíme se Vám vyjít maximálně vstříc. Z toho důvodu podporujeme i tuto alternativní variantu.

Příklad URL obsahují identické parametry jako JSON a XML výše:

						
https://api.messenger.cz/MessengerWeb/API/REST/public/[VYSTUPNI-FORMAT]/import/importParcel?importKey=lpKKWrxZyyf0CSi&ulice_odkud=Lib%C3%ADnsk%C3%A1&cislo_domu_odkud=3127/1&mesto_odkud=Praha5&psc_odkud=15000&kontaktni_osoba_odkud=KdosiN%C4%9Bjak%C3%BD&telefon_odkud=605123456&ulice_kam=Lib%C3%ADnsk%C3%A1&cislo_domu_kam=1&mesto_kam=Praha&psc_kam=16900&poznamka_odkud=Test_nevozit&dobirka=0
						
					

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

Alternativní možností je použití služeb, které nevyžadují HTTP Basic přihlašování a namísto toho očekávají parametry s uživatelským jménem a heslem (více o těchto službách zde).
Všechny takové importovací služby lze nalézt na adrese:

						
https://api.messenger.cz/MessengerWeb/PublicREST/[VYSTUPNI-FORMAT]/importParcel
						
					

Na této URL opět naslouchají tři služby, jsou to v podstatě tytéž, které jsme popsali výše, pouze s tím rozdílem, že nyní očekávají dva dodatečné přihlašovací parametry.

Příklady

POST - JSON

						
{  
   "customerNumber": [ZAKAZNICKE-CISLO],
   "password": [HESLO],
   "importKey":"lpKKWrxZyyf0CSi",
   "ulice_odkud": "Libínská",
   "cislo_domu_odkud": "3127/1",
   "mesto_odkud": "Praha 5",
   "psc_odkud": "150 00",
   "kontaktni_osoba_odkud": "Kdosi Nějaký",
   "telefon_odkud": "605 123 456",
   "ulice_kam": "Libínská",
   "cislo_domu_kam": "1",
   "mesto_kam": "Praha",
   "psc_kam": "169 00",
   "dobirka": 0,
   "typ_prepravy": 106,
   "poznamka_odkud": "Test nevozit"							
}
						
					

POST - XML

						
<?xml version="1.0" encoding="UTF-8" ?>
<importData>
	<customerNumber>[ZAKAZNICKE-CISLO]</customerNumber>
	<password>[HESLO]</password>
	<importKey>lpKKWrxZyyf0CSi</importKey>
	<ulice_odkud>Libínská</ulice_odkud>
	<cislo_domu_odkud>3127/1</cislo_domu_odkud>
	<mesto_odkud>Praha 5</mesto_odkud>
	<psc_odkud>150 00</psc_odkud>
	<kontaktni_osoba_odkud>Kdosi Nějaký</kontaktni_osoba_odkud>
	<telefon_odkud>605 123 456</telefon_odkud>
	<ulice_kam>Libínská</ulice_kam>
	<cislo_domu_kam>1</cislo_domu_kam>
	<mesto_kam>Praha</mesto_kam>
	<psc_kam>169 00</psc_kam>
	<dobirka>0</dobirka>
	<typ_prepravy>106</typ_prepravy>
	<poznamka_odkud>Test nevozit</poznamka_odkud>
</importData>
						
					

GET

						
https://api.messenger.cz/MessengerWeb/PublicREST/[VYSTUPNI-FORMAT]/importParcel?customerNumber=[ZAKAZNICKE-CISLO]&password=[HESLO]&importKey=lpKKWrxZyyf0CSi&ulice_odkud=Lib%C3%ADnsk%C3%A1&cislo_domu_odkud=3127/1&mesto_odkud=Praha5&psc_odkud=15000&kontaktni_osoba_odkud=KdosiN%C4%9Bjak%C3%BD&telefon_odkud=605123456&ulice_kam=Lib%C3%ADnsk%C3%A1&cislo_domu_kam=1&mesto_kam=Praha&psc_kam=16900&poznamka_odkud=Test_nevozit&dobirka=0
						
					

Výstupní hodnoty

Všechny importovací služby vrací stejná data nezávisle na tom jakou variantu importu používáte. Interně mají všechny importovací služby na svém výstupu objekt stejného typu, jen jej serializují buď do formátu JSON nebo XML , podle Vaší volby. Jediná výjimka nastáva v případě, že používáte přihlašování pomocí HTTP Basic a zadáte nesprávné přihlašovací údaje. V tomto případě vám server vrátí status 401 Unauthorized.

Výstupní parametry

Z každé naší imporovací služby tedy obdržíte následující sadu parametrů:

JSON

Pokud si zvolíte jako výstupní formát JSON (což se dělá takto), pak bude výstup služby při úspěšném importu vypadat takto:

						
{  
   "importResult":{  
      "success":true,
      "authentification":{  
         "success":true
      },
      "importKey":{  
         "success":true
      },
      "pairs":{  
         "success":true
      },
      "ids": [
          123456
      ],
      "trackingCodes": [
          "D8E65863213BC18"
      ],
      "trackingURL": "https://tracking.messenger.cz/consignment/D8E65863213BC18"
   }
}
						
					

XML

Pokud si zvolíte jako výstupní formát XML (což se dělá takto), pak bude výstup služby při úspěšném importu vypadat následovně:

						
<?xml version="1.0" encoding="UTF-8"?>
<importResult>
   <success>true</success>
   <authentification>
      <success>true</success>
   </authentification>
   <importKey>
      <success>true</success>
   </importKey>
   <pairs>
      <success>true</success>
   </pairs>
   <ids>123456</ids>
   <trackingCodes>D8E65863213BC18<trackingCodes>
   <trackingURL>https://tracking.messenger.cz/consignment/D8E65863213BC18<trackingURL>							
</importResult>