Qenner platform -‐ Webservices introductie
Qenner B.V. Neptunusstraat 25, 7521 WC Enschede Tel. : +31 (0)88 -‐ 25 00 000 Bank nr. 52.49.41.831 KvK. 54229995 te Enschede
Qenner platform -‐ Webservices introductie
1. Platform Het platform van Qenner biedt toegang tot een breed aanbod van vakantie-‐gerelateerde producten, zoals pakketreizen, vakantiewoningen en -‐parken, bootjes, vluchten en verzekeringen. Naast de web-‐interfaces die Qenner hiervoor biedt, is een reeks van Webservices ontwikkeld waarmee derden eenvoudig dit aanbod in hun eigen omgeving kunnen ontsluiten via zoek-‐ en boekprocessen. Dit document beschrijft deze webservices en de samenhang ertussen. Qenner biedt ook de mogelijkheid tot standaard en vergaand aangepaste exports. Hierbij kan gedacht worden aan het zeer specifiek filteren op te ontvangen aanbod, en het incrementeel aanleveren van wijzigingen. De BookingService kan ook aangeroepen worden op basis van gegevens uit een export.
2. Services overzicht Qenner kent de volgende webservices, die onafhankelijk of gecombineerd kunnen worden gebruikt: 1. TravelSearch zoek & vind webservice 2. BookingService 3. PaymentService 4. Toeristiek @ YourSite (T@YS) De flow van de verschillende (hoofd)functies van de webservices is als volgt: Start
TravelSearch GetCriteria
TravelSearch GetSearchResults
BookingService RetrieveRecap
BookingService CreateBooking
PaymentService GetAvailableCountries
PaymentService GetPaymentMethods
TravelSearch GetAccommodationInfo
TravelSearch GetBookUrl
Externe deeplink
Toeristiek @ yoursite Beschrijving / kenmerken
TravelSearch GetBookCode
BookCode
BookingService GetPriceInfo
PaymentService GetPayForm
BookingService GetBookableComponents
PaymentService GetPaymentStatus
Qenner Exports
End
2.1. TravelSearch zoek & vind webservice Met behulp van de TravelSearch kan op zeer flexibele wijze het complete aanbod van reizen binnen Nederland doorzocht worden. Ook steeds meer buitenlandse touroperators sluiten zich bij ons aan. Naast de bekende reiskenmerken zoals bestemming, reisduur en datum, touroperator, prijs en type reis, kan gefilterd en gesorteerd worden op dertig standaard en onbeperkt uitbreidbare gedetailleerde kenmerken. Hieronder zitten bijv. afstand tot het strand, aanwezigheid van zwembaden, opening van receptie en bar, kindvriendelijkheid en lengte van de bedden.
Pagina 2 van 7
v1.1
Qenner platform -‐ Webservices introductie Daarnaast kan het aanbod vergeleken worden, op een kaart getoond of gezocht worden, en zijn onafhankelijke Toeristiek beschrijvingen, foto’s, reviews van derden en weerinformatie allen gekoppeld aan het aanbod. Het aanbod wordt ontdubbeld geleverd, waardoor de prijzen van verschillende aanbieders eenvoudig vergeleken kunnen worden. Een andere unieke feature is de mogelijkheid het aanbod te ‘taggen’. Hiermee kan een door u aangegeven selectie van accommodaties gemarkeerd worden met een zoekcriterium dat specifiek voor uw site van toepassing is. Dit criterium kan vervolgens integraal in de filtering meegenomen worden bij zoekopdrachten. Het aanbod van onze touroperators wordt continu ververst, waarbij incrementele updates tot elke 10 minuten bijgewerkt worden om u altijd de meest actuele zoekresultaten te bieden. Er is een versie specifiek voor pakketreizen, en een versie voor vakantiewoningen en –parken.
2.2. BookingService Met behulp van de BookingService wordt al het aanbod dat te vinden is in of ge-‐export wordt uit de TravelSearch direct ontsloten om online geboekt te worden. De actuele beschikbaarheid, meest recente prijswijzigingen en mogelijke vluchtklasses kunnen direct online gecontroleerd worden. Via onze services kan geheel onafhankelijk van het specifieke protocol dat de Touroperator hanteert de reis online geboekt en vastgelegd worden in de backoffice. Voor implementatie-‐partijen scheelt dit een grote hoeveelheid verschillende protocollen en versies van protocollen aansluiten en onderhouden. De BookingService werkt geheel ‘stateless’, waardoor de aanroepende website volledig naar eigen keuze kan worden ingericht. Voor het boek-‐ en betaalproces zelf zijn er optionele statefull calls die de boeking tijdelijk in optie nemen om te wachten op bevestiging of betaling van de consument.
2.3. PaymentService Indien een reis via het Qenner platform geboekt is, kan deze direct online afgerekend worden. Hierbij wordt een reeks van (internationale) Payment Service Providers ondersteund, waarmee uw klant altijd uit de voeten kan. Onze implementatie staat het zelfs toe betaalmethoden van verschillende providers te combineren, uitermate geschikt voor internationale organisaties. In combinatie met de nieuwste versie van onze BookingService is het nu ook mogelijk om Betalen-‐voor-‐boeken aan te bieden voor aanbieders die dit ondersteunen, waardoor de betaling gegarandeerd is voordat de reis definitief bij de touperator vastgelegd wordt.
2.4. Toeristiek @ YourSite (T@YS) Toeristiek is een rijke bron van informatie over vakantiebestemmingen die door onderzoekers ter plaatse objectief vastgelegd wordt. Dit betreft een set van 600 kenmerken over de bestemming en de accommodatie, aangevuld met informatie over land, streek en plaats en een beschrijving in de vorm van een Karakteristiek. Deze informatie, aangevuld met historische klimaatgegevens en actuele weergegevens zijn beschikbaar via de T@YS webservice. De unieke geografische indeling van de accommodaties zorgen voor een volledig ontdubbeld aanbod van accommodaties in uw product.
Pagina 3 van 7
v1.1
Qenner platform -‐ Webservices introductie
3. Gedetailleerde beschrijvingen Hieronder staat een gedetailleerdere beschrijving van de stappen en functies van een aantal van deze services. De locatie van de implementatie documentatie en de locatie van de bijbehorende WSDL staat hier ook bij genoemd.
3.1. TravelSearch Search Service De TravelSearch is een stateless SOAP webservice. Gedetailleerde documentatie: QNR-‐XML-‐Doc-‐005 TravelSearch 2-‐PackageSearch and HolidayHomeSearch.pdf Alle calls van de TravelSearch verwachten een Authorization element, waarmee u geautoriseerd en geïdentificeerd wordt. Hierdoor krijgt u altijd alleen het voor u aangesloten aanbod uit het Qenner platform. Daarnaast zijn er een aantal optionele instellingen die voor uw account ingesteld worden, zoals het ontdubbelen van accommodaties, het meeleveren van GPS codes en ratings, en eigen tags gekoppeld aan het aanbod. De TravelSearch werkt met criteria, die op elk moment opgevraagd kunnen worden. Van elk van de criteria wordt het resulterende aantal accommodaties teruggegeven mocht dat criterium geselecteerd worden. Voor elke selectie van criteria kunnen de dan nog geldige criteria met de nieuwe van toepassing zijnde aantallen resultaten opgevraagd worden. Van een geselecteerde set criteria kunnen vervolgens de zoekresultaten opgevraagd worden, met een zelf op te geven hoeveelheid details over elk resultaat. Van een specifiek zoekresultaat kunnen de accommodatie-‐ en reisdetails opgevraagd worden, een gedetailleerde prijstabel, en de bijbehorende boekingscodes t.b.v. van het aanroepen van de BookingService. Hieronder de flow zoals een website normaliter de TravelSearch zal implementeren. getCriteria <no selected criteria>
Start
Deeplinked booking site
getCriteria
getCriteria
getSearchResults
Qenner Booking Service getAccommodationInfo
getBookUrl
getBookCode
getCriteria <searchCriteria>
getPriceInfo <searchCriteria>
Pagina 4 van 7
v1.1
Qenner platform -‐ Webservices introductie
3.2. Booking Service De BookingService is een stateless SOAP webservice. Gedetailleerde documentatie: http://content.traserv.com/docs/QNR-‐XML-‐Doc-‐002 Qenner BookingService.pdf Alle calls van de BookingService verwachten een Authorization element, waarmee u geautoriseerd en geïdentificeerd wordt. Hierdoor boekt u altijd onder uw eigen contract of ANVR nummer bij de aanbieder. Daarnaast zijn er een aantal optionele instellingen die voor uw account ingesteld worden, zoals het toevoegen van toeslagen (zoals Reserveringskosten) of kortingen. Deze worden toegevoegd aan de prijsberekening vanuit de aanbieder. Het integraal in de BookingService mee kunnen boeken van Europeesche verzekeringen is een optie die per account geconfigureerd kan worden. De BookingService bevat drie hoofd calls, die het gehele boekingsproces ondersteunen: • GetBookableComponents • GetPriceInfo • CreateBooking Daarnaast zijn er een aantal ondersteunende calls, beschikbaar voor een deel van het aanbod (voornamelijk pakketreizen): • RetrieveRecap • PrepareBooking • CompleteBooking GetBookableComponents Deze functie heeft als argument een BookCode, die geleverd kan zijn in een export vanuit het Qenner platform, of direct uit de TravelSearch kan komen. Deze BookCode bevat details over de accommodatie, eventueel arrangement of pakket, vertrekdatum, verblijfsduur en aantal personen. De functie geeft alle mogelijke reisopties terug voor de gevraagde reis, met bijbehorende verplichte en optionele extra’s. Binnen een accommodatie kunnen verschillende kamertypes en verzorgingen geboden worden; van elke combinatie wordt de reisprijs (per accommodatie of per persoon) vermeld. Voor reizen met vervoer kunnen meerdere vervoersopties en klasses geboden worden, sommigen eventueel met een toeslag ten opzichte van de bij de accommodatie genoemde reisprijs. Verplichte en optionele extra’s zijn in deze prijzen nog niet meegenomen. Alle geretourneerde componenten zijn beschikbaar of op aanvraag, aangegeven in de status van de component. Genoemde accommodaties en vervoer kunnen altijd gecombineerd worden; binnen vervoer zal voor de heen-‐ en terugreis normaliter een restrictie gelden dat dezelfde aanbieder voor beide gekozen moet worden. GetPriceInfo Deze functie heeft als argument een selectie van componenten zoals geretourneerd uit de GetBookableComponents functie, met daarin aangevuld het aantal af te nemen kamers of huisjes en gekozen verzorging, en de gekozen vervoersopties en hun aantallen. Ook reizigersinformatie wordt in deze functie gevraagd, die op dit moment nog dummy-‐gegevens mogen bevatten, zo lang de opgegeven leeftijden (aan de hand van de geboortedatum) zo correct mogelijk zijn. De bezetting, leeftijden en verdeling van personen over accommodaties kan invloed hebben op de beschikbaarheid en de prijs, netzoals uiteraard eventueel geselecteerde extra’s.
Pagina 5 van 7
v1.1
Qenner platform -‐ Webservices introductie De functie retourneert een prijsstaat met daarin de opbouw van de prijs en een totaalprijs. Optioneel wordt ook een overzicht gegeven van de ter plaatse te voldoende kosten. De status in het resultaat geeft aan of deze reis beschikbaar is, en eventueel op aanvraag. CreateBooking Deze functie accepteert identieke argumenten als de GetPriceInfo functie, al zullen nu uiteraard de correct reizigersgegevens alleen ingevuld moeten zijn. De functie geeft bij succes een overzicht van de boeking, een boekingsnummer en een factuurnummer (invoiceId) terug. Het boekingsnummer kan gebruikt worden als argument voor de RetrieveRecap functie, het factuurnummer is te gebruiken om de PaymentService aan te roepen voor de eerste online betaling van de reis. RetrieveRecap De retrieveRecap functie levert voor een bestaand boekingsnummer een complete beschrijving van de geboekte reis op, zoals deze bekend is bij Qenner. Indien via andere wegen (bijv. telefonisch of direct in de backoffice van de touroperator) de boeking later nog gewijzigd is bij de touroperator, kan de recap wellicht niet de laatste situatie beschrijven. Het juiste moment van het gebruik van deze functie is normaliter dan ook direct na het maken van de boeking. PrepareBooking en CompleteBooking De functies PrepareBooking en CompleteBooking zijn niet voor alle aanbieders, en alleen vanaf BookingService versie 1.5 beschikbaar. Ze bieden de mogelijkheid een boeking voor te bereiden, voorlopig vast te leggen bij de aanbieder, en pas te bevestigen in een tweede stap. Deze kan bijvoorbeeld genomen worden na het laten bevestigen door de boeker, of na het doen van de aanbetaling horende bij de boeking. Hieronder de flow zoals een website normaliter de BookingService zal implementeren. TravelSearch BookCode
GetBookableComponents
GetPriceInfo <default housing, transport, travelers>
GetPriceInfo <selected housing, transport, travelers>
BookingService CreateBooking
Qenner Exports BookingId invoiceId
RetrieveRecap
Pagina 6 van 7
v1.1
Qenner platform -‐ Webservices introductie
3.3. Payment Service De PaymentService werkt op basis van klant-‐specifieke configuratie. Er is altijd een abonnement bij een PSP (Payment Service Provider) of bij de eigen bank voor iDEAL noodzakelijk. De Payment Service kent de volgende functies: • GetAvailableCountries retourneert voor welke (verkoop)landen er betaalconfiguraties bestaan. De vervolg-‐ calls hebben een country code als parameter. • GetPaymentMethods retourneert de lijst met payment methods die van toepassing zijn. Eventueel kan de functie GetPaymentMethodInformation aangeroepen worden om meer details op te halen. • SetRedirectUrls met deze functie kan per resulterende betaalstatus opgegeven worden naar welke pagina de betaler teruggestuurd moet worden door de PSP. • GetPayForm deze functie retourneert een webformulier dat de juiste action-‐url en post-‐ informatie bevat voor de gekozen betaalmethode. Na het activeren van dit formulier (gewoonlijk door het klikken op een ‘Nu betalen’ button) zal de browser doorgestuurd worden naar de pagina’s van de PSP. Nadat de consument betaald heeft bij de PSP wordt deze, afhankelijk van de status van de betaling, doorgestuurd naar de eerder opgegeven redirect-‐pagina’s. Op deze pagina kan vervolgens de functie GetPaymentStatus gebruikt worden om te verifiëren of de betaling volledig verwerkt is. Dit kan bij sommige betaalmethodes even duren. Hieronder de flow zoals een website normaliter de PaymentService zal implementeren. BookingId invoiceId
GetAvailableCountries <invoiceId>
SetRedirectUrls <invoiceId>
GetPaymentMethods <invoiceId>
GetPayForm <paymentMethod, invoiceId>
Payment Service Provider
Redirect pages
GetPaymentStatus <invoiceId>
Pagina 7 van 7
v1.1