Taxis Pitane Soap Technologie koppeling ritopdrachten. Censys BV

Transcriptie

1 Taxis Pitane Soap Technologie koppeling ritopdrachten Censys BV Communicatie Protocol Taxis Pitane Business Suite Taxis Pitane Enterprise Editie

2 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 UpdatePitaneTripSubCentral Retourcodes Veldbeschrijvingen XML berichten (ResultXML) Bericht types Ritstatus Wagensoorten Vervoersvormen Retourmeldingen T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 2

3 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: 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. T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 3

4 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 = succes -1 = mislukt Het veld RESULTMESSAGE geeft informatie weer over de status van de aanvraag. Voorbeeld: SOAP actie: RequestPitaneTripsSubCentral <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <RequestPitaneTripsSubCentral xmlns=" <Token>string</Token> <Password>string</Password> </RequestPitaneTripsSubCentral> </soap:body> </soap:envelope> Antwoord: <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <RequestPitaneTripsSubCentralResponse xmlns=" <RequestPitaneTripsSubCentralResult> <ResultXML>string</ResultXML> <Resultcode>int</Resultcode> <ResultMessage>string</ResultMessage> </RequestPitaneTripsSubCentralResult> </RequestPitaneTripsSubCentralResponse> </soap:body> </soap:envelope> T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 4

5 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: " <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <ConfirmTripStatusSubCentral xmlns=" <Token>string</Token> <Password>string</Password> <ConfirmationCode>int</ConfirmationCode> <TripID>int</TripID> <Status>int</Status> <Remark>string</Remark> </ConfirmTripStatusSubCentral> </soap:body> </soap:envelope> T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 5

6 Antwoord: HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <ConfirmTripStatusSubCentralResponse xmlns=" <ConfirmTripStatusSubCentralResult> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </ConfirmTripStatusSubCentralResult> </ConfirmTripStatusSubCentralResponse> </soap:body> </soap:envelope> 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. T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 6

7 Voorbeeld van een bevestiging van een ritopdracht: <Token>B9AB651C-82EB-40A3-8CB8-025BBA6B397D</Token> <Password>geheim1234</Password> <ConfirmationCode>234653</ConfirmationCode> <TripID> </TripID> <Status>0</Status> <Remark></Remark> -> sus_confirmationcode -> pla_id Voorbeeld van een afwijzing van een ritopdracht: <Token>B9AB651C-82EB-40A3-8CB8-025BBA6B397D</Token> <Password>geheim1234</Password> <ConfirmationCode>234653</ConfirmationCode> <TripID> </TripID> <Status>-1</Status> <Remark>geen capaciteit beschikbaar</remark> -> sus_confirmationcode -> pla_id T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 7

8 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. T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 8

9 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: " <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <RequestPitaneTripsForecastingSubCentral xmlns=" <Token>string</Token> <Password>string</Password> <Startdate>dateTime</Startdate> <EndDate>dateTime</EndDate> </RequestPitaneTripsForecastingSubCentral> </soap:body> </soap:envelope> T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 9

10 Antwoord: HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <RequestPitaneTripsForecastingSubCentralResponse xmlns=" <RequestPitaneTripsForecastingSubCentralResult> <ResultXML>string</ResultXML> <Resultcode>int</Resultcode> <ResultMessage>string</ResultMessage> </RequestPitaneTripsForecastingSubCentralResult> </RequestPitaneTripsForecastingSubCentralResponse> </soap:body> </soap:envelope> T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 10

11 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: " <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <UpdatePitaneTripSubCentral xmlns=" <Token>string</Token> <Password>string</Password> <TripID>int</TripID> <Status>int</Status> <Latitude>double</Latitude> <Longitude>double</Longitude> <Vehicle>string</Vehicle> <TimeStamp>string</TimeStamp> </UpdatePitaneTripSubCentral> </soap:body> </soap:envelope> Antwoord: HTTP/ OK Content-Type: text/xml; charset=utf-8 Content-Length: length <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <UpdatePitaneTripSubCentralResponse xmlns=" <UpdatePitaneTripSubCentralResult> <ResultCode>int</ResultCode> <ResultMessage>string</ResultMessage> </UpdatePitaneTripSubCentralResult> </UpdatePitaneTripSubCentralResponse> </soap:body> </soap:envelope> T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 11

12 Voorbeeld: <Token> B9AB651C-82EB-40A3-8CB8-025BBA6B397D </Token> <Password>geheim1234</Password> <TripID>10560</TripID> <Status>4</Status> <Latitude>51.234</Latitude> <Longitude>5.415</Longitude> <Vehicle>AB-XZ-23</Vehicle> <TimeStamp> :50</TimeStamp> Retourcodes Status Omschrijving 4 Toegewezen aan de wagen 5 Klant ingestapt 6 Klant uitgestapt 7 Loosmelding (klant niet gevonden) 8 Afgehandeld (klaar voor administratie) 9 Klant werd gebeld Wanneer de ritopdracht met succes werd aangepast is de waarde van de resultcode = 1. (zie tabel retourmeldingen) T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 12

13 Veldbeschrijvingen XML berichten (ResultXML) Naam veld Voorbeeld Veldtype Omschrijving pla_id int Unieke sleutel (ritnummer) pla_datum T16:15:00 datetime Datum pla_tijdstip_locatie T17:14:00 datetime Tijdstip op locatie pla_ophstraat Ad Luijkxlaan string Straat ophaaladres pla_ophnummer 4 string Huisnummer ophaaladres pla_ophpostcode 5626 HL string Postcode ophaaladres pla_ophstad Eindhoven string Stad ophaaladres pla_besstraat Piusplein string Straat bestemming pla_bestnummer 73 string Huisnummer bestemming pla_bestpostcode 4621 EP string Postcode bestemming pla_beststad Bergen op Zoom string Stad bestemming pla_opmerking Klant in wagen helpen string Opmerking pla_vervoer 0 int Vervoersnummer pla_rolstoel 0 BoolInt Rolstoel pla_combineren 1 BoolInt Combineren pla_lopers 2 BoolInt Lopers pla_rollers 0 int Rollers pla_reiziger int Reiziger pla_wagen 33 int Wagen pla_chauffeur 0 int Chauffeur pla_route 0 int Routenummer pla_van 0 int Route instap beweging pla_naar 0 int Route uitstap beweging pla_mut 1 BoolInt Mutatie pla_km_sqr double Theoretische kilometers pla_km_map double Berekende kilometers pla_hulpstukken 0 BoolInt Hulpstukken pla_minuten 59 int Theoretische duur van de rit pla_soortvervoer S string Soort vervoer pla_soortwagen T string Soort wagen pla_filter S string Filter pla_bedrag_ double Meterbedrag pla_bedrag_ double Zorgbedrag pla_bedrag_ double Eigen bijdrage pla_bedrag_ double Extra kosten pla_bedrag_ double Bedrag rit 5 pla_bedrag double Tariefbedrag pla_naam_reiziger Michel van Eck string Naam reiziger pla_status W string Status rit (zie toelichting) pla_proces 0 int Processtatus pla_telefoon string Telefoon pla_bellen 0 BoolInt Bellen noodzakelijk pla_voorin 0 BoolInt Voorin zitten pla_verwijzer 0 int Indicatie vervoer pla_reden 0 int Prestatiecode pla_machtiging string Machtigingsnummer pla_begeleiding 1 int Begeleiding pla_tekst string Extra informatie pla_rc 1 BoolInt Op rekening pla_uzovi 0 int UZOVI code pla_referentie string Kenmerk klant pla_reistijd_sqr T00:00:00 datetime Reistijd SQR pla_tijdsverschil 0 int Kwaliteitsverschil minuten pla_btw_perc 6.00 double BTW percentage factuur pla_vlucht string Vluchtnummer pla_iata string Luchthaven pla_vluchttijd T00:00:00 datetime Vluchttijd pla_nss_code EHV75 string Station code T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 13

14 pla_oph_land NL string Land code ophaaladres pla_best_land NL string Land code bestemming pla_ophnummertoe string Ophaalnummer toevoeging pla_bestnummertoe string Bestemmingsnummer toevoeging pla_ string adres pla_spoed 0 int Spoed rit pla_planning 0 int Planning wagen pla_indicaties 0 BoolInt Indicaties pla_extern_locatie string Extern locatiecode pla_extern_kostenplaats string Extern kostenplaats pla_vip 0 int VIP klant pla_oph_latitude double Latitude startadres pla_oph_longitude double Longitude startadres pla_best_latitude double Longitude startadres pla_best_longitude double Longitude bestemming pla_zone_van 7290 int Zone van pla_zone_naar 6410 int Zone naar pla_zone_aantal 0 int Aantal zones pla_zone_gemeente 0.00 double Bedrag gemeente bijdrage pla_zone_begeleiding 0.00 double Bedrag begeleiding pla_zone_familie 0.00 double Bedrag familieleden pla_zone_passagier 0.00 double Bedrag passagier pla_extern_projectnummer string Extern projectnummer pla_subcentrale 1 int Sub centrale pla_zone_vervoersoort string Vervoersoort collectief vervoer pla_zone_familie_aantal 0 int Aantal familieleden pla_zone_begeleiding_aantal 0 int Aantal begeleiders pla_sms 0 BoolInt SMS dienst gebruiken pla_smsnummer string SMS nummer pla_totaal double Totaal bedrag factuur pla_btw 4.19 double Bedrag BTW factuur pla_netto double Netto bedrag factuur pla_belbus 0 int Belbusnummer pla_oph_syn string Synoniem pla_bes_syn string Synoniem bestemming pla_barcode string Barcode pla_oph_taxizone 0 int Taxi zonenummer ophaaladres pla_bes_taxizone 0 int Taxi zonenummer bestemming pla_is_materiaal 0 BoolInt Rit is een materiaalrit pla_begeleider 0 BoolInt Begeleider pla_bedrag_onder 0.00 double Tariefbedrag onderaannemer pla_netto_onder 0.00 double Netto bedrag onderaannemer pla_btw_onder 0.00 double Bedrag BTW onderaannemer pla_totaal_onder 0.00 double Totaal bedrag onderaannemer pla_via 0 BoolInt Via punt aanwezig pla_viastraat string Straat ophaaladres via pla_vianummer string Huisnummer ophaaladres via pla_vianummertoe string Ophaalnummer toevoeging via pla_viapostcode string Postcode ophaaladres via pla_viastad Eindhoven string Stad ophaaladres via pla_via_latitude double Latitude startadres via pla_via_longitude double Longitude startadres via pla_chf_uit_route string Uit route halen pla_europallet 0 int Aantal europallets pla_blokpallet 0 int Aantal blokpallets pla_pallet 0 int Aantal pallets pla_max_hoogte 0 int Maximum hoogte pla_max_lengte 0 int Maximum lengte pla_max_breedte 0 int Maximum breedte pla_laadklep 0 int Laadklep noodzakelijk sus_confirmationcode 1 int Bevestigingscode T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 14

15 sus_datum_invoer T08:38: datetime Registratiedatum sus_type 1 int Soort bericht (zie toelichting) T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 15

16 Bericht types sus_type Omschrijving 1 Nieuwe ritopdracht 2 Gewijzigde ritopdracht 3 Verwijderde ritopdracht 4 Toegewezen aan de wagen 5 Klant ingestapt 6 Klant uitgestapt 7 Loosmelding (klant niet gevonden) 8 Afgehandeld (klaar voor administratie) 9 Klant werd gebeld T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 16

17 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 T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 17

18 Wagensoorten pla_wagensoort T R B V L C Omschrijving Taxi Rolstoelbus Bus VIP wagen Limousine Caddy T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 18

19 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 T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 19

20 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 T a x i s P i t a n e S o a p k o p p e l i n g v Pagina 20