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.
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.
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
- Klient přesunuto do Klient/KlientDetail
- KlientAktivace přesunuto do Klient/KlientSouhlasAktivovat
- KlientDeaktivace přesunuto do Klient/KlientSouhlasDeaktivovat
- KlientObjednavka přesunuto do Klient/KlientObjednavkaList, vstupní parametr Produkt sjednocen s kalkulací.
- KlientPrihlaseni přesunuto do Klient/KlientPrihlasit
- KlientRegistrace přesunuto do Klient/Registrovat
- KlientZmena přesunuto do Klient/KlientUlozitZmeny
- KlientZmenaHesla přesunuto do Klient/ZmenitHeslo
- Kontakt přesunuto do Ostatni/EmailPridat
- Objednavka přesunuto do Objednavka/Objednat, změněno uspořádání parametrů, sjednoceno s Online.asmx/Objednavka, sjednoceno s parametry pro kalkulaci, rozšířeno o další typy objednávek (mimo katalog, cizí produkt). Viz níže.
Přesuny metod - Online.asmx
- LzeRezervovat přesunuto do Katalog/TerminLzeRezervovat
- Objednavka přesunuto do Objednavka/Objednat, změněno uspořádání parametrů, sjednoceno s Akce.asmx/Objednavka, sjednoceno s parametry pro kalkulaci, rozšířeno o další typy objednávek (mimo katalog, cizí produkt). Viz níže.
- ObjednavkaDetail přesunuto do Objednavka/ObjednavkaDetail
- ObjednavkaDokument přesunuto do Objednavka/DokumentDetail
- ObjednavkaFaktura přesunuto do Objednavka/FakturaDokument
- ObjednavkaKlientReset přesunuto do Objednavka/CestujiciResetovat
- ObjednavkaKlientSave přesunuto do Objednavka/CestujiciUlozit
- ObjednavkaPlatba přesunuto do Objednavka/PlatbaPridat
- ObjednavkaPotvrzeni přesunuto do Objednavka/ObjednavkaDokoncit. Parametr VystavitFakturu byl nahrazen metodou Objednavka/FakturyVystavit. Parametr ZavaznaRezervace byl nahrazen parametrem MinimalniDelkaRezervace.
- ObjednavkaSmlouva přesunuto do Objednavka/SmlouvaPridat
- ObjednavkaSmlouvaVzor přesunuto do Objednavka/SmlouvaVzorList
- ObjednavkaStorno přesunuto do Objednavka/ObjednavkaStornovat
- ObjednavkaZprava přesunuto do Objednavka/ObjednavkaEmailPridat
- OvereniDostupnosti přesunuto do Katalog/TerminOveritDostupnost
- Prihlaseni přesunuto do Ostatni/UzivatelPrihlasit
- RezervaceDo přesunuto do Katalog/TerminRezervaceDo
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.
- 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.
- 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.
Č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?
- Ciselnik/* - Udělejte si přehled o dostupných číselnících a hodnotách, které vracejí a významu vstupího parametru VypsatNazvy (viz níže).
- Katalog/ZajezdList - seznam zájezdů pro přípravu struktury stránky, generování URL atd. Není to ale hledání.
- Katalog/HotTipList - jednoduché načtení hottipů, ze kterého lze pokračovat na detail zájezdu nebo termínu.
- Katalog/HledaniZajezdu - hledání zájezdů podle kritérií, nebo zobrazení seznamu zájezdů z katalogu.
- Katalog/ZajezdDetail - zobrazení detailu zájezdu a výběru termínů.
- Katalog/TerminDetail - zobrazení detailu zájezdu a výběru termínů.
- Katalog/KalkulaceParametry - příprava parametrů pro zobrazení kalkulace.
- Katalog/Kalkulace - zobrazení kalkulace pro vybrané parametry.
- Objednavka/Objednat - uložení nové objednávky do systému. Vkládat lze několik různých druhů objednávek (s rezervcí, bez rezervace, mimo katalog, cizí produkt atd.)
- Objednavka/ObjednavkaDetail - získání aktuálních informací o objednávce.
- Objednavka/CestujiciUlozit - dodatečné uložení informací o cestujících osobách
- Objednavka/ObjednavkaDokoncit - dokončení rozpracované objednávky a potvrzení času platnosti rezervace.
- Objednavka/FakturyVystavit - vystavení faktury u objednávek s rezervací
- Objednavka/SmlouvaPridat - vygenerování smlouvy u objednávek s rezervací
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.