Taxis Pitane Business Suite Taxi Online API Censys BV Eindhoven v1.0.1
Inhoudsopgave Inhoud Doel van dit document... 3 Versie van de software... 4 Functionaliteit... 5 TaxiOnlineInsertTripByCustomer... 6 Aanroep:... 6 Antwoord:... 7 Status van de rit... 9 TaxiOnlineInsertTrip... 10 Aanroep:... 10 Antwoord:... 12 TaxiOnlineRequestTripStatus... 13 Aanroep... 13 Antwoord:... 14 Voorbeeld gegevens... 15 TaxiOnlineDeleteTrip... 16 Aanroep:... 16 Antwoord:... 17 Voorbeeld gegevens:... 18 2
Doel van dit document Met behulp van dit document kan men een interface tot stand brengen tussen Taxi Online en de Taxis Pitane Business Suite. Om gebruik te kunnen maken van het protocol moet men basis begrippen hebben van XML en het SOAP protocol. De Taxis Pitane Business Suite maakt gebruik van de Taxis Pitane Soap server. Elke klant van ons bedrijf beschikt, indien van toepassing, over zijn eigen Taxis Pitane Soap server. De communicatie tussen Taxi Online en de aangesloten centrale gebeurt rechtstreeks, zonder tussenkomst van ons data center. Het is dus van belang dat de aangesloten centrale beschikt over een computer, een Internet verbinding die permanent beschikbaar is en een vast publiek IP. Op deze computer installeert onze helpdesk de Taxis Pitane Soap server en maakt een account aan voor gebruik met Taxi Online. Raadpleeg onze helpdesk voor meer informatie wanneer u aan de slag wenst te gaan met Taxi Online. 3
Versie van de software Om gebruik te kunnen maken van de interface die beschikbaar is voor Taxi Online moet de Taxis Pitane Soap server minimaal beschikken over software versie: v2.1.117 Inlog procedure Om te communiceren met de Taxis Pitane Business Suite moet de ontvangende partij een account aanmaken in de Taxis Pitane software. Taxi Online wordt als een terminal gezien en dus beschikken over volgende gegevens: 1. Terminalcode 2. Inlognaam 3. Wachtwoord Het protocol binnen de Taxis Pitane software van deze terminal is standaard soap protocol Wanneer u de centrale wenst te koppelen aan Taxi Online moet u bovenstaande gegevens beschikbaar stellen aan uw contactpersoon binnen Taxi Online. Raadpleeg onze helpdesk voor meer informatie wanneer u aan de slag wenst te gaan met Taxi Online. Testserver Censys BV beschikt over een testserver om de koppeling veilig binnen een testomgeving te ontwikkelen. Wanneer u gebruik wenst te maken van de WSDL volgt dan volgende link: http://soap.pitane.nl/ Pitane.asmx?WSDL 4
Functionaliteit Het protocol voorziet in de volgende functies: TaxiOnlineInsertTripByCustomer TaxiOnlineInsertTrip TaxiOnlineRequestTripStatus TaxiOnlineDeleteTrip 5
TaxiOnlineInsertTripByCustomer Met behulp van deze functie is het mogelijk om een ritopdracht aan te bieden aan de Taxis Pitane software op basis van een bestaand klantennummer. De gegevens van de ritaanvraag worden overgenomen uit de basis instellingen van de debiteur binnen de Taxis Pitane software. Aanroep: POST /Pitane.asmx HTTP/1.1 Host: localhost SOAPAction: "http://soap.pitane.nl/taxionlineinserttripbycustomer" <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineInsertTripByCustomer xmlns="http://soap.pitane.nl/"> <Terminal>string</Terminal> <Logincode>string</Logincode> <Password>string</Password> <Customer>int</Customer> </TaxiOnlineInsertTripByCustomer> </soap:body> </soap:envelope> POST /Pitane.asmx/TaxiOnlineInsertTripByCustomer HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Terminal=string&Logincode=string&Password=string&Customer=string 6
Antwoord: HTTP/1.1 200 OK <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineInsertTripByCustomerResponse xmlns="http://soap.pitane.nl/"> <TaxiOnlineInsertTripByCustomerResult> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </TaxiOnlineInsertTripByCustomerResult> </TaxiOnlineInsertTripByCustomerResponse> </soap:body> </soap:envelope> HTTP/1.1 200 OK <PitaneTaxiOnlineConfirmation xmlns="http://soap.pitane.nl/"> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </PitaneTaxiOnlineConfirmation> 7
In alle communicatie met de Taxis Pitane Soap server zal Taxi Online een standaard berichtopmaak ontvangen, ongeacht de status van de ritopdracht. Afhankelijk van de status zal het antwoord bericht worden voorzien van de relevante informatie zoals tijdstippen, wagennummer en GPS locaties van het voertuig. PitaneTaxiOnlineConfirmation Veldnaam TripNumber TripStatus CarNumber LicensePlate DriverName CarETA ActualLatitude ActualLongitude ResultDateTime ResultCode ResultMessage Omschrijving Toegekend ritnummer binnen Taxis Pitane Status van de rit (zie verder) Toegekend wagennummer Kenteken van de betreffende taxi Chauffeursnaam uitgebreid met chauffeursnummer Verwachtte aankomsttijd van de wagen bij de klant Actuele positie van de wagen latitude Actuele positie van de wagen longitude Tijdsstempel van het bericht Resultaatcode van het bericht (zie verder) Extra toelichting 8
Status van de rit Volgende statusmeldingen worden verstuurd aan Taxi Online Taxis Pitane status Wachtend in de agenda status W Wagen onderweg naar klant status T Klant ingestapt status K Klant uitgestapt - status V Klant niet gevonden status L Ritopdracht werd verwijderd status D Taxi Online status Confirmed Driving to pickup Arrived at pickup Arrived at destination Cancelled by customer Cancelled by booker Elk communicatie pakket vanuit de Taxis Pitane Soap server richting Taxi Online is voorzien van een resultaatcode en omschrijving. ResultMessage ResultCode Omschrijving SUCCESS 0 Succesvol verwerkt USER NOT FOUND - 1 Inloggegevens zijn foutief INVALID OWNER - 1 Gevraagd ritnummer heeft andere eigenaar CUSTOMER NOT FOUND - 1 Klantennummer is onbekend Aandacht: Wanneer men succesvol een ritopdracht heeft ingevoerd in de Taxis Pitane software is het veld ResultCode voorzien van het intern ritnummer. 9
TaxiOnlineInsertTrip Deze functie kan worden gebruikt om een vrij adres in te voeren wanneer men niet beschikt over een klantennummer om de boeking te registreren. Aanroep: POST /Pitane.asmx HTTP/1.1 Host: localhost SOAPAction: "http://soap.pitane.nl/taxionlineinserttrip" <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineInsertTrip xmlns="http://soap.pitane.nl/"> <Terminal>string</Terminal> <Logincode>string</Logincode> <Password>string</Password> <Owner>string</Owner> <TravelType>string</TravelType> <CarType>string</CarType> <Passengers>int</Passengers> <Wheelchairs>int</Wheelchairs> <PassengerName>string</PassengerName> <PassengerPhone>string</PassengerPhone> <FromStreet>string</FromStreet> <FromHouseNumber>string</FromHouseNumber> <FromHouseNumberAdd>string</FromHouseNumberAdd> <FromZipcode>string</FromZipcode> <FromCity>string</FromCity> <ToStreet>string</ToStreet> <ToHouseNumber>string</ToHouseNumber> <ToHouseNumberAdd>string</ToHouseNumberAdd> <ToZipcode>string</ToZipcode> <ToCity>string</ToCity> <Remark>string</Remark> <Latitude>double</Latitude> <Longitude>double</Longitude> </TaxiOnlineInsertTrip> </soap:body> </soap:envelope> 10
POST /Pitane.asmx/TaxiOnlineInsertTrip HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Terminal=string&Logincode=string&Password=string&Owner=string&TravelType=st ring&cartype=string&passengers=string&wheelchairs=string&passengername=stri ng&passengerphone=string&fromstreet=string&fromhousenumber=string&fromhouse NumberAdd=string&FromZipcode=string&FromCity=string&ToStreet=string&ToHouse Number=string&ToHouseNumberAdd=string&ToZipcode=string&ToCity=string&Remark =string&latitude=string&longitude=string 11
Antwoord: HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 <soap12:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <TaxiOnlineInsertTripResponse xmlns="http://soap.pitane.nl/"> <TaxiOnlineInsertTripResult> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </TaxiOnlineInsertTripResult> </TaxiOnlineInsertTripResponse> </soap12:body> </soap12:envelope> HTTP/1.1 200 OK <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineInsertTripResponse xmlns="http://soap.pitane.nl/"> <TaxiOnlineInsertTripResult> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </TaxiOnlineInsertTripResult> </TaxiOnlineInsertTripResponse> </soap:body> </soap:envelope> 12
TaxiOnlineRequestTripStatus Deze functie kan worden gebruikt om de status van een ritopdracht permanent op te vragen. Aanroep POST /Pitane.asmx HTTP/1.1 Host: localhost SOAPAction: "http://soap.pitane.nl/taxionlinerequesttripstatus" <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineRequestTripStatus xmlns="http://soap.pitane.nl/"> <Terminal>string</Terminal> <Logincode>string</Logincode> <Password>string</Password> <Trip>int</Trip> </TaxiOnlineRequestTripStatus> </soap:body> </soap:envelope> POST /Pitane.asmx/TaxiOnlineRequestTripStatus HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Terminal=string&Logincode=string&Password=string&Trip=string 13
Antwoord: HTTP/1.1 200 OK <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineRequestTripStatusResponse xmlns="http://soap.pitane.nl/"> <TaxiOnlineRequestTripStatusResult> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </TaxiOnlineRequestTripStatusResult> </TaxiOnlineRequestTripStatusResponse> </soap:body> </soap:envelope> HTTP/1.1 200 OK <PitaneTaxiOnlineConfirmation xmlns="http://soap.pitane.nl/"> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </PitaneTaxiOnlineConfirmation> 14
Voorbeeld gegevens <?xml version="1.0" encoding="utf- 8"?> <PitaneTaxiOnlineConfirmation xmlns="http://soap.pitane.nl/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema- instance"> <TripNumber>122985</TripNumber> <TripStatus>Driving to pick up</tripstatus> <CarNumber>15</CarNumber> <LicensePlate>PPJJ84</LicensePlate> <DriverName>Groeneveld Ben</DriverName> <CarETA>2014-01- 14T10:50:00</CarETA> <ActualLatitude>51.6265</ActualLatitude> <ActualLongitude>5.0725</ActualLongitude> <ResultDateTime>2014-02- 05T18:55:30.1885062+01:00</ResultDateTime> <ResultCode>0</ResultCode> <ResultMessage>SUCCESS</ResultMessage> </PitaneTaxiOnlineConfirmation> 15
TaxiOnlineDeleteTrip Deze functie kan worden gebruikt om eerder geboekte ritopdracht te verwijderen in de Taxis Pitane software van de centrale. De status wordt geaccepteerd wanneer er sprake is van een wachtende ritopdracht in de software. Het resultaat van deze actie is een standaard statusbericht van de ritopdracht. Wanneer de wagen reeds onderweg is naar de klant moet de boeker contact opnemen met de centrale. Aanroep: POST /Pitane.asmx HTTP/1.1 Host: localhost SOAPAction: "http://soap.pitane.nl/taxionlinedeletetrip" <soap:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <TaxiOnlineDeleteTrip xmlns="http://soap.pitane.nl/"> <Terminal>string</Terminal> <Logincode>string</Logincode> <Password>string</Password> <Trip>int</Trip> </TaxiOnlineDeleteTrip> </soap:body> </soap:envelope> POST /Pitane.asmx/TaxiOnlineDeleteTrip HTTP/1.1 Host: localhost Content-Type: application/x-www-form-urlencoded Terminal=string&Logincode=string&Password=string&Trip=string 16
Antwoord: HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 <soap12:envelope xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope"> <soap12:body> <TaxiOnlineDeleteTripResponse xmlns="http://soap.pitane.nl/"> <TaxiOnlineDeleteTripResult> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </TaxiOnlineDeleteTripResult> </TaxiOnlineDeleteTripResponse> </soap12:body> </soap12:envelope> HTTP/1.1 200 OK <PitaneTaxiOnlineConfirmation xmlns="http://soap.pitane.nl/"> <TripNumber>int</TripNumber> <TripStatus>string</TripStatus> <CarNumber>int</CarNumber> <LicensePlate>string</LicensePlate> <DriverName>string</DriverName> <CarETA>dateTime</CarETA> <ActualLatitude>double</ActualLatitude> <ActualLongitude>double</ActualLongitude> <ResultDateTime>dateTime</ResultDateTime> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </PitaneTaxiOnlineConfirmation> 17
Voorbeeld gegevens: <?xml version="1.0" encoding="utf- 8"?> <PitaneTaxiOnlineConfirmation xmlns="http://soap.pitane.nl/" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:xsi="http://www.w3.org/2001/xmlschema- instance"> <TripNumber>123249</TripNumber> <TripStatus>Cancelled by booker</tripstatus> <CarNumber>0</CarNumber> <LicensePlate/> <DriverName/> <CarETA>2014-02- 05T20:05:06</CarETA> <ActualLatitude>0</ActualLatitude> <ActualLongitude>0</ActualLongitude> <ResultDateTime>2014-02- 05T21:29:21.1163224+01:00</ResultDateTime> <ResultCode>123249</ResultCode> <ResultMessage>SUCCESS</ResultMessage> </PitaneTaxiOnlineConfirmation> 18