ProfiTour ProfisXML Interface

Seznam služeb:
Dokumentace:
Online verze

FAQ :
Často kladené otázky - sem byste se opravdu měli podívat, než začnete rozhraní implementovat.

Informace

Rozhraní je implementováno jako .NET WCF. Pro každou službu je k dispozici basicHttpBinding s XML/SOAP serializací a netHttpBinding pro binární formát dat. Oba bindingy jsou k dispozici jako http i https. Služby lze připojovat jednotlivě podle potřeby, nebo společnou službou Profis.svc, která obsahuje metody ze všech ostatních služeb dohromady.

Před začátkem implementace si od CK vyžádejte tyto hodnoty pro každou republiku a jazykovou mutaci webu:
  • UzivatelLogin,
  • UzivatlHeslo,
  • id_Jazyk,
  • id_Republika,
  • id_Organizace.
Na straně serveru dochází ke zpětně kompatibilním úpravám struktury a WSDL bez předchozího upozornění, klient služby musí být proti těmto změnám odolný a případně komunikovat podle původního WSDL. Zpětně nekompatibilní úpravy budou vydány jako nová verze. Stará verze zůstane v provozu.
Typy zpětně kompatibilních změn:
  • Přidání nového parametru metody (na začátek, doprostřed i na konec).
  • Odebrání parametru metody.
  • Přidání nové položky do vstupního objektu metody (na začátek, doprostřed i na konec).
  • Odebrání položky ze vstupního objektu metody.
  • Přidání nové metody.
  • Přidání nové položky do výstupního objektu metody (na začátek, doprostřed i na konec).
  • Odebrání položky z výstupního objektu metody.
Dokumentace a názvy v chybových hláškách se udržují pouze pro aktuální verzi. Pro starší verze není dokumentace k dispozici.

Novinky a změny

Přechod z verze 0 (WebServices, .asmx) na verzi 1 (WCF, .svc)

Společné změny

  • Nové bindingy lze volat pouze jako basicHttpBinding (Xml/Soap) nebo netHttpBinding (binární). Volání GET již není možné.
  • Hodnoty z číselníku ve tvaru id_Xxx a str_Xxx jsou reprezentovány objekty IntegerNazev a StringNazev ve tvaru Xxx s položkami Xxx.ID a Xxx.Nazev.
  • V XML serializaci se již nepoužívají atributy.
  • Vstupní i výstupní objekty můžou používat alternativní datové typy pro stejnou položku nebo parametr (AdresaDomaciInput vs. AdresaZahranicniInput).
  • Opakující se vstupní parametry byly sloučeny do Context objektů.
  • Result(Of ResultType) je nyní předek Result, obsahující Message.
  • Result.Error bylo zrušeno a nahrazeno za Fault.
  • Result.Data se obvykle nadále jmenuje Data, ale nemusí. Může obsahovat i více různých položek s výstupními daty.
  • DataItem.Extra je Base.Externi
  • Metody s větším počtem vstupních parametrů mají parametry sloučené do strukturovaného typu.
  • Seznamy byly často přejmenovány na množné číslo (Popis -> Popisy).
  • Rozdělení náhledů obrázků bylo přejmenováno z Nahled.ID na Nahled.id_ObrazekFormat.
  • Výstupy metod v co nejvyšší míře používají dědičnost a opakující se objekty.
  • Přidání nových metod a nových funkcí z Online.asmx atd.

Přesuny metod - Ciselniky.asmx

  • Všechny číselníky byly přejmenovány na jednotné číslo se suffixem List.
  • Přejmenování TypZajezdKategorie -> Kategorie
  • Zrušeny třídy ConstItemOfInt32, ZkratkaConstItemOfString, ZkratkaConstItemOfInt32, ZkratkaIntConstItem a nahrazeny IntegerCiselnik, StringCiselnik, PoradiCiselnik.
  • Doplněno ID podle ProfiTour/ProfiXML do číselníků Oblast, Stat, Stredisko, SvozMisto, TypDoprava, TypHotel, TypStrava, TypVybaveni, TypKategorie.
  • Letiste.Zkratka přejmenováno na Letiste.Kod.
  • Republika.Republika přejmenováno na Republika.Nazev.
  • Mena.Nazev nevrací zkratku, ale název. VypsatNazvy nadále zobrazuje zkratku.

Přesuny metod - Export.asmx

  • AktivniStredisko zrušeno bez náhrady, stejnou funkci dělá metoda Katalog/Dostupnost s parametry Typ=Stredisko, JenID=True a id_Republika.
  • Clanek přesunuto do Admin/ClanekDetail
  • Clanky přesunuto do Admin/ClanekList
  • DestinacePopis přesunuto do Admin/StatPopis, Admin/OblastPopis nebo Admin/StrediskoPopis podle typu.
  • Dostupnost přesunuto do Katalog/Dostupnost
  • DostupnostFlat zrušeno bez náhrady.
  • Hledani přesunuto do Katalog/HledaniZajezdu, výsledky obsahují obvyklé objekty Zajezd a Termin. Parametry určené hodnotami Min/Max a případně výčtem byly sloučeny do společných objektů. Vzdálenosti od pláže atd už se nepředávají jako -1, ale jako nevyplněné/vynechané hodnoty.
  • HledaniFlat zrušeno bez náhrady.
  • HledaniMini zrušeno bez náhrady.
  • HledaniTerminu přesunuto do Katalog/HledaniTerminu
  • HledaniTerminuFlat zrušeno bez náhrady.
  • HledaniTerminuMini zrušeno bez náhrady.
  • HotTipy přesunuto do Katalog/HotTipList, rozdělení objektu pro hottip (poznámka, pořadí) a termín.
  • Hotel přesunuto do Katalog/HotelDetail
  • Kalkulace přesunuto do Katalog/Kalkulace, TypCena přejmenováno na CenaTyp, zrušena úroveň ceníků (lze zrekonstruovat podle id_Ubytovani a id_ZajezdHotel), Warning přejmenováno na Varovani. Vstupní parametry sjednoceny s objednávkou viz níže.
  • KalkulaceFlat zrušeno bez náhrady.
  • TerminZajezd přesunuto do Katalog/TerminDetail, upraveno uspořádání tříd.
  • Ubytovani přesunuto do Katalog/UbytovaniDetail
  • Vylet přesunuto do Katalog/VyletDetail
  • WebTabulka přesunuto do Ostatni/ExterniProcedura nebo Ostatni/ExterniTabulka, pro konkrétní název zkuste vždy nejdřív proceduru. Pokud nebude fungovat, tak je to tabulka. Byla optimalizována struktura na seznam sloupců a řádky už jen s hodnotami
  • WebTabulkaFlat zrušeno bez náhrady.
  • WebTabulky přesunuto do Ostatni/ExterniProcedura, optimalizována struktura na seznam sloupců a řádky už jen s hodnotami.
  • WebTabulkyFlat zrušeno bez náhrady.
  • Zajezd přesunuto do Katalog/ZajezdDetail, Zajezd přejmenováno na ZajezdPopis, TypZajezdKategorie přejmenováno na Kategorie.
  • ZajezdTermin přesunuto do Katalog/KalkulaceParametry, většina elementů byla přejemenována. SkupinaSlevaKombinace odstraněno bez náhrady, kalkulace vrátí nejvýhodnější kombinaci a ta se předá do objednávky. Pojištění upraveno z číselníku, takže název se již nevrací přímo.
  • ZajezdTerminFlat zrušeno bez náhrady.
  • Zajezdy přesunuto do Katalog/ZajezdList, ZajezdMini je přejmenován na Zajezd.

Přesuny metod - Akce.asmx

Přesuny metod - Online.asmx

Kalkulace a objednávky

Jako základ kalkulace se použije VlastniProduktTerminInput s těmito hodnotami:
  • Cestujici - kombinace hodnot CestujiciDospelyInput a CestujiciVekInput. Nově lze rovnou definovat osoby, přihlášené klienty a cestující jen podle data narození.
  • id_SkupinaSlevaParametr - jako v původní verzi.
  • Pojisteni - seznam PojisteniInput zopakovaný pro všechny cestující. Nově lze pojistit jen některé osoby a dát jedné osobě více různých pojištění.
  • RezervaceDopravy - jedna RezervaceDopravaKalkulaceInput ve směru Tam a jedna RezervaceDopravaKalkulaceInput ve směru zpět. Obě se všemi cestujícími a nastavením parametrů pro letiště a svozy. Nově lze různé osoby rozdělt na různé svozy a nastavit místenky.
  • RezervaceUbytovani - seznam RezervaceUbytovaniKalkulaceInput pro každý ZajezdHotel (dříve to byly jen ty s ubytováním). Pro rezervaci více pokojů se bude id_ZajezdHotel a případně i id_Ubytovani opakovat vícekrát. Vždy s přiřazením konkrétních cestujících.
Pro objednávku s rezervací (Online.asmx/Objednavka) se použije ObjednavkaTerminInput s těmito hodnotami:
  • id_Organizace - stejně jako ve staré verzi.
  • Objednatel - stejně jako ve staré verzi podle nových datových typů. Nově lze poslat rovnou i přihlášeného objednatele.
  • Produkt - stejně jako u kalkulace s VlastniProduktTerminInput.
  • id_ObjednavkaZdroj - nastavte hodnotu 1.
  • PoznamkaObjednavka - stejně jako ve staré verzi.
  • PoznamkaKlient - stejně jako ve staré verzi.
  • URL - stejně jako ve staré verzi.
  • id_SkupinaSlevaKombinace - stejně jako ve staré verzi, hodnotu se dozvíte z výstupu Katalog/Kalkulace.
  • NepovinneCeny - stejně jako ve staré verzi, ale s novým typem.
Pro objednávku bez rezervace (Akce.asmx/Objednavka) se použije všechno stejně jako u objednávky s rezervací, pouze s těmito rozdíly:
  • Produkt.RezervaceDopravy bude prázdné.
  • Produkt.RezervaceUbytovani bude prázdné.
  • PoznamkaObjednavka bude obsahovat celkovou rekapitulaci všech informací a parametrů. Tzn objenané hotely, pokoje, rekapitulaci cenové kalkulace ve formě textu.
Pokud objednatel cestuje, a ve staré verzi cestoval implicitně vždy, tak je potřeba ho umístit mezi cestující do Produkt.Cestujici pomocí CestujiciKlientInput s opisem dat do KlientDataInput.

Často kladené otázky

Kde začít?

WCF 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 rozhraní (kromě případu, kdy máte výsledek již uložen v cache).

Každá metoda vrací datový typ odvozený od Result, který reprezentuje obecný výsledek metody, nebo chybu reprezentovanou jako Fault. Možné výstupní stavy tedy jsou:
  • Fault značí chyby ve volání nebo implementaci na straně klienta. Texty chyb by neměly být prezentovány návštěvníkovi.
  • Result.Message obsahuje chybovou zprávu pro klienta podle parametru id_Jazyk a měla by být zobrazena klientovi, protože ji může opravit např. jiným výběrem kritérií. Ostatní výstupní data nemá smysl v takovém případě zpracovávat.
  • Result může obsahovat další položky s výstupními daty podle konkrétní metody.

Jaká je posloupnost metod?

Jak funguje parametr VypsatNazvy?

Každá metoda kromě číselníků obsahuje kontext a výběrem jazyka a parametrem VypsatNazvy typu boolean:

1) VypsatNazvy = True
V tomto režimu bude výstup pro každý identifikátor z číselníku doplněn textová název. Např. při výskytu položky TypDoprava.ID="40" bude výstup doplněn o TypDoprava.Nazev="letecká". Podobně pro všechny ostatní číselníky.
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ích datech 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í, tzn. hlavní web CK.

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 Katalog/KalkulaceParametry, která poskytuje dodatečné informace potřebné pro zjištění všech vstupních parametrů metody Katalog/Kalkulace.

Proč mají některé termíny nulový počet dní?

Některé termíny nejsou zadané fixním počtem dní, ale jsou zadané jako sezóna, tzn. počet dní je nulový a počet nocí záporný (udává rozdíl mezi vybraným počtem dní a nocí). V takovém případě je obecně možný nástup kdykoliv a na libovolný počet dní. Proto klient musí vybrat počet dní, aby byla kalkulace zobrazena pro správnou délku pobytu a datum nástupu.

Proč metoda hledání někdy odmítá hodnotu parametru DatumDo?

DatumDo je typu Date a musí to být existující datum. 30.2. není platné datum, stejně jako 31.4. - duben končí 30.4. Podobně pro další 30ti denní měsíce.