ProfiTour XML Interface
Seznam číselníků:Ciselniky.asmx
Export dat:
Export.asmx
Akce:
Akce.asmx
Dokumentace:
Online verze
FAQ:
Odpovědi na často kladené otázky - sem byste se opravdu měli podívat, než začnete rozhraní implementovat.
Novinky a změny
• 11.7.2024Do metod Hledani, HledaniFlat, HledaniMini a Dostupnost byl přidán parametr DatumOdMax.
• 15.7.2016
Při založení nové objednávky lze u objednatele vyplnit id_Pohlavi (pouze hodnotami "M" nebo "F"), což zajistí automatické vložení klienta do ProfiAgent. Přibyl také číselník Ciselniky.asmx/Pohlavi.
• 13.6.2015
Systém byl rozšířen o možnost kalkulovat zájezdy bez ubytování. Nemění se signatura žádné metody, pouze začaly fungovat kalkulace i na zájezdy, které neobsahují žádné ubytování.
• 11.2.2015
Byla přidána nová metoda Export.asmx/AktivniStredisko, která vrací seznam ID všech středisek obsahujících aktivní termíny podle zadaných kritérií.
• 10.6.2014
Systém transferů byl předělán na systém svozů. V souvislosti s tím došlo ke změně názvů tříd, vlastností, příslušného číselníku i parametrů.
Ciselniky.asmx/TransferMisto -> Ciselniky.asmx/SvozMisto
TransferMistoConstItem -> SvozMistoConstItem
TransferMistoConstList -> SvozMistoConstList
TransferMisto -> SvozMisto, současně je id_TransferMisto a str_TransferMisto nahrazeno za id_SvozMisto a str_SvozMisto.
TransferTrasa -> Svoz, současně je id_TransferMisto a str_TransferMisto nahrazeno za id_SvozMisto a str_SvozMisto a odebráno ID (do kalkulace se předává id_SvozMisto) i Nazev (zobrazovat se má str_SvozMisto). Cena už není Nullable/XmlElement, ale přímo atribut.
ZajezdTermin/TransferTrasa -> ZajezdTermin/Svozy
ZajezdVysledek/TransferMisto -> ZajezdVysledek/SvozMisto
Export.asmx/Kalkulace a Export.asmx/KalkulaceFlat: Vstupní parametr id_TransferTrasa je nahrazen za id_SvozMisto.
• 30.5.2014
Parametr id_Republika v metodě Export.asmx/Hledani byl upraven z pole stringů na jeden string.
• 3.7.2013
Metoda Akce.asmx/Objednavka má nový parametr URL, do kterého je možné odeslat aktuální URL adresu, na které byla objednávka vyplněna. Adresa je potom předána do notifikačního emailu a objednávky, aby se prodejce mohl snadno dostat k termínu, který klient objednal.
• 26.7.2012
Ve všech metodách, kde se vyskytují atributy CenaOd, PriplatkyOd a CenaCelkemOd jsou nově k dispozici i hodnoty CenaOdKatalog, PripaltkyOdKatalog a CenaCelkemOdKatalog s původními cenami před použitím slev. Pokud jsou původní katalogové ceny k dispozici, jinak budou hodnoty stejné jako aktuální ceny.
• 21.5.2012
Metoda Export.asmx/Dostupnost umožňuje pomocí parametru Typ=Vse zjistit cekovou statistiku dostupných zájezdů, termínů atd.
• 6.5.2012
Ke každému obrázku přibyl kromě náhledu velikosti 120x90 ještě náhled 200x140.
• 21.12.2011
Byla přidána metoda Export.asmx/Pocasi a její Flat verze Export.asmx/PocasiFlat zobrazující předpověď počasí pro požadovaný seznam států nebo oblastí.
• 6.6.2011
Byla přidána metoda Export.asmx/Dostupnost jako náhrada čtyř původních metod dostupnosti. Nová metoda umožňuje filtrovat termíny podle více kritérií. Metody Export.asmx/DostupnostOblasti, DostupnostStaty, DostupnostStrediska, DostupnostTypZajezdKategorie budou odstraněny v příštím releasu.
• 22.6.2010
Slavnostní zahájení provozu v tichosti a bez účasti veřejnosti :)
Často kladené otázky
Kde začít?
Pro volání metod musíte mít přiděleno ID organizace, které se používá jako jeden ze vstupních parametrů každé metody. Bez tohoto parametru vrací metody chybu "Access denied".XML rozhraní neslouží pro přenos celé DB na Váš server, ale jako back-end datový zdroj namísto DB. Čili každé otevření stránky na Vašem webu by mělo zavolat alespoň jednu metodu XML rozhraní (kromě případu, kdy máte výsledek již uložen v cache).
Každá metoda vrací generický datový typ Result(Of ResultType), který reprezentuje obecný výsledek metody. Ten může obsahovat elementy:
<Error>Text chyby, který by neměl být zveřejněn</Error> - zpravidla chybné vstupní parametry, nebo interní chyba XML rozhraní.
<Message>Text chyby, který by měl být zobrazen návštěvníkovi</Message> - informace o neaktivních termínech, nedostupných kalkulacích apod.
<Data>XmlNode reprezentující výstupní data metody.</Data>
Při přítomnosti/vyplnění hodnoty Error nebo Message ve výstupu metody je hodnota Data vždy prázdná a nemá smysl ji zpracovávat.
Jaká je posloupnost metod?
Udělejte si krátký přehled o dostupných číselnících Ciselniky.asmx a hodnotách, které vracejí a významu vstupího parametru VypsatNazvy (viz níže).Úvodní metodou je zpravidla Export.asmx/HotTipy, ze které se pokračuje na detail zájezdu nebo termínu.
Dále Export.asmx/Hledani, která slouží pro zobrazení výsledků vyhledávání i seznamu zájezdů v katalogu. Z výsledků se pokračuje na detail zájezdu nebo termínu.
Detail zájezdu lze získat metodou Export.asmx/Zajezd, úplný popis všech hotelů pak metodou Export.asmx/Hotel a detail dostupných výletů metodou Export.asmx/Vylet.
Detail termínu lze získat metodou Export.asmx/ZajezdTermin. Jako vstupní parametr je ale potřeba seznam hotelů zájezdu z metody Export.asmx/Zajezd.
Na základě informací z detailu termínu lze sestavit vstupní parametry pro metodu Export.asmx/Kalkulace obsahující detail ceníku a poznámku.
Pro uložení objednávky slouží metoda Akce.asmx/Objednavka.
Jak funguje parametr VypsatNazvy?
Každá metoda služby Export.asmx obsahuje vstupní parametr VypsatNazvy typu boolean:1) VypsatNazvy = True
V tomto režimu bude výstup XML pro každý atribut ID z číselníku id_NazevCiselniku doplněna textová hodnota str_NazevCiselniku. Např. při výskytu atributu id_Doprava="40" bude výstup XML doplněn o str_Doprava="letecká". Podobně pro všechny ostatní číselníky, s výjimkou číselníku republik.
Použití této varianty je jednodušší na implementaci, ale je přenášen větší objem dat. Režim je vhodný pro menší weby.
2) VypsatNazvy = False
V tomto reřimu jsou ve výstupním XML uvedena pouze ID z číselníků, bez výpisu textové verze.
Použití této varianty je složitější na implementaci, protože vyžaduje implementaci cache na hodnoty číselníků, ale je přenášen menší objem dat a komunikace mezi aplikacemi je tak efektivnější. Režim je vhodné využít pro weby s větší návštěvností.
HTTP GET - Jak se správně sestavuje URL?
Pod každým testovacím formulářem (např. http://xml.profitour.sk/Export.asmx?op=HotTipy) jsou uvedeny příklady pro všech možností volání, včetně HTTP GET. URL musí obsahovat všechny parametry, které obsahuje testovací formulář, např:http://xml.profitour.sk/Export.asmx/HotTipy?id_Organizace=1&id_Jazyk=sk&VypsatNazvy=True&id_Republika=sk
(Tato ukázka vrátí chybu Access denied, použijte hodnotu id_Organizace, které Vám bylo přiděleno při aktivaci služby.)
Co znamená 1:1, 1:N a skupina ve vztahu zájezdu a hotelů?
Jeden zájezd může obecně obsahovat program zahrnující pobyt ve více hotelech (pobytovo-poznávací zájezdy, plavby, exotické zájezdy s pobytem na více ostrovech a pod.). Tyto jsou v dokumentaci označovány jako 1:N. Většina zájezdů ale obsahuje právě jeden hotel (obyčejné pobytové zájezdy) a ty jsou označovány jako 1:1.Textový popis, obrázky a seznam vybavení může být uveden jak u samotného zájezdu (např. program společný pro celý poznávací zájezd), tak u některého z hotelů, nebo u všech hotelů samostatně. V případě zájezdů 1:1 je popis uveden zpravidla u hotelu a popis zájezdu zůstává prázdný.
U zájezdů 1:N mohou být hotely zájezdu rozděleny do skupin. Např. Thajsko a zájezd Bangkok - Pattaya - Ko Samet: klient v tomto případě tráví jednu noc v Bangkoku, poté několik dní v Pattaya a několik dní v Ko Samet, dle popisu zájezdu. Na každém z těchto ostrovů je ale na výběr z několika hotelů, klient si musí vybrat ve kterých hotelech chce být ubytován, ale nemůže si vybrat libovolnou kombinaci.
Hotely zájezdu mohou (ale nemusí - u triviálních zájezdů, kde klient navštíví vždy všechny přítomné hotely a nemusí si tedy vybírat) být rozděleny do těchto skupin a vybraná kombinace musí obsahovat vždy pouze jedinou skupinu, čili nelze současně vybrat hotel ze skupiny 1 a na jiném ostrově hotel ze skupiny 3. Speciální význam má nevyplněná hodnota skupiny - takový hotel lze kombinovat s libovolnou skupinou.
V případě, že zájezd obsahuje více skupin si klient musí vybrat kombinaci hotelů. Při výběru navíc musí z dané skupiny obsadit všechna dostupná pořadí. (Např. u Bangkok - Pattaya - Ko Samet musí vybrat jeden z hotelů s pořadím 1 (Bangkok), jeden hotel s pořadím 2 (Pattaya) a jeden hotel s pořadím 3 (Ko Samet). Žádné dostupné pořadí nesmí zůstat neobsazeno.
Zvolený seznam se pak používá jako vstupní parametr pro metodu Export.asmx/ZajezdTermin, která poskytuje dodatečné informace potřebné pro zjištění všech vstupních parametrů metody Export.asmx/Kalkulace.