Taxis Pitane Soap Technologie koppeling ritopdrachten Censys BV
Communicatie Protocol Taxis Pitane Business Suite Taxis Pitane Enterprise Editie
Voorwoord ............................................................................................................................................ 3 Test locatie: ........................................................................................................................................ 3 Beschikbare functies ............................................................................................................................. 4 RequestPitaneTripsSubCentral....................................................................................................... 4 ConfirmTripStatusSubCentral ........................................................................................................ 5 Aanbieden van een route .................................................................................................................... 8 In- en uitstap volgorde..................................................................................................................... 8 RequestPitaneTripsForecastingSubCentral ...................................................................................... 9 Statusberichten verzenden naar de centrale ................................................................................... 11 UpdatePitaneTripSubCentral ....................................................................................................... 11 Retourcodes ................................................................................................................................. 12 Veldbeschrijvingen XML berichten (ResultXML) ........................................................................... 13 Bericht types .................................................................................................................................... 16 Ritstatus ........................................................................................................................................... 17 Wagensoorten ................................................................................................................................. 18 Vervoersvormen ............................................................................................................................. 19 Retourmeldingen ................................................................................................................................ 20
Taxis Pitane Soap koppeling v2.1.112
Pagina 2
Voorwoord Met behulp van deze handleiding is het mogelijk om te communiceren met de Taxis Pitane centrale via het soap protocol. Alle beschikbare functies werden beschreven in de volgende pagina’s. Dit stuk is geschreven voor gebruikers die kennis hebben van het implementeren van soap technologie. Om de implementatie bij de klant voor te bereiden hebben wij een testomgeving beschikbaar die u kunt gebruiken.
Test locatie: URL: http://soap.pitane.nl WSDL: http://soap.pitane.nl/PitaneSoap.asmx?WSDL Voor het gebruik van een test account moet u verder beschikken over inloggegevens (token en wachtwoord). Bel onze helpdesk voor noodzakelijke informatie en/of account gegevens.
Taxis Pitane Soap koppeling v2.1.112
Pagina 3
Beschikbare functies RequestPitaneTripsSubCentral
Met deze functie kunt u alle beschikbare ritten ophalen met betrekking tot centrale, ongeacht de status. Alle resultaten worden weergegeven in RESULTXML enveloppe (zie veldbeschrijvingen XML berichten voor meer informatie). Het veld RESULTCODE geeft informatie weer over de aanvraag: 0 -1
= =
succes mislukt
Het veld RESULTMESSAGE geeft informatie weer over de status van de aanvraag.
Voorbeeld:
SOAP actie: RequestPitaneTripsSubCentral <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>
string <Password>string Antwoord: <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>
string int string
Taxis Pitane Soap koppeling v2.1.112
Pagina 4
Bevestigen van een bericht
ConfirmTripStatusSubCentral Wanneer u berichten ophaalt via de RequestPitaneTripsSubCentral moet u de ontvangen berichten per ritopdracht bevestigen. Een bevestiging geeft aan dat u de ritopdracht zelf heeft verwerkt in uw eigen software systeem. Let op: wanneer u dit niet doet blijft het systeem dezelfde rit aanbieden. Een bericht bevestigen kunt u doen door ConfirmTripStatusSubCentral pakket te verzenden: Voorbeeld: POST /PitaneSoap.asmx HTTP/1.1 Host: soap.pitane.nl Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://soap.pitane.nl/ConfirmTripStatusSubCentral" <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>
string <Password>string int int <Status>int string
Taxis Pitane Soap koppeling v2.1.112
Pagina 5
Antwoord: HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <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>
int string
Wanneer uw bericht status goed werd ontvangen ontvangt u een ACK, bij foutief verzenden ontvangt u een NACK op uw pakket in het veld RESULTMESSAGE.
Taxis Pitane Soap koppeling v2.1.112
Pagina 6
Voorbeeld van een bevestiging van een ritopdracht:
B9AB651C-82EB-40A3-8CB8-025BBA6B397D <Password>geheim1234
234653 -> sus_confirmationcode
1265423 -> pla_id <Status>0
Voorbeeld van een afwijzing van een ritopdracht:
B9AB651C-82EB-40A3-8CB8-025BBA6B397D <Password>geheim1234
234653 -> sus_confirmationcode
1265423 -> pla_id <Status>-1
geen capaciteit beschikbaar
Taxis Pitane Soap koppeling v2.1.112
Pagina 7
Aanbieden van een route Wanneer de centrale vooraf gecombineerde ritopdrachten verzend zijn deze herkenbaar door het veld pla_route. Alle bij elkaar horende ritopdrachten dragen dezelfde waarde in het veld pla_route en moeten afzonderlijk op basis van het veld pla_id worden bevestigd.
In- en uitstap volgorde De in- en uitstap volgorde wordt bepaald door de waarde in het ved pla_van (instap) en pla_naar (uitstap) in oplopende vorm. De route moet dan in deze volgorde worden gereden. Let op: Ingeval van een combinatie van ritten moeten alle ritopdrachten afzonderlijk worden bevestigd op de hoofdcentrale.
Taxis Pitane Soap koppeling v2.1.112
Pagina 8
RequestPitaneTripsForecastingSubCentral Het is mogelijk binnen de Taxis Pitane agenda de planning op te vragen van een ondernemer. Aan deze planning kunnen geen rechten worden ontleend maar het geeft wel een indicatie over de mogelijke capaciteit die men kan verwachten aan opdrachten. De planning opvragen is enkel informatief, ritopdrachten moeten dus NIET bevestigd worden aan de soap server. Een planning komt tot stand door de rit binnen de centrale te koppelen aan een vervoerder of onderaannemer. Dit kan dus nog wijzigen! Een planning kan men opvragen voor een bepaalde periode via de velde STARTDATE en ENDDATE. Voorbeeld: POST /PitaneSoap.asmx HTTP/1.1 Host: soap.pitane.nl Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://soap.pitane.nl/RequestPitaneTripsForecastingSubCentral" <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>
string <Password>string <Startdate>dateTime <EndDate>dateTime
Taxis Pitane Soap koppeling v2.1.112
Pagina 9
Antwoord: HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <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>
string int string
Taxis Pitane Soap koppeling v2.1.112
Pagina 10
Statusberichten verzenden naar de centrale Elke ontvangen ritopdracht op de subcentrale moet afgehandeld worden op de centrale van de aanbieder. Via onderstaande functie kunt u de ritopdrachten afhandelen.
UpdatePitaneTripSubCentral
POST /PitaneSoap.asmx HTTP/1.1 Host: soap.pitane.nl Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://soap.pitane.nl/UpdatePitaneTripSubCentral" <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>
string <Password>string int <Status>int double double string <TimeStamp>string
Antwoord: HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length <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>
int string
Taxis Pitane Soap koppeling v2.1.112
Pagina 11
Voorbeeld:
B9AB651C-82EB-40A3-8CB8-025BBA6B397D <Password>geheim1234
10560 <Status>4
51.234 5.415 AB-XZ-23 <TimeStamp>2012-02-15 14:50
Retourcodes
Status 4 5 6 7 8 9
Omschrijving Toegewezen aan de wagen Klant ingestapt Klant uitgestapt Loosmelding (klant niet gevonden) Afgehandeld (klaar voor administratie) Klant werd gebeld
Wanneer de ritopdracht met succes werd aangepast is de waarde van de resultcode = 1. (zie tabel retourmeldingen)
Taxis Pitane Soap koppeling v2.1.112
Pagina 12
Veldbeschrijvingen XML berichten (ResultXML) Naam veld pla_id pla_datum pla_tijdstip_locatie pla_ophstraat pla_ophnummer pla_ophpostcode pla_ophstad pla_besstraat pla_bestnummer pla_bestpostcode pla_beststad pla_opmerking pla_vervoer pla_rolstoel pla_combineren pla_lopers pla_rollers pla_reiziger pla_wagen pla_chauffeur pla_route pla_van pla_naar pla_mut pla_km_sqr pla_km_map pla_hulpstukken pla_minuten pla_soortvervoer pla_soortwagen pla_filter pla_bedrag_1 pla_bedrag_2 pla_bedrag_3 pla_bedrag_4 pla_bedrag_5 pla_bedrag pla_naam_reiziger pla_status pla_proces pla_telefoon pla_bellen pla_voorin pla_verwijzer pla_reden pla_machtiging pla_begeleiding pla_tekst pla_rc pla_uzovi pla_referentie pla_reistijd_sqr pla_tijdsverschil pla_btw_perc pla_vlucht pla_iata pla_vluchttijd pla_nss_code
Voorbeeld 105706 2013-01-25T16:15:00 2012-11-30T17:14:00 Ad Luijkxlaan 4 5626 HL Eindhoven Piusplein 73 4621 EP Bergen op Zoom Klant in wagen helpen 0 0 1 2 0 10157 33 0 0 0 0 1 95.02 95.02 0 59 S T S 0.00 0.00 0.00 0.00 0.00 74.00 Michel van Eck W 0 0 0 0 0 1 1 0 1900-01-01T00:00:00 0 6.00
1900-01-01T00:00:00 EHV75
Veldtype int dateTime dateTime string string string string string string string string string int BoolInt BoolInt BoolInt int int int int int int int BoolInt double double BoolInt int string string string double double double double double double string string int string BoolInt BoolInt int int string int string BoolInt int string dateTime int double string string dateTime string
Omschrijving Unieke sleutel (ritnummer) Datum Tijdstip op locatie Straat ophaaladres Huisnummer ophaaladres Postcode ophaaladres Stad ophaaladres Straat bestemming Huisnummer bestemming Postcode bestemming Stad bestemming Opmerking Vervoersnummer Rolstoel Combineren Lopers Rollers Reiziger Wagen Chauffeur Routenummer Route instap beweging Route uitstap beweging Mutatie Theoretische kilometers Berekende kilometers Hulpstukken Theoretische duur van de rit Soort vervoer Soort wagen Filter Meterbedrag Zorgbedrag Eigen bijdrage Extra kosten Bedrag rit 5 Tariefbedrag Naam reiziger Status rit (zie toelichting) Processtatus Telefoon Bellen noodzakelijk Voorin zitten Indicatie vervoer Prestatiecode Machtigingsnummer Begeleiding Extra informatie Op rekening UZOVI code Kenmerk klant Reistijd SQR Kwaliteitsverschil minuten BTW percentage factuur Vluchtnummer Luchthaven Vluchttijd Station code
Taxis Pitane Soap koppeling v2.1.112
Pagina 13
pla_oph_land pla_best_land pla_ophnummertoe pla_bestnummertoe pla_email pla_spoed pla_planning pla_indicaties pla_extern_locatie pla_extern_kostenplaats pla_vip pla_oph_latitude pla_oph_longitude pla_best_latitude pla_best_longitude pla_zone_van pla_zone_naar pla_zone_aantal pla_zone_gemeente pla_zone_begeleiding pla_zone_familie pla_zone_passagier pla_extern_projectnummer pla_subcentrale pla_zone_vervoersoort pla_zone_familie_aantal pla_zone_begeleiding_aantal pla_sms pla_smsnummer pla_totaal pla_btw pla_netto pla_belbus pla_oph_syn pla_bes_syn pla_barcode pla_oph_taxizone pla_bes_taxizone pla_is_materiaal pla_begeleider pla_bedrag_onder pla_netto_onder pla_btw_onder pla_totaal_onder pla_via pla_viastraat pla_vianummer pla_vianummertoe pla_viapostcode pla_viastad pla_via_latitude pla_via_longitude pla_chf_uit_route pla_europallet pla_blokpallet pla_pallet pla_max_hoogte pla_max_lengte pla_max_breedte pla_laadklep sus_confirmationcode
NL NL
0 0 0
0 51.47220 5.43270 51.49270 4.29930 7290 6410 0 0.00 0.00 0.00 0.00 1 0 0 0 74.00 4.19 69.81 0
0 0 0 0 0.00 0.00 0.00 0.00 0
Eindhoven 0.00000 0.00000 0 0 0 0 0 0 0 1
string string string string string int int BoolInt string string int double double double double int int int double double double double string int string int int BoolInt string double double double int string string string int int BoolInt BoolInt double double double double BoolInt string string string string string double double string int int int int int int int int
Land code ophaaladres Land code bestemming Ophaalnummer toevoeging Bestemmingsnummer toevoeging Email adres Spoed rit Planning wagen Indicaties Extern locatiecode Extern kostenplaats VIP klant Latitude startadres Longitude startadres Longitude startadres Longitude bestemming Zone van Zone naar Aantal zones Bedrag gemeente bijdrage Bedrag begeleiding Bedrag familieleden Bedrag passagier Extern projectnummer Sub centrale Vervoersoort collectief vervoer Aantal familieleden Aantal begeleiders SMS dienst gebruiken SMS nummer Totaal bedrag factuur Bedrag BTW factuur Netto bedrag factuur Belbusnummer Synoniem Synoniem bestemming Barcode Taxi zonenummer ophaaladres Taxi zonenummer bestemming Rit is een materiaalrit Begeleider Tariefbedrag onderaannemer Netto bedrag onderaannemer Bedrag BTW onderaannemer Totaal bedrag onderaannemer Via punt aanwezig Straat ophaaladres via Huisnummer ophaaladres via Ophaalnummer toevoeging via Postcode ophaaladres via Stad ophaaladres via Latitude startadres via Longitude startadres via Uit route halen Aantal europallets Aantal blokpallets Aantal pallets Maximum hoogte Maximum lengte Maximum breedte Laadklep noodzakelijk Bevestigingscode
Taxis Pitane Soap koppeling v2.1.112
Pagina 14
sus_datum_invoer sus_type
2013-02-08T08:38:35.940 1
dateTime int
Registratiedatum Soort bericht (zie toelichting)
Taxis Pitane Soap koppeling v2.1.112
Pagina 15
Bericht types sus_type 1 2 3 4 5 6 7 8 9
Omschrijving Nieuwe ritopdracht Gewijzigde ritopdracht Verwijderde ritopdracht Toegewezen aan de wagen Klant ingestapt Klant uitgestapt Loosmelding (klant niet gevonden) Afgehandeld (klaar voor administratie) Klant werd gebeld
Taxis Pitane Soap koppeling v2.1.112
Pagina 16
Ritstatus pla_status
W T K V L D
Omschrijving Wachtend in de agenda Toegewezen aan de wagen Klant in het voertuig Klant uitgestapt Loosmelding Rit werd verwijderd
Taxis Pitane Soap koppeling v2.1.112
Pagina 17
Wagensoorten pla_wagensoort T R B V L C
Omschrijving Taxi Rolstoelbus Bus VIP wagen Limousine Caddy
Taxis Pitane Soap koppeling v2.1.112
Pagina 18
Vervoersvormen pla_soortvervoer P Z T O S C K A G
Omschrijving Particulier vervoer Zorgvervoer Treintaxi Belbus Groepsvervoer / woon-werk vaste combinatie Collectief vervoer / WMO Koerierdienst Academie vervoer Groepsvervoer in losse combinatie
Taxis Pitane Soap koppeling v2.1.112
Pagina 19
Retourmeldingen Omschrijving INVALID USER INVALID STATUS INVALID VEHICLE SUCCESS USER NOT FOUND FAILED BLOCKED
Reden Controleer de token en/of het wachtwoord Ongeldige status code van de ritopdracht Kenteken van de wagen is foutief Met succes verwerkt Gebruikersgegevens zijn ongeldig De opdracht is mislukt Het account werd geblokkeerd
Taxis Pitane Soap koppeling v2.1.112
Pagina 20