Introduction
Car Rental Software offers different APIs that allow its users to manage, make, modify or cancel reservations.
An OTA compliant SOAP web service that offers functions to retrieve pricing information, block quotes and make and cancel reservations.
The main API to be used in the future is the CRS Booker API. This is a RESTful web service still under ongoing development. However, a first set of functions which allows its users to integrate additional information with an existing reservation, is already available. Once completed, the CRS Booker API will replace all the other interfaces.
Car Rental Software
API Documentation
Car Rental Software is powered by My Appy
App Development and Software Solutions
Authorizing API calls
API calls have to provide authorization information in order for the system to identify the calling party. The APIs are designed for controllers or brokers to allow them work with bookings of their partner car rental companies directly from their desk.
Each system connecting to one of Car Rental Software's APIs has to clearly identify itself as a registered controller or broker for the car rental company, respectively. In order to do so it has to provide the broker's unique identifier (username) and a valid API key (password) in every API call.
The credentials can be requested from the appropriate car rental company.
OTA Compliant Web Service
Car Rental Software offers a OTA-compliant SOAP web service described by its WSDL file located at https://carrentalsoftware.myappy.it/web/ota/opentravel.wsdl. This web service is a partial implementation of the 2017B-1.0 version of the OpenTravel schema and the documentation is limited on the functions supported by the CRS OTA API.
A more comprehensive documentation of the full OTA standard can be found on their website: https://opentravel.org. If you're looking for a more detailed description of the types and models used by OTA, you can have a look at https://modelviewers.pilotfishtechnology.com/modelviewers/OTA/
As of now the CRS OTA API offers the following functions:
| Function | Description |
|---|---|
| OTA_Ping | This function is solely for testing purposes and can be used to test whether the interface is available and running as expected. |
| OTA_VehAvailRate | Call OTA_VehAvailRate in order to get pricing information for a given period, pickup/drop off stations and vehicle types. |
| OTA_VehLocSearch | This function can be used to get a list of all or of selected stations matching given search criteria of the car rental company. |
| OTA_VehModify | OTA_VehModify has to be used to confirm a booking that has previously been created via the OTA_VehRes function with the two-step procedure. |
| OTA_VehRes | OTA_VehRes is the function that has to be called to block an offer retrieved earlier via OTA_VehAvailRate or to book a previously requested offer. |
| OTA_VehRetRes | Once an offer has been blocked or booked, you can use this function to retrieve its details. |
All API calls are based on SOAP messages containing the request and response data. The main data block of a SOAP message usually starts with the name of the called function followed by the suffix RQ indicating a function call (request) and RS for a response.
Authentication
Every API call (except the Ping method) has to provide proper authentication information so that the system is able to identify the calling party. Therefore you need to include a Username and a Password in the requests that you want to send to the server. These credentials can be requested by the appropriate car rental company that can generate them or look them up using the broker file of the CRS control panel.
Authentication credentials are put into a POS → Source → RequestorID tag of the SOAP message as demonstrated in the code sample.
| Parameter | Description |
|---|---|
| Type | Indicates the type of the entity that is trying to identify. Set to 29 which is the value for Booking agent. |
| ID | The unique broker ID/username that the car rental company provided to you. |
| MessagePassword | The broker's API Key/password that the car rental company provided to you. |
Please note that in the following, the authentication part will be skipped in order to keep code samples as simple as possible.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehAvailRateRQ>
<POS>
<Source>
<RequestorID Type="29" ID="{Username}" MessagePassword="{Password}"/>
</Source>
</POS>
<!-- Message content here -->
</ns1:OTA_VehAvailRateRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>Error handling
Every response from the server should contain either the Success flag indicating that the request has been processed successfully or an Errors tag indicating one or more errors that occurred during the elaboration of the request.
| Response parameter | Description |
|---|---|
| Success | Flag indicating that the request has been processed successfully. If not present, check for the Errors tag to see what went wrong. |
| Errors | Container for one ore more error messages that indicate why the request could not been processed successfully. |
Please note that in the following, the success/errors part will be skipped in order to keep code samples as simple as possible.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehLocSearchRS>
<ns1:Success/>
<!-- Response data here -->
</ns1:OTA_VehLocSearchRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehLocSearchRS>
<Errors>
<Error Code="403" ShortText="Permission denied"/>
</Errors>
</ns1:OTA_VehLocSearchRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_Ping
The OTA_Ping method is for testing purposes only and can be used to check whether the system is up and running correctly.
Request
The only parameter expected inside its main OTA_PingRQ message is a random string identified as EchoData.
| Request parameter | Description |
|---|---|
| EchoData | The string that the server should echo back. |
Response
After processing the request, the system will respond to the caller echoing back the same string that was provided when the function was called together with the Success flag set.
| Response parameter | Description |
|---|---|
| EchoData | The string echoed back to the caller |
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_PingRQ>
<EchoData>Echo data</EchoData>
</ns1:OTA_PingRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_PingRS>
<ns1:Success/>
<ns1:EchoData>Echo data</ns1:EchoData>
</ns1:OTA_PingRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_VehAvailRate
The OTA_VehAvailRate function can be used to retrieve pricing information for one or more specific vehicle type(s) or a given period of time and a pickup/drop-off station. This function does not block any requested prices but does only return price. After analyzing the server's response, it is then possible to use the OTA_VehRes function to block a certain quote or make a booking straightaway.
Request
In order to get pricing information, a certain set of parameters are mandatory while others are optional to refine the search. Please check the code sample to find out how the parameters are structured and whether they are separate tags or tag attributes.
| Request parameter | Description |
|---|---|
| PickUpDateTime* | Date and time at which the vehicle has to be picked up. Use the date format YYYY-MM-DD'T'hh:mm:ss'Z' (including the Z suffix) to specify the date and time in UTC. If the trailing Z is omitted, hence you are using YYYY-MM-DD'T'hh:mm:ss as format, the date and time value is considered to be in local time (referred to the timezone of the car rental company). |
| ReturnDateTime* | Date and time (given in UTC) at which the vehicle will be returned. Use the date format YYYY-MM-DD'T'hh:mm:ssZ (including the Z suffix) to specify the date and time in UTC. If the trailing Z is omitted, hence you are using YYYY-MM-DD'T'hh:mm:ss as format, the date and time value is considered to be in local time (referred to the timezone of the car rental company). |
| PickUpLocation* | The station where the vehicle has to be picked up from. Provide the station's UID in the LocationCode attribute. |
| ReturnLocation | The station where the vehicle will be returned to. Provide the station's UID in the LocationCode attribute. This parameter is optional and in case it is not given, the PickUpLocation will also be used as the ReturnLocation. |
| RateRange | This tag can be used to filter out pricing information that does not match your expectations. You can specify either a MinRate and/or a MaxRate or a FixedRate. Please note that the system will only consider the rental rate (taxes, optionals and coverages excluded) for given rate range. All monetary amounts are expected to be given in EUR. |
| VehPrefs | Optional vehicle preferences. Can be used to indicate a vehicle type preference. Use separate VehPref blocks for each preference, specifying the ACRISS code of the preferred type in the Code attribute of the VehMakeModel tag. The Name is ignored by the system and can be left empty. If in doubt, get in contact with the car rental company to get a list with available ACRISS codes. |
| (*) mandatory field | |
Response
After processing the request, the system will respond to the caller providing a set of pricing information matching the calling request. The quotes will appear in different VehAvail blocks that can be found in VehVendorAvails → VehVendorAvail → VehAvails. Furthermore, the response will contain the request's information about pickup/drop-off times and stations in the VehicleRentalCore to confirm the search parameters.
Each VehAvail block contains two elements. VehAvailCore provides information about the vehicle type linked to an offer together with rental pricing information and additional equipment that can be booked. The VehAvailInfo part provides information about available coverage options that can be booked for the given vehicle type. Since the equipment and coverage options are optional they are not included in the rental price and the total estimate in VehAvailCore → TotalCharge.
Please note, that all prices provided by the system are taxes excluded. For each charge however, you'll also find the TaxAmounts part summarizing the expected taxes. Only the field EstimatedTotalAmount of VehAvailCore → TotalCharge contains the rental price including taxes (but excluded any optional equipment and coverage options).
| VehAvailCore parameter | Description |
|---|---|
| Vehicle | The vehicle tag contains information about the vehicle type associated to the pricing information, such as the ACRISS code in the Code attribute and a textual Description. CodeContext specifies what to expect in Code field and will always be set to SIPP which refers to ACRISS code. If available, the vehicle element may contain a PictureURL child indicating the URL of an image file in order to illustrate the vehicle type. |
| TotalCharge | The total charge to expect when booking this option, taxes excluded (RateTotalAmount) and taxes and fees included (EstimatedTotalAmount). Please note that the total charge indicated here does not include any optional equipment or coverage options. Mandatory extras may be present however. |
| Rental Rate | Provides further information about the specific rental rate applied to this offer. The rate distance specifies distance limitations. If applicable (Unlimited="false") the DistUnitName together with the Quantity and VehiclePeriodUnitName indicate the maximum distance that is covered by the quote. If no limits apply, Unlimited will be set to true. The vehicle charges element provides a list of different charges that were considered for the calculation of the booking totals. The golden rule here is: Only vehicle specific charges (Purpose="1") will be included in the total rental rate (IncludedInRate and IncludedInEstTotalInd will always be true). Any other fees or mandatory extras will only be included in the estimated reservation totals (IncludedInEstTotalInd will be true). All charges are taxes excluded. The TaxAmounts child however indicates expected taxes that have to be added in order to get the full estimated rental price. As said before, additional fees or mandatory extras may be present in the vehicle charges list. When the system determines for example that either the pickup date and time or the return date and time are beyond office hours, another VehicleCharge element of type 82 (= Out of hours fee) might be present. Another VehicleCharge element might be listed when a company takes extra fees for One way rentals, i.e. where the drop-off station is not the same as the pickup station. In this case a VehicleCharge element of type 2 (= Drop fee) might be present, following the same logic and restrictions as the out of hours fee. Please note, that any fee or extra being present as a VehicleCharge in the VehAvailRate response of a requested quote, has to be included in an eventual OTA_VehRes request in order to block a quote or make booking successfully. If you try to block a quote without a mandatory fee or extra, the system will not proceed with the operation and return an error. |
| PricedEquips | Gives you a list of optional equipment that can be booked together with the vehicle. Each PricedEquip element provides information about the equipment itself including the OpenTravel Code List Equipment Type (EQP) in the EquipType attribute and a textual Description, as well as pricing information provided by the Charge element. As said before, equipment prices are never included in the rate totals of an availability response, so IncludedInRate and IncludedInEstTotalInd will always be false. In case a listed equipment is countable, a Quantity="1" attribute will be present within the Equipment tag. In this case, the corresponding Charge element indicates the pricing information for a single piece of equipment. Please note, that if EquipType is set to 39 (= other) booking a specific equipment might not succeed. In this case get in contact with the car rental company and ask them to properly set the equipment type for registered optionals via their control panel. Most of the EQP codes are defined by the standard, to have a complete overview of the supported codes (check with the rental company!) refer to the following list: 1: Mobile phone / Cellulare 2: Bike rack / Portabiciclette 3: Luggage rack / Portabagagli 4: Ski rack / Portasci 5: Trailer hitch / Gancio di traino 6: Automatic locks / Chiusura automatica 7: Infant child seat / Seggiolino per bambini 8: Child toddler seat / Seggiolino per neonato 9: Booster seat / Rialza per bambini 10: Snow chains / Catene da neve 11: Hand control right / Hand control (destra) 12: Hand control left / Hand control (sinistra) 13: Navigational system / Navigatore 14: Snow tires / Pneumatici invernali 15: Baby stroller / Passegino 16: DVD player monitor / DVD 17: VCR player monitor / VCR 18: Spinner knob / Manopola sul volante 19: Furniture pads / Cuscinetti per mobili 20: Car dolly / Carrello auto 21: Auto transport / Trasporto auto 22: Hand truck / Carrello per sacchi 23: Cargo barrier front / Barriera del carico (anteriore) 24: Cargo barrier rear / Barriera del carico (posteriore) 25: Luggage trailer / Rimorchio per bagagli 26: Camping equipment / Attrezzi campeggio 27: Satellite radio / Radio satellitare 28: Wheelchair accessible van / Veicolo accessibile con sedia a rotelle 29: Seat belt extensions / Prolunghe della cintura di sicurezza 30: Winter package / Pacchetto invernale 31: Citizen band radio / Baracchino 32: Computerized directions / Computerized directions 33: FM radio / Radio 34: Navigational phone / Cellulare con navigatore 35: Ski rental / Noleggio sci 36: Ski equipped / Attrezzatura sci 37: Cassette player / Mangianastri 38: Television / TV 39: Other [do not use] / Altro 40: Portable DVD/CD/picture player / DVD/CD portatile 41: Multimedia centre / Multimedia center 42: Flag holder / Portabandiera 43: Motorcycle helmet / Casco 44: Jerrycan / Tanica 45: Luggage roof case / Portapacchi (tetto) 46: Hand-held navigation system / Navigatore portatile 47: Snow board rack / Porta snowboard 48: Ski box / Box per sci 49: Surf rack / Porta surf 50: Scooter case / Bauletto per scooter 51: Car telephone / Telefono 52: Toll payment tag/pass / Dispositivo per pagamenti pedaggi 53: Additional spare tire / Ruota di scorta 54: Wheelchair / Sedia a rotelle 55: WiFi Access / WIFI 56: Road/congestion payment scheme / Road/congestion payment scheme 57: Booster cushion / Cuscino riduttore 58: Trolley / Carrello 59: Carbon offset / Carbon offset 60: Security devices / Dispositivi sicurrezza 61: Travel Tab / Travel tab 101: Additional driver / Conducente addizionale 102: Young Driver / Young Driver 103: Road assistance / Assistenza stradale 104: Fuel Antifreeze / Fuel Antifreeze 105: Child seat (generic) / Child seat (generic) 150: Generic code 1 / Generico 1 151: Generic code 2 / Generico 2 152: Generic code 3 / Generico 3 153: Generic code 4 / Generico 4 154: Generic code 5 / Generico 5 155: Generic code 6 / Generico 6 156: Generic code 7 / Generico 7 157: Generic code 8 / Generico 8 158: Generic code 9 / Generico 9 159: Generic code 10 / Generico 10 160: Generic code 11 / Generico 11 161: Generic code 12 / Generico 12 162: Generic code 13 / Generico 13 163: Generic code 14 / Generico 14 164: Generic code 15 / Generico 15 165: Generic code 16 / Generico 16 166: Generic code 17 / Generico 17 167: Generic code 18 / Generico 18 168: Generic code 19 / Generico 19 169: Generic code 20 / Generico 20 200: Out of hours checkout / Fuori orario checkout 210: One way / One way 250: Out of hours checkin / Fuori orario checkin |
| VehAvailInfo parameter | Description |
| PricedCoverages | Provides a list with coverage options that may be booked together with the vehicle. Each PricedCoverage element specifies information about the coverage itself in the Coverage element and pricing information in Charge. Each option comes with a unique identifier in the Code attribute that is needed in case you want to book an option. CoverageType provides details about the type of coverage and will be set to 21 (= insurance). This might change in the future in order to provide more information using a more detailed OpenTravel Code List Vehicle Coverage Type (VCT). The Details child gives you a textual description of the coverage option. The coverage charges are similar to equipment charges and are not further explained here. The Deductible elements specifies the deductible amount for this coverage option. |
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehAvailRateRQ>
<VehAvailRQCore>
<VehRentalCore PickUpDateTime="2020-03-02T18:00:00Z"
ReturnDateTime="2020-03-06T18:00:00Z">
<PickUpLocation LocationCode="98107384"/>
<ReturnLocation LocationCode="98107384"/>
</VehRentalCore>
<RateRange CurrencyCode="EUR" MinRate="10.00" MaxRate="40.00"/>
<VehPrefs>
<VehPref>
<VehMakeModel Code="CDAR" Name=""/>
</VehPref>
</VehPrefs>
</VehAvailRQCore>
</ns1:OTA_VehAvailRateRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehAvailRateRS>
<ns1:VehAvailRSCore>
<VehRentalCore PickUpDateTime="2020-03-02T18:00:00Z"
ReturnDateTime="2020-03-06T18:00:00Z">
<PickUpLocation LocationCode="98107384"/>
<ReturnLocation LocationCode="98107384"/>
</VehRentalCore>
<VehVendorAvails>
<VehVendorAvail>
<VehAvails>
<VehAvail>
<VehAvailCore>
<Vehicle Code="CDAR" CodeContext="SIPP"
Description="Gruppo B Automatica (Km illimitati)">
<PictureURL>http://url/to/image</PictureURL>
</Vehicle>
<TotalCharge CurrencyCode="EUR" RateTotalAmount="40.00"
EstimatedTotalAmount="48.80"/>
<RentalRate>
<RateDistance Unlimited="false" DistUnitName="km"
Quantity="1000" VehiclePeriodUnitName="Day"/>
<VehicleCharges>
<VehicleCharge Purpose="1" TaxInclusive="false"
IncludedInEstTotalInd="true" IncludedInRate="true"
Description="" Amount="40" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22"
Total="8.80"/>
</TaxAmounts>
</VehicleCharge>
</VehicleCharges>
</RentalRate>
<PricedEquips>
<PricedEquip>
<Equipment EquipType="39">
<Description>Navigatore</Description>
</Equipment>
<Charge IncludedInEstTotalInd="false"
IncludedInRate="false" TaxInclusive="false"
Amount="40.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22"
Total="8.80"/>
</TaxAmounts>
</Charge>
</PricedEquip>
<PricedEquip>
<Equipment EquipType="39">
<Description>Portasci</Description>
</Equipment>
<Charge IncludedInEstTotalInd="false"
IncludedInRate="false" TaxInclusive="false"
Amount="100.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22"
Total="22.00"/>
</TaxAmounts>
</Charge>
</PricedEquip>
<!-- Other PricedEquip blocks with further optionals
to book -->
</PricedEquips>
</VehAvailCore>
<VehAvailInfo>
<PricedCoverages>
<PricedCoverage>
<Coverage Code="23" CoverageType="21">
<Details CoverageTextType="Copertura Standard"/>
</Coverage>
<Charge TaxInclusive="false"
Description="Copertura Standard"
Amount="0" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22"
Total="0.00"/>
</TaxAmounts>
</Charge>
<Deductible CurrencyCode="EUR" Amount="1200.00"/>
</PricedCoverage>
<PricedCoverage>
<Coverage Code="18" CoverageType="21">
<Details CoverageTextType="Mini-Kasko"/>
</Coverage>
<Charge TaxInclusive="false"
Description="Mini-Kasko"
Amount="58" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22"
Total="12.76"/>
</TaxAmounts>
</Charge>
<Deductible CurrencyCode="EUR" Amount="600.00"/>
</PricedCoverage>
<!-- Other PricedCoverage blocks with further coverage options
to book -->
</PricedCoverages>
</VehAvailInfo>
</VehAvail>
<!-- Other VehAvail blocks with further quotes -->
</VehAvails>
</VehVendorAvail>
</VehVendorAvails>
</ns1:VehAvailRSCore>
</ns1:OTA_VehAvailRateRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_VehLocSearch
The OTA_VehLocSearch function can be used to retrieve a list of available pickup/drop-off stations of the car rental company. It may be called without any search criterions to get a full list of available stations.
Request
If you are not interested in a complete list of available stations, use search criterions to filter the results. At the moment address information of the stations are non-formatted and thus the filtering functionality is limited.
| Request parameter | Description |
|---|---|
| VehLocSearchCriterion | The only filter accepted at the moment is the Address → CityName parameter. Depending on the information that each car rental company provides, this parameter can however be used to search for a specific city name, airport code, ecc. |
Response
After processing the request, the system will respond to the caller providing a list of localities where rented vehicles can be picked up or dropped off. Each locality comes in a separate VehMatchedLoc element with a LocationDetail child containing all the information.
| Response parameter | Description |
|---|---|
| Code | Provides a unique identifier needed for booking and availability requests. |
| Name | Name of the locality |
| Address | Provides further information about the locality, such as its address in a non-formatted way using the AddressLine tags and CityName the name of the city where the locality can be found. |
| AdditionalInfo → OperationSchedules | Provides information about the opening hours of the locality. Each OperationSchedule block may specify the opening hours for a certain period or day (specified by the Start and End tags) or may be valid for a certain day of the week in general (Mon to Sun tags set to true in the corresponding OperationTimes → OperationTime element). The information about the operation times should be interpreted as follows:
|
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehLocSearchRQ>
<VehLocSearchCriterion>
<Address>
<CityName>APT</CityName>
</Address>
</VehLocSearchCriterion>
</ns1:OTA_VehLocSearchRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehLocSearchRS>
<ns1:VehMatchedLocs>
<ns1:VehMatchedLoc>
<ns1:LocationDetail Code="98107384" Name="Milano-MXP">
<Address Remark="MI-MXP">
<AddressLine>APT Malpensa (MI)</AddressLine>
<AddressLine>Lun-Ven:08:00/22:00</AddressLine>
<AddressLine>Sab:09:00/18:30</AddressLine>
<AddressLine>Tel:+39 02-123456</AddressLine>
<CityName>Milano - Malpensa</CityName>
</Address>
<AdditionalInfo>
<OperationSchedules>
<OperationSchedule Start="2022-12-24" End="2022-12-24">
<OperationTimes>
<OperationTime Start="08:00" End="20:00" Mon="true" Tue="true" Weds="true" Thur="true" Fri="true" Sat="true" Sun="true" Priority="100" />
</OperationTimes>
</OperationSchedule>
<OperationSchedule Start="2022-12-25" End="2022-12-26">
<OperationTimes>
<OperationTime Start="08:00" End="18:00" Mon="true" Tue="true" Weds="true" Thur="true" Fri="true" Sat="true" Sun="true" Priority="100" />
</OperationTimes>
</OperationSchedule>
<OperationSchedule Start="2022-12-31" End="2022-12-31">
<OperationTimes>
<OperationTime Start="08:00" End="18:00" Mon="true" Tue="true" Weds="true" Thur="true" Fri="true" Sat="true" Sun="true" Priority="100" />
</OperationTimes>
</OperationSchedule>
<OperationSchedule Start="2023-01-01" End="2023-01-01">
</OperationSchedule>
<!-- Other OperationSchedule blocks with operation times for other days -->
<OperationSchedule Start="2022-01-01" End="2030-12-31">
<OperationTimes>
<OperationTime Start="07:00" End="23:00" Mon="true" Tue="true" Weds="true" Thur="true" Fri="true" Priority="10" />
<OperationTime Start="07:00" End="13:00" Sat="true" Priority="10" />
</OperationTimes>
</OperationSchedule>
</OperationSchedules>
</AdditionalInfo>
</ns1:LocationDetail>
</ns1:VehMatchedLoc>
<!-- Other VehMatchedLoc blocks with further stations -->
</ns1:OTA_VehLocSearchRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_VehModify
The OTA_VehModify function can be used to confirm a reservation that has previously been initiated via the OTA_VehRes function. The rental company may have defined a timeout (usually 10 minutes) that gives you a maximum time that may pass between the OTA_VehRes call and the confirmation before a reservation will be canceled automatically. Once canceled, you won't be able to confirm the reservation anymore. If in doubt, get in contact with the car rental company to find out whether and what timeout was defined for your account.
Please note, that at this stage the function can only be used to confirm a previously initiated reservation. No other modifications are allowed.
Request
In order to use the function to confirm a reservation, the reservation should have already been initiated via the OTA_VehRes function which returned you a unique reservation reservation of Type=16. This ID (or ConfID as it is entitled in the OTA_VehRes response) has to be used to confirm the reservation.
| Request parameter | Description |
|---|---|
| UniqueID* | The unique reservation reference that the system returned to you in the response of the OTA_VehRes function call. Only the unique reference of Type="16" can be used for the OTA_VehModify function. |
| VehModifyRQCore* | Include this tag with the attribute ModifyType="Book" to indicate that you want to confirm the reservation. |
| VehModifyRQInfo | Contains the RentalPaymentPref tag that can be used to specify details about an eventual pre-payment. The structure of the RentalPaymentPref tag is the same as is the case for the OTA_VehRes function call. |
| (*) mandatory field | |
Response
Upon successful processing of a OTA_VehModify request the full reservation record will be returned to the caller. This is the same as the result of a OTA_VehRetRes call and is described more in detail there.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-Env:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-Env:Body>
<ns1:OTA_VehModifyRQ>
<UniqueID Type="16" ID="123456"/>
<VehModifyRQCore ModifyType="Book"/>
<VehModifyRQInfo>
<RentalPaymentPref>
<Voucher Identifier="2144454359350886"/>
<PaymentAmount CurrencyCode="EUR" Amount="139.86"/>
</RentalPaymentPref>
</VehModifyRQInfo>
</ns1:OTA_VehModifyRQ>
</SOAP-Env:Body>
</SOAP-Env:Envelope>
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehModifyRS>
<ns1:Success/>
<VehModifyRSCore ModifyStatus="Book">
<VehReservation ReservationStatus="Reserved">
…
</VehReservation>
</VehModifyRSCore>
</ns1:OTA_VehModifyRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
OTA_VehRes
The OTA_VehRes function can be used to block a quote or make a reservation. The information that have to provided when making the request have to be taken from a previously performed OTA_VehAvailRate request.
Request
In order to block a quote or make a reservation, you need to specify a series of parameters that are described in the following. Most of them are child elements of the VehResRQCore element. Only the details about the preferred coverage option to book has to be put into the VehResRQInfo element.
Pricing information have to be taken from the response of a previously made OTA_VehAvailRate call. Once the system receives a OTA_VehRes request, it performs an internal availability check to get actual quote information and only accepts the quote to be blocked or the reservation to be made if the prices from the request match the result from the internal check. It is thus important that you put monetary amounts from the availability request without modifying into the OTA_VehRes request, otherwise it will be refused.
| VehResRQCore parameter | Description |
|---|---|
| VehRentalCore* | Describes the basic rental parameters as described for the OTA_VehAvailRate request. |
| VehPref* | Use the Code attribute of the VehMakeModel child element to specify the ACRISS code of the vehicle type that you would like to book. For more details about the VehPref element have a look at the OTA_VehAvailRef function. |
| Customer* | Provides basic information about the primary customer and any additional customers. In order block a quote or make a reservation successfully at least the Name of the Primary customer has to be provided. Alternatively, if you have performed a booking for the same client and know its unique identifier you can also provide the CustomerID as shown in the example to recall the customer details from a previous booking. The following elements can be used to describe the primary and any additional customer. |
| - BirthDate | Indicates the date of birth of the customer and has to be given as an attribute of the Primary or Additional customer tag respectively. |
| - PersonName* | Specifies the name of the customer. At the moment, only the GivenName and the Surname are considered by the system. Please note that for every customer record, at least the Surname has to be given. |
| - Document | Used to provide information about a legal document of the customer. DocType defines the type of the document that is presented. Use either 2 for passports, 4 for driver's licenses and 5 for national identify documents. Please note that passports and national ids are treated equally by the system and will always be returned as national id documents. DocID specifies the actual document number, DocIssueAuthority the authority that has issued the document and EffectiveDate and ExpireDate the validity period. |
| - Telephone | Telephone number (preferably) including the national prefix to be given as PhoneNumber attribute. |
| Valid email address of the customer | |
| - Address | Address information of the customer. While most fields are self-explaining please note that the CountryName has to be the ISO 3166 two-letter code. |
| - CustomerID | Use this element to specify the unique identifier of a previously registered customer to recall its information automatically. Type has to be 1 (= customer) and ID the unique identifier (from the CRS context!) of the customer. This id can be retrieved from the same CustomerID field of the Customer element of an existing reservation. Please not that the CustomerID can only be used for the Primary customer. |
| VehicleCharges* | Lists all the charges that have to be applied to the quote to be blocked or the reservation to be made. Have a look at the OTA_VehAvailRate function to learn more about vehicle charges. Please note that while the charges listed in the OTA_VehAvailRate response contain only charges related to the vehicle itself and other mandatory fees or extras, in a OTA_VehRes request you also have to list the charges of all additional equipment and coverage options that you want to include in the booking as well. Use the Purpose attribute of every VehicleCharge record to indicate what the charge is related to. Use 1 for charges related to the vehicle rental, 82 for out of hours fees (if present), 2 for one way fees (if present), 21 for any equipment to book and 4 for a coverage option. Similarly to the response of a OTA_VehAvailRate response, these additional equipment charges should not be included in the rate (IncludedInRate="false"). Together with the estimated taxes they have to be included in the estimated totals (IncludedInEstTotalInd="true") though. In case a countable equipment has to be added to the booking, a separate charge has to be added for each piece, i.e. if you would like to add two child seats to the booking, add the child seat charge to the VehicleCharges twice. |
| SpecialEquipPrefs | List with additional equipment that has to be included in the booking. Since equipment charges have to be put into the VehicleCharges part of the request, it is sufficient to provide only the equipment type via the EquipType attribute. Use the Quantity attribute to indicate the desired quantity of countable extras. |
| TotalCharge | Specifies the total charge of the quote to block or the reservation to make. The RateTotalAmount is the sum of car rental specific charges only (taxes excluded), while EstimatedTotalAmount considers all the charges including taxes. |
| VehResRQInfo parameters | Description |
| ResStatus | The ResStatus attribute of the VehResRQInfo allows you to specify whether you simply want to block a quote or whether you want to make a booking. Booking can either be done by confirming a reservation straightaway or by using a two-step booking procedure that allows you to first, initiate a booking, then perform other steps (like processing a payment) in-between and afterwards confirming the booking to block an actual vehicle. If you intend to you the two-step procedure set the ResStatus="Initiate". This will signal to the system that the reservation it creates still has to be confirmed. In order to do so, you'll have to use the OTA_VehModify function later on. Please note, the car rental company may have defined a timeout (usually 10min) that gives you a maximum time frame for confirming the booking. If you do not make it in time to confirm the booking, it will be canceled automatically and you won't be able to confirm it anymore. However, if in doubt, contact the car rental company to get to know whether it has defined a timeout and what it is in detail. If you'd like to create a reservation that is confirmed straightaway sest ResStatus="Book". In case this parameter is not given, the system will simply block the quote for the given client. Quotes are usually valid for one week before they expire. |
| CoveragePrefs | Use the CoveragePrefs → CoveragePref tag to indicate the coverage option to be included in the booking. CoverageType has to be set to 21 (= insurance) while Code has to be the code taken from the appropriate record of the respective availability search. |
| RentalPaymentPref | Use this field in case a reservation is made and you want to inform the car rental company about a pre-payment that was made by the client. PaymentAmount takes information about the amount that has been paid. For every payment, also a Voucher with a valid Identifier has to be given in order to identify the payment. |
| (*) mandatory field | |
Response
Upon successful processing of a OTA_VehRes request the full reservation record will be returned to the caller. This is the same as the result of a OTA_VehRetRes call and is described more in detail there.
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehResRQ>
<VehResRQCore>
<VehRentalCore PickUpDateTime="2020-03-03T09:36:53Z" ReturnDateTime="2020-03-07T09:36:53Z">
<PickUpLocation LocationCode="98107384"/>
<ReturnLocation LocationCode="98107384"/>
</VehRentalCore>
<VehPref>
<VehMakeModel Code="CDAR" Name=""/>
</VehPref>
<Customer>
<Primary BirthDate="2000-05-13">
<PersonName>
<GivenName>John</GivenName>
<Surname>Smith</Surname>
</PersonName>
<Document DocType="5" DocID="ABCDEF33" DocIssueAuthority="City of Washington D.C."
EffectiveDate="2017-01-01" ExpireDate="2021-12-31"/>
<Telephone PhoneNumber="555555"/>
<Email>j.smith@domain.com</Email>
<Address>
<AddressLine>543, 5th Avenue</AddressLine>
<CityName>Washington</CityName>
<CountryName>US</CountryName>
<PostalCode>1234</PostalCode>
<StateProv>DC</StateProv>
</Address>
<!-- Customer ID may be used if customer is already registered and you have
the CRS's uid -->
<!-- CustomerID Type="1" ID="{customer uid}" /-->
</Primary>
<Additional BirthDate="2002-07-25">
<PersonName>
<GivenName>Emily</GivenName>
<Surname>Smith</Surname>
</PersonName>
<Telephone PhoneNumber="555555"/>
<Address>
<AddressLine>543, 5th Avenue</AddressLine>
<CityName>Washington</CityName>
<CountryName>US</CountryName>
<PostalCode>1234</PostalCode>
<StateProv>DC</StateProv>
</Address>
</Additional>
</Customer>
<VehicleCharges>
<VehicleCharge Purpose="1" TaxInclusive="false" IncludedInEstTotalInd="true" IncludedInRate="true" Description="" Amount="40" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="8.80"/>
</TaxAmounts>
</VehicleCharge>
<VehicleCharge Description="Navigatore" IncludedInEstTotalInd="true" IncludedInRate="false" Purpose="21" TaxInclusive="false" Amount="40.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="8.80"/>
</TaxAmounts>
</VehicleCharge>
<VehicleCharge Description="Portasci" IncludedInEstTotalInd="true" IncludedInRate="false" Purpose="21" TaxInclusive="false" Amount="100.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="22.00"/>
</TaxAmounts>
</VehicleCharge>
<VehicleCharge Description="Seggiolino" IncludedInEstTotalInd="true" IncludedInRate="false" Purpose="21" TaxInclusive="false" Amount="32.80" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="7.22"/>
</TaxAmounts>
</VehicleCharge>
<VehicleCharge Description="[Cod. 2-B] Mini-Kasko" IncludedInEstTotalInd="true" IncludedInRate="false" Purpose="4" TaxInclusive="false" Amount="58.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="12.76"/>
</TaxAmounts>
</VehicleCharge>
</VehicleCharges>
<SpecialEquipPrefs>
<SpecialEquipPref EquipType="13"/>
<SpecialEquipPref EquipType="4"/>
<SpecialEquipPref EquipType="7"/>
</SpecialEquipPrefs>
<TotalCharge CurrencyCode="EUR" RateTotalAmount="40.00" EstimatedTotalAmount="330.38"/>
</VehResRQCore>
<VehResRQInfo ResStatus="Book">
<CoveragePrefs>
<CoveragePref Code="18" CoverageType="21"/>
</CoveragePrefs>
<RentalPaymentPref>
<PaymentAmount Amount="100.00" CurrencyCode="EUR"/>
<Voucher Identifier="VOU-123"/>
</RentalPaymentPref>
</VehResRQInfo>
</ns1:OTA_VehResRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehResRS>
<ns1:VehResRSCore>
<VehReservation ReservationStatus="Reserved">
<!-- Vehicle reservation details -->
</VehReservation>
</ns1:VehResRSCore>
</ns1:OTA_VehResRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_VehRetRes
The OTA_VehRetRes function can be used to retrieve a previously performed reservation or blocked quote. All you need to request the reservation details is the reservation's uid/reference.
Request
After blocking a quote or making a reservation successfully, the system returns the full reservation to the caller. This record contains a unique reservation reference that has to be given to this function in order to recall all the reservation details.
| Request parameter | Description |
|---|---|
| UniqueID* | Use the ID field of this element of the VehRetResRQCore block to provide the unique reference of the reservation that you are requesting the details for. Note that for a reservation lookup only references of Type="16" (= reference) are valid. |
| (*) mandatory field | |
Response
Upon successful processing of a OTA_VehRetRes request the full reservation record will be returned to the caller enclosed in a VehReservation tag. As illustrated in the example, this record is very similar to the data provided during a OTA_VehRes request and will only be described very briefly.
| Response parameter | Description |
|---|---|
| ReservationStatus | This attribute of the VehReservation indicates whether the reservation record refers to a blocked quote or a booking. For the former, ReservationStatus will be set to Requested. If you used the two-step procedure to first create and then confirm the booking, ReservationStatus may take the value Initiate. In this case you still have to use the OTA_VehModify function to confirm the booking. If the status is set to Reserved the reservation has been confirmed. If you find the status Cancelled the reservation has been cancelled. |
| Customer | Lists the customers that are linked to the reservation. You should always find the Primary customer information with a valid CustomerID that you may use for later reference. For a more detailed description of all the other fields refer to the OTA_VehRes description. |
| VehSegmentCore | This element contains the same information as described for the VehAvailCore element of the OTA_VehAvailRate response and does not need much explanation. Just two notes: 1) Since the CRS system only works with UTC timestamps internally, the PickUpDateTime and ReturnDateTime attributes of the VehRentalCore will be given in UTC (identifiable by the Z suffix). However, in order to enhance readability, another two attributes PickUpLocalDateTime and ReturnLocalDateTime are provided as well specifying the pickup and return dates/times in local time (considering the timezone of the car rental company). 2) While equipment options of the OTA_VehAvailRate response are never included in the TotalCharge this may be different for an actual reservation record as in this case, all equipment options that have actually been included in the reservations will be considered for the EstimatedTotalAmount attribute of the TotalCharge. Hence, if the IncludedInEstTotalInd attribute is set to true for an equipment option it can be considered included in the quote/booking. Additionally to the previously described information you can find two ConfID values. One will be of Type=16 which gives you the unique reservation reference that you'll need to look up the reservation again afterwards. The other gives you a more readable quote (Type="23", provisional reservation), reservation (Type="14") or contract (Type="39") number depending on the progress of the given reservation record. This second ConfID is provided for information purposes only and may not be used to recall reservation information through this API. It might be useful however for operators of a car rental company, in case you need personal support for a reservation. |
| VehSegmentInfo | Again, this part of the response is similar to its VehAvailInfo counterpart of a OTA_VehAvailInfo response containing available coverage options that can be included in the booking. In case there is one PricedCoverage option with IncludeInEstTotalInd="true" it can be considered included in the quote or reservation. |
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehRetResRQ>
<VehRetResRQCore>
<UniqueID Type="16" ID="{reservation reference}"/>
</VehRetResRQCore>
</ns1:OTA_VehRetResRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehRetResRS>
<ns1:VehRetResRSCore>
<VehReservation ReservationStatus="Reserved">
<Customer>
<Primary BirthDate="2000-05-13">
<CustomerID Type="1" ID="75854"/>
<PersonName>
<GivenName>John</GivenName>
<Surname>Smith</Surname>
</PersonName>
<Telephone PhoneNumber="555555"/>
<Email>j.smith@domain.com</Email>
<Address>
<AddressLine>543, 5th Avenue</AddressLine>
<CityName>Washington</CityName>
<CountryName>US</CountryName>
<PostalCode>1234</PostalCode>
<StateProv>DC</StateProv>
</Address>
<Document DocType="5" DocID="ABCDEF33" DocIssueAuthority="City of Washington D.C."
EffectiveDate="2017-01-01" ExpireDate="2021-12-31"/>
</Primary>
<!-- Additional customer information if available -->
</Customer>
<VehSegmentCore>
<ConfID Type="16" ID="71603"/>
<ConfID Type="14" ID="2020/00003 MI-MXP"/>
<VehRentalCore PickUpDateTime="2020-03-03T09:36:53Z"
ReturnDateTime="2020-03-07T09:36:53Z"
PickUpLocalDateTime="2020-03-03T10:36:53"
ReturnLocalDateTime="2020-03-07T10:36:53">
<PickUpLocation LocationCode="98107384"/>
<ReturnLocation LocationCode="98107384"/>
</VehRentalCore>
<Vehicle Code="CDAR" CodeContext="SIPP">
<VehMakeModel Code="CDAR"/>
</Vehicle>
<RentalRate>
<RateDistance Unlimited="false" DistUnitName="km" Quantity="1000" VehiclePeriodUnitName="Day"/>
<VehicleCharges>
<VehicleCharge Purpose="1" TaxInclusive="false" IncludedInEstTotalInd="true"
IncludedInRate="true" Description="2018 (km illimitati)" Amount="40" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="8.80"/>
</TaxAmounts>
</VehicleCharge>
</VehicleCharges>
</RentalRate>
<PricedEquips>
<PricedEquip>
<Equipment EquipType="13">
<Description>Navigatore</Description>
</Equipment>
<Charge IncludedInEstTotalInd="true" IncludedInRate="false" TaxInclusive="false"
Amount="40.00" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="8.80"/>
</TaxAmounts>
</Charge>
</PricedEquip>
<!-- Other PricedEquip blocks with further optionals
to book -->
</PricedEquips>
<TotalCharge CurrencyCode="EUR" RateTotalAmount="40.00" EstimatedTotalAmount="330.38"/>
</VehSegmentCore>
<VehSegmentInfo>
<PricedCoverages>
<PricedCoverage>
<Coverage Code="23" CoverageType="21">
<Details CoverageTextType="[Cod. 2-A] - Copertura Standard"/>
</Coverage>
<Charge IncludeInEstTotalInd="false" TaxInclusive="false"
Description="[Cod. 2-A] - Copertura Standard" Amount="0" CurrencyCode="EUR">
<TaxAmounts>
<TaxAmount CurrencyCode="EUR" Percentage="22" Total="0.00"/>
</TaxAmounts>
</Charge>
<Deductible CurrencyCode="EUR" Amount="1200.00"/>
</PricedCoverage>
<!-- Other PricedCoverage blocks with further coverage options
to book -->
</PricedCoverages>
</VehSegmentInfo>
</VehReservation>
</ns1:VehRetResRSCore>
</ns1:OTA_VehRetResRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>OTA_VehCancel
The OTA_VehCancel function can be used to cancel a previously performed reservation. All you need to do so is the reservation's uid/reference.
Request
After making a reservation successfully, the system returns the full reservation to the caller. This record contains a unique reservation reference that has to be given to this function in order to cancel the reservation.
| Request parameter | Description |
|---|---|
| UniqueID* | Use the ID field of this element of the VehCancelRQCore block to provide the unique reference of the reservation that you are requesting to cancel. Note that for a reservation lookup only references of Type="16" (= reference) are valid. |
| (*) mandatory field | |
Response
Upon successful processing of a OTA_CancelRes request the system will respond to the caller confirming the cancellation of the reservation providing the CancelStatus="Cancelled" attribute of the VehCancelRSCore block.
| Response parameter | Description |
|---|---|
| CancelStatus | This attribute of the VehCancelRSCore indicates that the reservation has been cancelled and should be set to Cancelled. |
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehCancelRQ>
<VehCancelRQCore>
<UniqueID Type="16" ID="{reservation reference}"/>
</VehCancelRQCore>
</ns1:OTA_VehCancelRQ>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope><?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.opentravel.org/OTA/2003/05">
<SOAP-ENV:Body>
<ns1:OTA_VehCancelRS>
<ns1:Success/>
<VehCancelRSCore CancelStatus="Cancelled"/>
<VehCancelRSInfo/>
</ns1:OTA_VehCancelRS>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>CRS Booker API
Car Rental Software provides the CRS Booker API to its users, a RESTful web service available under https://carrentalsoftware.myappy.it/api/v1. The API is based on resource-oriented URLs used to identify, access or create system resources. Communication itself is based on standard HTTP response codes and authentication. Data is encoded with JSON. The interface is still under ongoing development but already offers a limited set of endpoints as described in this section.
As of now the CRS Booker API offers the following endpoints:
| Endpoint | Description |
|---|---|
| Client | The client endpoint can be used to retrieve or submit client details. |
| Client Driver | The client driver endpoint can be used to retrieve or submit driver details. |
| Client Reservation | The client reservation endpoint can be used to retrieve or submit booking details. |
| Client Reservation Update | Client reservation updates are used to integrate the information linked to a booking, e.g. submit personal details of drivers linked to an existing booking, upload documents, ecc. |
| Session | The session endpoint has to be used to retrieve session tokens needed to use all the other endpoints of the interface. |
API endpoints may depend on each other in order to identify the requested resources. For this reason, URLs of single endpoints may be concatenated. For instance, client reservation updates are linked to a single reservation which is why the URL that has to be used to create a new client reservation has the following format: client_reservation/:id/client_reservation_update where :id is the ID of the reservation for which a client reservation update has to be created.
Authentication
Every API call has to provide proper authentication in order to let system identify the calling party. Therefore you need to include the Authorization HTTP header with a valid token whenever a request is sent to the server. The system differentiates between two token types: Basic tokens have the sole purpose of identification and can be generated by the caller using the API credentials provided by the car rental company. These tokens have to be used to retrieve Bearer tokens which on the other hand are necessary to access the major part of the system's resources.
Basic tokens
In order to use the CRS Booker API, request the API credentials from the car rental company. These come in pairs: A unique identifier (UID) and an API key. Your basic authentication token is the base64 encoded concatenation of the following string: {{UID}}:{{API_KEY}}. To signal to the server that a basic token is used for authentication for a specific request, set the Authorization header of the HTTP request as follows: Authorization: Basic {{BASIC_TOKEN}}.
Basic tokens are valid until the credentials are revoked. For this reason it is important to not share the credentials with any non-authorized party and to signal any misuse or doubt about a possibile leakage to the rental company or My Appy.
Bearer tokens
Bearer tokens are temporary and can be requested via the session/token endpoint. They can be used to access the major part of available system resources until they expire or are revoked.
To signal to the server that a bearer token is used for authentication for a specific request, set the Authorization header of the HTTP request as follows: Authorization: Bearer {{BEARER_TOKEN}}.
Please note that all API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without a valid Authorization header will also fail.
Authorization: Basic MTIzNDU2OkFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaAuthorization: Bearer AD43t4asdfasdflkj4taSDF4talkjasdfl4ntalkjsdfljktnasDOIGBJOLKXCVSKJGHAPJKXCError handling
The CRS Booker API uses HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success while codes in the 5xx range indicate an error with either the information provided with the API request or the server (these are rare).
Every response from the server returns JSON encoded data (if not stated otherise) and should contain the success property indicating that the request has been processed successfully or not and additionally an error property indicating one or more errors that occurred during the elaboration of the request. For some error, the system also provides a human readable message describing in more detail the error that occurred.
For successful requests, you'll also find the result property containing the requested data.
{
"success": true,
"result": {
"client_reservation": {
"uid": "123456",
"client_id": "12345"
// .,.
}
}
}{
"success": false,
"error": "_A0000/2",
"message": "",
}Expanding responses
Many endpoints allow you to request more than a single object in a single call via expanded responses. When a correlation exists between two endpoints, e.g. a client reservation and a client, usually one of the objects contain a ID referencing the correlated object. Instead of performing two API requests, one for each object to to request, you can indicate the correlated object with the expand parameter.
The expand parameter can be used whenever indicated in the endpoint description. It has to be passed to the server as a HTTP GET parameter and contains a comma-separated list of objects to expand.
GET /api/v1/client_reservation/123456?expand=client{
"success": true,
"result": {
"client_reservation": {
"uid": "123456",
"client_id": "12345",
// ...
},
"client": {
"uid": "12345",
// ...
},
}
}Data representation
As described before, most of the data transmitted to and from the platform will be JSON encoded. There are some data field types, though, that need special attention while using the CRS Booker API.
Date and Time
Date and time values throughout the system are always given in UTC and thus not reflecting the actual timezone where a certain rental company or one of its bases are located. The format of the time string is always YYYY-MM-DD hh:mm:ss with the hours always being given in the 24 hours format.
Please note, that even if a field is supposed to indicate a sole date value without considering the time, e.g. the date_of_birth attribute of a client, you'll always (if not indicated otherwise!) find a complete time string in UTC if the field is populated. In this case, the time would most probably indicate midnight (after being converted to the right timezone, respectively) of the given date. For instance if a client's date of birth is 5 Jun 1992, then the date_of_birth field would have the value 1992-06-04 22:00:00 for an Italian car rental company (Italy is in the CET timezone (UTC+1) but switches to summer time CEST (UTC+2) from late March to late October).
Countries
Countries have different representations throughout the system. They might be given with a country_id or a country string. If you find a country attribute you probably have to deal with the written name of the country or its ISO 3166-1 alpha-2 two letter code. Country IDs are numeric and fixed to the following values.
| Country ID | Country Name |
|---|---|
| 1 | AFGHANISTAN |
| 2 | ALBANIA |
| 3 | ALGERIA |
| 4 | ANDORRA |
| 5 | ANGOLA |
| 6 | ANGUILLA |
| 7 | ANTIGUA E BARBUDA |
| 8 | ANTILLE OLANDESI |
| 9 | ARABIA SAUDITA |
| 10 | ARGENTINA |
| 11 | ARMENIA |
| 12 | ARUBA |
| 13 | AUSTRALIA |
| 14 | AUSTRIA |
| 15 | AZERBAIGIAN |
| 16 | BAHAMAS |
| 17 | BAHRAIN |
| 18 | BANGLADESH |
| 19 | BARBADOS |
| 20 | BELGIO |
| 21 | BELIZE |
| 22 | BENIN |
| 23 | BERMUDA |
| 24 | BHUTAN |
| 25 | BIELORUSSIA |
| 26 | BIRMANIA |
| 27 | BOLIVIA |
| 28 | BONAIRE |
| 29 | BOSNIA ED ERZEGOVINA |
| 30 | BOTSWANA |
| 31 | BRASILE |
| 32 | BRUNEI |
| 33 | BULGARIA |
| 34 | BURKINA FASO |
| 35 | BURUNDI |
| 36 | CAMBOGIA |
| 37 | CAMERUN |
| 38 | CANADA |
| 39 | CAPO VERDE |
| 40 | CIAD |
| 41 | CILE |
| 42 | CINA |
| 43 | CIPRO |
| 44 | CITTÀ DEL VATICANO |
| 45 | COLOMBIA |
| 46 | COMORE |
| 47 | COREA DEL NORD |
| 48 | COREA DEL SUD |
| 49 | COSTA D'AVORIO |
| 50 | COSTA RICA |
| 51 | CROAZIA |
| 52 | CUBA |
| 53 | CURAÇAO |
| 54 | DANIMARCA |
| 55 | DOMINICA |
| 56 | ECUADOR |
| 57 | EGITTO |
| 58 | EL SALVADOR |
| 59 | EMIRATI ARABI UNITI |
| 60 | ERITREA |
| 61 | ESTONIA |
| 62 | ETIOPIA |
| 63 | FIGI |
| 64 | FILIPPINE |
| 65 | FINLANDIA |
| 66 | FRANCIA |
| 67 | GABON |
| 68 | GAMBIA |
| 69 | GEORGIA |
| 70 | GEORGIA DEL SUD E ISOLE SANDWICH MERIDIONALI |
| 71 | GERMANIA |
| 72 | GHANA |
| 73 | GIAMAICA |
| 74 | GIAPPONE |
| 75 | GIBUTI |
| 76 | GIORDANIA |
| 77 | GRECIA |
| 78 | GRENADA |
| 79 | GROENLANDIA |
| 80 | GUADALUPA |
| 81 | GUAM |
| 82 | GUATEMALA |
| 83 | GUINEA |
| 84 | GUINEA EQUATORIALE |
| 85 | GUINEA-BISSAU |
| 86 | GUYANA |
| 87 | GUYANA FRANCESE |
| 88 | HAITI |
| 89 | HONDURAS |
| 90 | HONG KONG |
| 91 | INDIA |
| 92 | INDONESIA |
| 93 | IRAN |
| 94 | IRAQ |
| 95 | IRLANDA |
| 96 | ISLANDA |
| 97 | ISOLA DEL NATALE |
| 98 | ISOLA NORFOLK |
| 99 | ISOLE CAYMAN |
| 100 | ISOLE COCOS E KEELING |
| 101 | ISOLE COOK |
| 102 | ISOLE FALKLAND |
| 103 | ISOLE MARIANNE SETTENTRIONALI |
| 104 | ISOLE MARSHALL |
| 105 | ISOLE PITCAIRN |
| 106 | ISOLE SALOMONE |
| 107 | ISOLE SPARSE NELL'OCEANO INDIANO |
| 108 | ISOLE VERGINI AMERICANE |
| 109 | ISOLE VERGINI BRITANNICHE |
| 110 | ISRAELE |
| 111 | ITALIA |
| 112 | KAZAKISTAN |
| 113 | KENYA |
| 114 | KIRGHIZISTAN |
| 115 | KIRIBATI |
| 240 | KOSOVO |
| 116 | KUWAIT |
| 117 | LAOS |
| 118 | LESOTHO |
| 119 | LETTONIA |
| 120 | LIBANO |
| 121 | LIBERIA |
| 122 | LIBIA |
| 123 | LIECHTENSTEIN |
| 124 | LITUANIA |
| 125 | LUSSEMBURGO |
| 126 | MACAO |
| 174 | MACEDONIA |
| 127 | MADAGASCAR |
| 128 | MALAWI |
| 129 | MALDIVE |
| 130 | MALESIA |
| 131 | MALI |
| 132 | MALTA |
| 133 | MAROCCO |
| 134 | MARTINICA |
| 135 | MAURITANIA |
| 136 | MAURITIUS |
| 137 | MAYOTTE |
| 138 | MESSICO |
| 139 | MOLDAVIA |
| 167 | MONACO |
| 140 | MONGOLIA |
| 141 | MONTENEGRO |
| 142 | MONTSERRAT |
| 143 | MOZAMBICO |
| 144 | NAMIBIA |
| 145 | NAURU |
| 146 | NEPAL |
| 147 | NICARAGUA |
| 148 | NIGER |
| 149 | NIGERIA |
| 150 | NIUE |
| 151 | NORVEGIA |
| 152 | NUOVA CALEDONIA |
| 153 | NUOVA ZELANDA |
| 154 | OMAN |
| 155 | PAESI BASSI |
| 156 | PAKISTAN |
| 157 | PALAU |
| 158 | PALESTINA |
| 159 | PANAMA |
| 160 | PAPUA NUOVA GUINEA |
| 161 | PARAGUAY |
| 162 | PERÙ |
| 163 | POLINESIA FRANCESE |
| 164 | POLONIA |
| 165 | PORTO RICO |
| 166 | PORTOGALLO |
| 168 | QATAR |
| 169 | REGNO UNITO |
| 170 | REPUBBLICA CECA |
| 171 | REPUBBLICA CENTRAFRICANA |
| 172 | REPUBBLICA DEL CONGO |
| 173 | REPUBBLICA DEMOCRATICA DEL CONGO |
| 175 | REPUBBLICA DOMINICANA |
| 176 | RIUNIONE |
| 177 | ROMANIA |
| 178 | RUANDA |
| 179 | RUSSIA |
| 180 | SABA |
| 181 | SAINT KITTS E NEVIS |
| 182 | SAINT VINCENT E GRENADINE |
| 183 | SAINT-BARTHÉLEMY |
| 184 | SAINT-MARTIN |
| 185 | SAINT-PIERRE E MIQUELON |
| 186 | SAMOA |
| 187 | SAMOA AMERICANE |
| 188 | SAN MARINO |
| 190 | SANT'ELENA, ASCENSIONE E TRISTAN DA CUNHA |
| 189 | SANTA LUCIA |
| 191 | SÃO TOMÉ E PRÍNCIPE |
| 192 | SENEGAL |
| 193 | SERBIA |
| 194 | SEYCHELLES |
| 195 | SIERRA LEONE |
| 196 | SINGAPORE |
| 197 | SINT EUSTATIUS |
| 198 | SINT MAARTEN |
| 199 | SIRIA |
| 200 | SLOVACCHIA |
| 201 | SLOVENIA |
| 202 | SOMALIA |
| 203 | SPAGNA |
| 204 | SRI LANKA |
| 205 | STATI FEDERATI DI MICRONESIA |
| 206 | STATI UNITI D'AMERICA |
| 207 | SUDAFRICA |
| 208 | SUDAN |
| 209 | SUDAN DEL SUD |
| 210 | SURINAME |
| 211 | SVEZIA |
| 212 | SVIZZERA |
| 213 | SWAZILAND |
| 214 | TAGIKISTAN |
| 215 | TAIWAN |
| 216 | TANZANIA |
| 217 | THAILANDIA |
| 218 | TIMOR EST |
| 219 | TOGO |
| 220 | TOKELAU |
| 221 | TONGA |
| 222 | TRINIDAD E TOBAGO |
| 223 | TUNISIA |
| 224 | TURCHIA |
| 225 | TURKMENISTAN |
| 226 | TURKS E CAICOS |
| 227 | TUVALU |
| 228 | UCRAINA |
| 229 | UGANDA |
| 230 | UNGHERIA |
| 231 | URUGUAY |
| 232 | UZBEKISTAN |
| 233 | VANUATU |
| 234 | VENEZUELA |
| 235 | VIETNAM |
| 236 | WALLIS E FUTUNA |
| 237 | YEMEN |
| 238 | ZAMBIA |
| 239 | ZIMBABWE |
Currencies
Monetary values are treated in the rental company's default currency. This is fixed and is not communicated in any way and has to be requested by the car rental company if in doubt. If not indicated otherwise, the platform uses the EUR (€) currency, though.
Files and attachments
While most of the CRS Booker API is about exchanging textual data, certain endpoints allow you to attach actual files to specific objects, such as the copy of a driver's ID or license. In order to upload a file to Car Rental Software use the guide below.
Uploading files
The procedure to upload a file is the same for all the various endpoints that expect a file attachment. Files can either be uploaded entirely with a single request or in smaller chunks that are then put together. In any case, the maximum allowed file size is 10MB.
Auth: Bearer token
Expandable: none
Files are uploaded to the platform via a series of POST requests to the same endpoint with the following data:
| Attribute | Description |
|---|---|
| base64 | Boolean indicating whether the transmitted data is base64 encoded or plaintext |
| data | The file data either in plaintext if the base64 attribute is either not present or set to false or in base64 encoding |
| filename | The name of the file being transmitted |
| offset | Offset in bytes of the data being transmitted relative to the beginning of the file. Use this parameter if you'd like to upload the file in chunks. For instance, if you have to upload a file of 2048KB you could send it in two chunks of 1024KB = 1024×1024 = 1048576 bytes each indicating an offset=0 for the first bit and an offset of 1048576 for the second chunk. |
After processing the request, the platform will return a new offset value which indicates the position where it stopped writing to the file which should correspond to your transmitted offset + the length of data (in plaintext!).
Once all the data has been transmitted to the server another POST request has to be sent to the same endpoint to confirm the upload. This is done by setting the confirm attribute to true. If during or after the transmission you would like to interrupt the operation instead, set the cancel attribute to true. In this case you signal to the server that you are not going to finish the upload and that you would like the platform to discard the data already submitted.
POST /api/v1/:endpoint
{
"base64": true
"data": "/9j/4AA...",
"filename": "license.jpg",
"offset": 0,
}{
"result":
{
"offset": 2005,
},
"success": true,
}{
"confirm": true,
"filename": "license.jpg"
}{
"cancel": true,
"filename": "license.jpg"
}Client
A client represents the entity that is responsible for a certain booking and which will be considered for invoicing. A client can thus be either a legal entity, such as a company or a public institution, or a physical person. Please note that direct access to client objects are not permitted at this stage which is why there is no endpoint available right now.
Client object
The client object stores basic information about a person or a legal entity. Address information are related to the person's residence or the legal entity's main office.
| Attribute | Description |
|---|---|
| uid | The unique reference of the client |
| address | The main address line indicating the street name and house number. |
| city | City, district, suburb, town, or village. |
| contact_person | Contact person's name in case the client object is representing a legal entity |
| country | Two-letter country code (ISO 3166-1 alpha-2) |
| country_id | Internally used ID of the country |
| date_of_birth | Client's date of birth |
| Client email address | |
| first_name | Client's given name and any additional middle names if present. This field may not be populated if the object is representing a legal entity |
| name | Client's surname of name of the legal entity. |
| pec | Certified email address |
| phone | Phone number |
| place_of_birth | The city where the person was born |
| province | The two-letter code of the province or state where the city is located (the compilation of this field depends on the indicated country) |
| sdi_code | Unique identifier used for electronic invoicing in Italy |
| tax_number | The client's tax number |
| type | The client object's type. This might be on of the following: business Private business business_consortium Group of different businesses one_man_business Private business identified solely by the owner's tax number one_man_business_wvn Private business identified by the owner's tax number and the business's VAT number private Physical person public_amm Public institution |
| vat_number | The business VAT number |
| zip_code | ZIP or postal code |
{
"uid": "400278",
"address": "Via Roma 1",
"city": "Palermo",
"contact_person": null,
"country_id": "111",
"date_of_birth": "1992-06-04 22:00:00",
"email": "francesco.rossi.134634@gmail.com",
"first_name": "Francesco",
"name": "Rossi",
"pec": null,
"phone": "+393112234567",
"place_of_birth": "Palermo",
"province": "PA",
"sdi_code": null,
"tax_number": null,
"type": "private",
"vat_number": null,
"zip_code": "90100",
}Client driver
A client driver object stores information about the physical person that is supposed to conduct the rented vehicle. A client reservation may have registered more than one client driver. Please note that direct access to client driver objects are not permitted at this stage which is why there is no endpoint available right now.
Client driver object
The client driver object stores basic information about a person. Address information are related to the person's residence.
| Attribute | Description |
|---|---|
| uid | The unique reference of the client driver |
| address | The main address line indicating the street name and house number. |
| city | City, district, suburb, town, or village. |
| country | Two-letter country code (ISO 3166-1 alpha-2) |
| country_id | Internally used ID of the country |
| date_of_birth | Client's date of birth |
| Client email address | |
| file_id | URL of the attached copy of the driver's ID. |
| file_id_2 | URL of the attached copy of the rear side driver's ID. |
| file_license | URL of the attached copy of the driver's license. |
| file_license_2 | URL of the attached copy of the rear side driver's license. |
| file_residence_cert | Attached copy of the signed driver's residence declaration |
| first_name | Drivers's given name and any additional middle names if present. |
| id_expiry_date | The expiry date of the driver's ID |
| id_number | The number of the driver's ID |
| id_issuer | The institution that issued the driver's ID |
| id_issuer_locality | The place or nation that issued the driver's ID |
| id_issue_date | The date on which the driver's ID was issued |
| id_type | The type of ID. This can be one of the following values: id Regular ID id_diplomatic Diplomatic ID id_electronic Electronic ID card license Driver's license passport Regular passport passport_diplomatic Diplomatic passport passport_service Service passport |
| license_expiry_date | The expiry date of the driver's license |
| license_number | The number of the driver's license |
| license_issuer | The institution that issued the driver's license |
| license_issuer_locality | The place where the license was issued |
| license_issue_date | The date on which the license was issued |
| name | Drivers's surname |
| nationality | Two-letter country code (ISO 3166-1 alpha-2) of the driver's nationality |
| phone | Phone number |
| place_of_birth | The city where the person was born |
| province | The two-letter code of the province or state where the city is located (the compilation of this field depends on the indicated country) |
| tax_number | The client's tax number |
| zip_code | ZIP or postal code |
{
"uid": "19",
"address": "Via Roma 1",
"city": "Palermo",
"country_id": "111",
"date_of_birth": "1992-06-04 22:00:00",
"email": "francesco.rossi.134634@gmail.com",
"file_id": "https://...",
"file_id_2": null,
"file_license": "https://...",
"file_license_2": null,
"file_residence_cert": "https://...",
"first_name": "Francesco",
"id_expiry_date": "2025-01-15 23:00:00",
"id_number": "AB12345",
"id_issuer": "Comune di Palermo",
"id_issuer_locality": "Palermo",
"id_issue_date": "2020-01-16 23:00:00",
"id_type": "id",
"license_expiry_date": "2025-01-01 23:00:00",
"license_number": "PA123455",
"license_issuer": "Motorizzazione",
"license_issuer_locality": "Palermo",
"license_issue_date": "2015-01-22 03:00:00",
"name": "Rossi",
"nationality": "IT",
"phone": "+393481112233",
"place_of_birth": "Palermo",
"province": "PA",
"tax_number": "TTTTTT20G20G123G",
"zip_code": "90100",
}Client reservation
A client reservation represents an actual booking providing information about the booked vehicle, pickup and return dates and booking totals. All available properties are described in detail in the section below.
GET /api/v1/client_reservation/:id
GET /api/v1/client_reservation/:filterReservation object
The client reservation object stores basic information about a certain reservation. A reservation has different states throughout the booking and rental process. It may start as a single quote which blocks a certain price for a vehicle type to rent. At this point no actual vehicle will be blocked or assigned to the reservation. Once confirmed, the quote turns into an actual reservation with a specific vehicle assigned to it. Finally, when the client arrives to pick up the vehicle, the reservation is turned into a contract.
Depending on the reservation's state, some attributes may be populated or not. The fields ref_id_quote, ref_id_reservation and ref_id_contract can be used to identify the actual state. If only the ref_id_quote attribute is populated we're talking about a quote. If the ref_id_reservation attribute is populated but not the ref_id_contract field it's a reservation. If we have a ref_id_contract field, the reservation has been converted into a contract. In terms of readability of this documentation, in any case we'll refer to client_reservation records simply as "reservation" independent from it's actual state.
| Attribute | Description |
|---|---|
| uid | The unique reference of the reservation |
| acriss_code | The short code of the vehicle type that has been assigned to the reservation |
| acriss_code_id | The unique reference of the vehicle type assigned to the reservation |
| acriss_code_name | The name of the vehicle type assigned to the reservation |
| agent | The name of the agent that created the reservation. |
| agent_id | The unique reference of the agent that created the reservation |
| broker | The name of the broker that created the reservation |
| broker_id | The unique reference of the broker that created the reservation |
| cancel_date | The time at which the reservation was canceled. If the reservation was not canceled this attriute is null |
| checkin_base | The name of the return base |
| checkin_base_id | The unique reference of the return base |
| checkin_time | The time at which the vehicle has to be returned to the return base |
| checkout_base | The name of the base where the vehicle has to be picked up |
| checkout_base_id | The unique reference of the base where the vehicle has to be picked up |
| checkout_time | The time at which the vehicle has to be picked up |
| client | The name of the client |
| client_id | The unique reference of the client |
| client_reservation_id | If this reservation is the extension of another reservation this field is populated with the unique reference of the correlated reservation, otherwise it's null |
| created_time | The time at which the reservation was created |
| expiry_time | The time at which a specific quote will expire. After a quote expired it can't be confirmed anymore. |
| notes | Internal notes for the reservation. |
| notes_printed | Notes related to the reservation that might appear on printed documents destinated for the client. |
| ref_id_contract | The contract number following the global numbering system for the given rental company. This attribute is only populated when the reservation is being converted into a contract. |
| ref_id_quote | The quote number following the global numbering system for the given rental company. This attribute may not be populated in case a reservation was created directly, skipping the process of creating a quote first. |
| ref_id_reservation | The reservation number following the global numbering system for the given rental company. |
| status | The reservation's status. Possible values are: bookedThe reservation is confirmed but it's not yet time to pick up the vehicle. canceled The reservation has been canceled. closed The reservation has been closed, i.e. the client has returned the vehicle to it's base or the reservation passed to one of the reservation's extensions. initiated An agent or a broker has intitiated the booking process indicating basic rental details but has not yet confirmed it. ongoing The reservation is under way in this moment, i.e. the client has picked up the vehicle but has not yet returned it. overdue The reservation is still under way although the time at which the client was supposed to return the vehicle has already passed. |
| stn_id_contract | The contract number following the checkout base's numbering system for the given rental company. This attribute is only populated when the reservation is being converted into a contract and only if station numbering is enabled for the rental company's account. |
| stn__id_quote | The quote number following the checkout base's numbering system for the given rental company. This attribute may not be populated in case a reservation was created directly, skipping the process of creating a quote first or if station numbering is disabled for the rental company's account. |
| stn__id_reservation | The reservation number following the checkout base's numbering system for the given rental company. This attribute may not be popuplated if station numbering is disabled for the rental company's account. |
| vat_incl | This field is set to true if price relevant information for this reservation are to be considered VAT inclusive. If not present or if set to false prices have to be considered VAT exclusive. |
| totals | The reservation totals including all additionally booked extras, fees, ecc. |
{
"uid": "543759",
"acriss_code": "MBK2",
"acriss_code_id": "31",
"acriss_code_name": "Moto Scooter 125cc o superiore",
"agent": null,
"agent_id": null,
"broker": "car-rental-software/sample",
"broker_id": "1",
"cancel_date": "2024-05-28 16:32:54",
"checkin_base": "PMO APT",
"checkin_base_id": "92248782",
"checkin_time": "2024-02-29 03:30:00",
"checkout_base": "PMO APT",
"checkout_base_id": "92248782",
"checkout_time": "2024-02-28 06:00:00",
"client": "My Appy Tester",
"client_id": "400278",
"client_reservation_id": null,
"created_time": "2024-02-27 05:07:14",
"expiry_time": null,
"notes": "Campo personalizzato: test",
"notes_printed": "Campo personalizzato: test",
"ref_id_contract": null,
"ref_id_quote": "2024/00008",
"ref_id_reservation": "2024/00010",
"status": "booked",
"stn_id_contract": null,
"stn_id_operation": null,
"stn_id_quote": "2024/00007 PMO-APT",
"stn_id_reservation": "2024/00009 PMO-APT",
"vat_incl": "0",
"totals": "50.00",
}Retrieve reservation
Retrieves a client reservation object. This endpoint can be called using the client reservation's unique reference :id or a :filter value identifying the reservation.
auth: Bearer token
expandable: client, client_driver
When requesting a client reservation object, you can also request the client reservation's client and registered client drivers using the expand parameter. Since a reservation is linked to exactly one client but may have more than one driver registered, the client data comes as a single object while the drivers are returned as a list of client_driver objects.
If you don't know the system's unique client reservation's reference :id you can try to retrieve the record using the :filter format. :filter is the base64 encoded string of a JSON object containing the following attributes:
{
"voucher_no": "...", // Voucher number indicated when the reservation was created
"surname": "..." // Reservation client's surname spelled exactly as it was communicated to the platform when the reservation was created
}The platform will return a client reservation object if the call is successful. In case no matching client reservation with the given :id or :filter can be found a R1002/5 or R1002/7 error will be returned by the platform.
Depending on the caller's permissions, client reservation details, e.g. the client name, might be returned in an obfuscated way.
GET /api/v1/client_reservation/:filter
{
"success": true,
"result":
{
"client_reservation":
{
"uid": "543759",
// ...
}
}
}{
"success": true,
"result":
{
"client":
{
"uid": "...",
// ...
},
"client_driver":
[
{
"uid": "...",
"name": "Driver 1",
// ...
},
{
"uid": "...",
"name": "Driver 2",
// ...
}
],
"client_reservation":
{
"uid": "543759",
// ...
}
}
}Client reservation update
Client reservation updates can be used to request the integration of additional information regarding a client reservation or related objects, respectively. Once submitted an update, the car rental company is notified and may decide whether to consider the update or discard it.
POST /api/v1/client_reservation/:id/client_reservation_update
POST /api/v1/client_reservation_update/:id/file_urlReservation update object
Due to the variety of information that client reservation update may contain, data is stored in a JSON-formatted external file. Therefore, the client reservation object contains only a limited set of attributes which allow the identification of the object itself and the related client reservation.
| Attribute | Description |
|---|---|
| uid | The unique reference of the reservation update |
| created_time | The time at which the object was created |
| client_reservation | A human-readable description of the related client reservation |
| client_reservation_id | The unique reference of the related client reservation |
| file_url | The url of the file containing the actual information |
| status | The status of the client reservation update. This might be one of the following values: acquired The information from the update have been acquired by the platform incomplete The information from the update have not yet been (completely) transmitted to the platform pending The information from the update were transmitted to the platform but haven't been approved for acquisition yet |
{
"uid": "251",
"created_time": "2024-10-12 04:53:11",
"client_reservation": "Prenotazione 2024/00047 PMO-APT"
"client_reservation_id": "706324",
"file_url": "https://..."
"status": "pending",
}Create reservation update
Creates a new client reservation update for the client reservation identified by its unique reference :id.
auth: Bearer token
expandable: none
In order to create a client reservation update, send a POST request to the /api/v1/client_reservation/:id/client_reservation_update endpoint where :id is the unique reference of the client reservation for which you want to submit an update for. No other parameters are requested. It is thus sufficient to send the POST request with an empty request body. If you don't know the id of the reservation but only have voucher number and the client's surname, read through Retrieve reservation to find out how to retrieve the reservation record first. Once the object has been created, the endpoint returns a client reservation update object.
In a second step use the id from the newly created reservation update to submit the actual data from the update to the platform. As described earlier, the data is supposed to be transmitted as a valid JSON file that can be uploaded using the /api/v1/client_reservation_update/:id/file_url endpoint.
As of now, it is possible to update the personal information of the client reservation's main driver and to attach copies of his or her ID and license. Optionally, information about a secondary driver may be submitted as well.
The JSON file that has to be uploaded to the server should have the same format as shown in the given code example. Since it should be possible to submit a reservation update containing information for a secondary driver only, the client_driver object represents an indexed list (with defined indexes "0" and "1") instead of a simple array. Consequently, the client_driver.0 object represents the reservation's main driver and client_driver.1 the secondary driver, respectively. The actual properties of each of these objects can be a subset of the client driver object, depending on which information should be updated for a specific driver (or both of them). Properties that refer to attached files, e.g. file_id or file_license are not expected to be URLs in this case, but valid data strings containing the actual data of the files to attach.
Related guide: Retrieve reservation, Uploading files, Client driver object
{
"success": true,
"result":
{
"client_reservation_update":
{
"uid": "256",
// ...
}
}
}{
"client_driver":
{
"0":
{
"address": "Via Roma 1",
"city": "Palermo",
"file_id": "data:image/png;base64,iVBORw0..."
"province": "PA",
"zip_code": "90100",
// ...
},
"1":
{
"first_name": "Roberto"
"name": "Romano",
// ...
}
}
}Introduction
If you are an authorised broker and need technical assistance for your implementation please connect to My Appy Help Center on https://helpcenter.myappy.it. Support via email is not given at this point. If you do not have an account on Help Center, yet, or if you have got an account for a specific client on Car Rental Software but would like to open a new communication channel for another client, compile the form below to have your personal Help Center account configured accordingly.
Request access to My Appy Help Center
Please compile the form below to have your personal access to My Appy Help Center configured accordingly. Do not forget to provide your email address as it will be used to create your account. Afterwards, an invitation will be sent to this email address containing your personal credentials that you'll have to use to access Help Center.
In the broker id field insert the unique identifier that the car rental company has provided to you to be used for the communication with the web service.
Please note that only complete submissions including a correct Broker ID will be considered. All other requests will be discarded without notice.
If you experience problems requesting your Help Center account you can get in touch with us via support@myappy.net. Please remember however that email support is only given for the setup of your account. No technical questions or doubts regarding the APIs will receive response via email.
Broker name - The name of your company, e.g.
Car rental company name - The name of the car rental company that you want to connect to
Contact name - The name of the person that is requesting access to Help Center
Contact surname - Them surname of the person that is requesting access to Help Center
Email address - The contact's email address
Broker ID - The unique broker ID/username that the car rental company provided to you