1. Getting Started
This page is meant as a quick start guide for integrating with Carnect car hire platform using SOAP (https://api.carhire-solutions.com/service.asmx). All mentioned terms, abbreviations, etc. in this document are based on the Open Travel Alliance 2007A Specifications. Please find all information regarding the OTA specifications under https://opentravel.org.
Make sure you have your credentials available and your IP range has been whitelisted for access. As well, pay special attention to HTTP compression. If you don’t configure your http/SOAP client to use http 1.1 and make sure that it is sending the header Accept-Encoding: gzip you will end up receiving a „403 Forbidden“ error!
1.1. System Information
The main function of the car platform is to provide all necessary and/or required information within a short limited time period.
1.1.1. Search Geographic
1.1.1.1. Search by Geo-point
A search by geo-point can be carried out by using the latitude and longitude of a given geo-point.
Search will return offers of multiple suppliers located within the system defined radius around the given geo-point.
1.1.1.2. Search by Airport
A search by airport can be carried out by using the airport IATA-Code or airport ID.
Search will return offers of multiple suppliers located at the airport.
1.1.1.3. Search by City
A search by city can be carried out by using the a city ID or by using a geo-point.
Search will return offers of multiple suppliers located within the city (downtown). If a supplier is only located at the airport, offers are also be returned for city search if the location is in the given radius.
1.1.1.4. Search by Location
A search by location can be carried out by using
Location ID (assigned only to one supplier)
Location code and GDS code (queries only one supplier)
Location is always unique to a single supplier and therefore a search will not return offers from multiple suppliers.
Note
To request for a specific location of a supplier it is always recommended to request with GDS Code + location code!
1.1.2. System Access
Client partners implementing access of the OTA2007A interface need to test their implementation first before setting their software productive. For testing please use this URL
Staging web-service URL: https://ota2007a.cnx-uat.com/service.asmx
Unless qualification, all tests need to be performed using the staging URL given above. This applies to all message types:
Availrate
Raterule
Reservation
Retrieve
Cancellation
For testing pleaser refer to the instructions provided in test reservations. After testing every single message type please share samples of the inbound and outbound XML with the Carnect integrations team (contact details will be provided at the beginning of the integration phase).
After the samples have been reviewed and certified, the client partner shall provide the Carnect Integrations Team access to their test system – this allows Carnect to perform the front-end certification and ensure the correct display of the car rental product on the client partner’s website.
After the whole certification process has been finalized the Carnect Integrations team will activate the client partner for the live environment and will share the production URL with him.
1.1.3. OTA-SOAP Message-Format
Each request for the OTA interface contains two parts, the SOAP-Header and the SOAP-Body. Both the OTA Request and the OTA Response messages are transmitted inside the SOAP body.
SOAP-Webservice |
|
WDSL Location |
|
targetNamespace |
|
SOAP Action URL |
e.g. |
An example of a valid request is given below
Request SOAP Header:
SOAPAction:http://www.opentravel.org/OTA/2003/05/getVehAvailRate
Content-Type:text/xml
Request SOAP Body:
Note
RequestorID must be filled in correct. Values are provided by Carnect
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<VehAvailRateRQ xmlns="http://www.opentravel.org/OTA/2003/05">
<POS>
<Source ISOCountry="DE">
<RequestorID Type="XXX" ID_Context="XXX" />
</Source>
</POS>
<VehAvailRQCore RateQueryType="Live">
<RateQueryParameterType>2</RateQueryParameterType>
<VehRentalCore PickUpDateTime="2017-09-20T12:00:00.000+02:00" ReturnDateTime="2017-09-25T12:00:00.000+02:00">
<PickUpLocation LocationCode="47" CodeContext="1" />
<ReturnLocation LocationCode="47" CodeContext="1" />
</VehRentalCore>
</VehAvailRQCore>
</VehAvailRateRQ>
</soap:Body>
</soap:Envelope>
1.1.4. OTA-SOAPAction header
Our logging relies on the SOAPAction header, which is required by SOAP 1.1, but not by SOAP 1.2.
Please make sure you are adding this header, if you are using SOAP 1.2, depending on the call you are performing.
VehAvailRateRQ |
|
SOAPAction: |
|
VehRateRule |
|
SOAPAction: |
|
VehReservation |
|
SOAPAction: |
|
VehRetReservation |
|
SOAPAction: |
|
VehCancelReservation |
|
SOAPAction: |
http://www.opentravel.org/OTA/2003/05/getVehCancelReservation |
VehLocationSearchRQ |
|
SOAPAction: |
|
VehLocDetail |
|
SOAPAction: |
|
curl example:
curl --location --request POST 'https://api.carhire-solutions.com/service.asmx' \
--header 'Content-Type: text/xml;charset=UTF-8' \
--header 'SOAPAction: "http://www.opentravel.org/OTA/2003/05/getVehAvailRate"' \
--data-raw 'HERE GOES YOUR SOAP'
Note
Sending no SOAPAction header will result in a 400 Bad Request in Staging Environment
Sending no valid Accept-Encoding header will result in a 400 Bad Request in Staging Environment
Sending invalid SOAP Action Text will result in a 400 Bad Request in Staging Environment
Incorrect use of Content_type header will result in a 400 Bad Request in Staging Environment
1.1.5. XML Sample Output Tool
There are websites with sample implementations of the OTA-Interface. These websites provide capabilities to create valid sample XML requests and to analyze input and output XML messages. Intention of these sites is to help developers in testing and verifying their own request and response messages. There are two testing websites which differ in the type of their setup.
You may also refer to (insert document Rate rules)
1.1.5.1. SOAP Client
The SOAP client is a web tool for testing SOAP compliancy and can be found at https://www.soapui.org/, https://www.getpostman.com/ and http://www.soapclient.com/.
1.1.6. Message Timeouts
We recommend using two different timeout values, one for reservation, one for all other calls. Non-reservation calls are expected to complete within 6s, thus the suggested timeout value for SOAP client is 7s, to allow for the transmission overhead.
For reservation requests we recommend a timeout of 130s as this call will require waiting for a transaction confirmation from the supplier and may also require a credit card transaction.
Some customers might require lower timeouts than these. Should your implementation require use of lower timeout values, please contact us to discuss.
1.1.7. HTTP Compression
Make sure that the HTTP/SOAP client you are using
is configured to use
HTTP 1.1(not1.0)is sending the header
Accept-Encoding: gzip(only sendingdeflateis insufficient)
in order to enable efficient compression. All new implementations must implement this. Learn more about HTTP compression on Wikipedia.
Note
Sending another Accept-Encoding header or using HTTP 1.0 will result in a 403 Forbidden error.
1.1.8. HTTPS
All communication with the API must use HTTPS (not plain HTTP) and TLS 1.2 or higher.
1.1.9. Data Dumps
CarHire Solutions related data can be downloaded to your own system. Please note that using the API to obtain this information instead is strongly encouraged.
Data that used to be provided as CSV files but is now deprecated
Airports: please use the destination API for airports instead to obtain this information
Cities: please use the destination API for cities instead to obtain this information
Countries: please use the destination API for countries instead to obtain this information
Locations: static export of all locations is not supported, please use raterule request to retrieve details about rental offer location or _location details request in other cases
1.2. SOAP clients
Your programming language of choice should allow you to generate SOAP proxies/clients. The two WSDL files for initial integration process are https://ota2007a.cnx-uat.com/service.asmx?WSDL and https://ota2007a.cnx-uat.com/destination.asmx?WSDL . Those services are meant for testing and currently do not place actual reservations with car rental suppliers (however, you should make sure to cancel all your test reservations).
1.3. Test reservations
For test bookings you can use testcheck@carnect.com as email address and chose a pick-up date 14 days in advance. This way your reservations will be automatically cancelled. If you don’t use this email address please use „Test“ in your surname and make sure you cancel them afterwards. Staging (UAT) urls will not accept reservations made less than 14 days in advance of the target reservation date. Reservations that are not cancelled will be cancelled automatically - however, this is a fallback mechanism, you should take care to cancel all test reservations yourself.
Note
Please make sure you are using a valid mailbox in case you don’t use testcheck@carnect.com as email address. All emails to an invalid mailbox will bounce back. A high bounce rate has a negative impact on the delivery of our emails.
1.4. Available destinations
You can search for offers using the IATA codes for cities and airports. However, many smaller cities do not have an IATA code but are still served by our suppliers. To search in those destinations, you need to first load the list of available destinations. Those do not change often and should be cached in your database (however, please do refresh them on a schedule - daily if possible). GEO Destinations details.
<soap:Envelope xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<VehicleCityRequest>
<Language>DE</Language>
<CountryISO>DE</CountryISO>
</VehicleCityRequest>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.opentravel.org/OTA/2003/05">
<soap:Body>
<VehicleCityResponse>
<Cities>
<City id="59" iata="AAH" latitude="50.7781295776367" longitude="6.08849000930786">
<Name>Aachen</Name>
<RegionID>1</RegionID>
</City>
<City id="60" latitude="48.837760925293" longitude="10.0920295715332">
<Name>Aalen</Name>
<RegionID>1</RegionID>
</City>
<City id="8474" latitude="52.0726890563965" longitude="7.00794982910156">
<Name>Ahaus</Name>
<RegionID>1</RegionID>
</City>
<City id="61" latitude="53.6694488525391" longitude="10.2319297790527">
<Name>Ahrensburg</Name>
<RegionID>1</RegionID>
</City>
<City id="38600" state-code="NY" latitude="41.4706446" longitude="-74.1122506">
<Name>New Windsor-NY</Name>
<RegionID>24</RegionID>
</City>
<City id="41" state-code="NY" iata="NYC" latitude="40.7127753" longitude="-74.0059728">
<Name>New York</Name>
<RegionID>24</RegionID>
</City>
</Cities>
</VehicleCityResponse>
</soap:Body>
</soap:Envelope>
1.5. Searching for offers
For the end user, the search is the first step when booking a car. A simple search form might look like in these examples
These search forms might translate to an XML search request like
<soap:Envelope xmlns="http://www.opentravel.org/OTA/2003/05" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<VehAvailRateRQ EchoToken="1.0" ReqRespVersion="large" Version="1.0">
<POS>
<Source ISOCountry="US">
<RequestorID ID_Context="password" Type="username"/>
</Source>
</POS>
<VehAvailRQCore RateQueryType="Live">
<RateQueryParameterType>2</RateQueryParameterType>
<VehRentalCore PickUpDateTime="2024-06-12T09:00:00.000" ReturnDateTime="2024-06-16T09:00:00.000">
<PickUpLocation CodeContext="1" LocationCode="51"/>
<ReturnLocation CodeContext="1" LocationCode="51"/>
</VehRentalCore>
</VehAvailRQCore>
</VehAvailRateRQ>
</soap:Body>
</soap:Envelope>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<informationHeader xmlns="http://www.opentravel.org/OTA/2003/05">
<Successfully>true</Successfully>
<ProcessingTime>1.6014142</ProcessingTime>
</informationHeader>
</soap:Header>
<soap:Body>
<VehAvailRateRS xmlns="http://www.opentravel.org/OTA/2003/05"
EchoToken="1.5892924;1.6014142" TimeStamp="2017-09-29T17:03:52" Version="3">
<VehAvailRSCore>
<VehRentalCore PickUpDateTime="2018-06-12T09:00:00"
ReturnDateTime="2018-06-16T09:00:00" Quantity="5">
<PickUpLocation LocationCode="51" />
<ReturnLocation LocationCode="51" />
</VehRentalCore>
<VehVendorAvails>
<VehVendorAvail>
<VehAvails>
<VehAvail>
<VehAvailCore Status="Available">
<Vehicle AirConditionInd="true" TransmissionType="Manual" FuelType="Petrol"
DriveType="Unspecified" PassengerQuantity="4" BaggageQuantity="2"
VendorCarType="R" Code="Opel Mokka/Nissan Juke" CodeContext="">
<VehType VehicleCategory="3" />
<VehClass Size="3" />
<VehMakeModel Name="Opel Mokka/Nissan Juke" Code="EFMR" />
<PictureURL>
https://static.carhire-solutions.com/images/car/Goldcar/small/CXMR-R.jpg</PictureURL>
</Vehicle>
<RentalRate>
<RateDistance Unlimited="true" DistUnitName="Km" />
<VehicleCharges>
<VehicleCharge CurrencyCode="EUR" Amount="195.43" TaxInclusive="true"
Purpose="original" RateConvertInd="true">
<Calculation UnitName="Day" Quantity="4" />
</VehicleCharge>
<VehicleCharge CurrencyCode="EUR" Amount="195.43" TaxInclusive="true"
Purpose="preferred" RateConvertInd="true" />
<VehicleCharge CurrencyCode="EUR" Amount="171.43" TaxInclusive="true"
Purpose="baserate" RateConvertInd="true" />
<VehicleCharge CurrencyCode="EUR" Amount="1400.00" TaxInclusive="true"
Description="Upon collection of the car usually a security deposit will be blocked on the drivers credit card. This deposit typically corresponds to the stated amount of the possible excess plus the value of one tank of fuel. This deposit can only be blocked on a valid credit card (prepaid debit cards,prepaid credit cards and cash cannot be accepted).<br /><br /> For luxury cars two credit cards in the same name are required for all rentals. The credit card must not be from the same issuer. Please note some suppliers will not accept American Express, Visa Premier or Diners Club credit cards, we strongly recommend to use a Visa or Mastercard. <br /><br /> In the event that you fail to produce a valid credit card or have insufficient funds available the car rental agent may refuse to release the vehicle. In this instance no funds will be reimbursed. Estimated deposit amount: EUR 1400.00"
IncludedInEstTotalInd="false" Purpose="Estimated deposit amount"
RateConvertInd="true" />
</VehicleCharges>
<RateQualifier VendorRateID="MICRONNEXUS">
<RateComments>
<RateComment Name="SilverPackage" />
</RateComments>
</RateQualifier>
<RateRestrictions>
<MinimumAge>21</MinimumAge>
<MaximumAge>80</MaximumAge>
<NoShowFeeInd>false</NoShowFeeInd>
</RateRestrictions>
</RentalRate>
<TotalCharge CurrencyCode="EUR" EstimatedTotalAmount="195.43"
RateConvertInd="false" />
<Fees>
<Fee CurrencyCode="EUR" Amount="0.00" TaxInclusive="true"
Description="Location service charge(LSC)" IncludedInRate="true"
IncludedInEstTotalInd="true" />
<Fee CurrencyCode="EUR" Amount="0.00" TaxInclusive="true"
Description="VAT(TAX)" IncludedInRate="true"
IncludedInEstTotalInd="true" />
</Fees>
<Reference URL="https://www.carhiremarket.com/upsell_parameter.aspx?reference_number=54114770862533183651462627A034&live=true"
Type="16" ID_Context="5Pr_0" />
<Vendor TravelSector="Car Rental" Code="GR" CodeContext="34">Goldcar
rental</Vendor>
<VendorLocation LocationCode="PMIC191" CodeContext="PPM"
ExtendedLocationCode="51-GRPPM" CounterLocation="3"
Name="Majorca - Promenade">Majorca - Promenade</VendorLocation>
<DropOffLocation LocationCode="PMIC191" CodeContext="PPM"
ExtendedLocationCode="51-GRPPM" Name="Majorca - Promenade" />
</VehAvailCore>
<VehAvailInfo>
<PricedCoverages>
<PricedCoverage>
<Coverage CoverageType="Location service charge" Code="LSC">
<Details>
<Charge Amount="0.00" IncludedInRate="true" />
</Details>
</Coverage>
<Charge CurrencyCode="EUR" Amount="0.00" TaxInclusive="true"
Description="An additional service charge applies at some airports, railway stations and ports- In this offer it is included."
GuaranteedInd="true" IncludedInRate="true"
IncludedInEstTotalInd="true" />
</PricedCoverage>
<PricedCoverage>
<Coverage CoverageType="Collision damage waiver" Code="CDW">
<Details>
<Charge Amount="0.00" IncludedInRate="true" />
</Details>
</Coverage>
<Charge CurrencyCode="EUR" Amount="0.00" TaxInclusive="true"
Description="Maximum excess of 1,400 EUR to be paid in the case of damage. Please note that comprehensive insurance does not cover damage to wheels, tires, mirrors and underbody"
GuaranteedInd="true" IncludedInRate="true"
IncludedInEstTotalInd="true" />
</PricedCoverage>
<PricedCoverage>
<Coverage CoverageType="Supplementary Liability Insurance" Code="SLI">
<Details>
<Charge Amount="0.00" IncludedInRate="true" />
</Details>
</Coverage>
<Charge CurrencyCode="EUR" Amount="0.00" TaxInclusive="true"
Description="Legally required, insurance for damages on the adversarial vehicle, persons and objects- In this offer it is included."
GuaranteedInd="true" IncludedInRate="true"
IncludedInEstTotalInd="true" />
</PricedCoverage>
<!-- some fees omitted from the sample -->
</PricedCoverages>
<PaymentRules>
<PaymentRule PaymentType="4">Prepayment. For the local pick up of your car
a valid credit card is mandatory. The card holder and driver must be the
same person. Prepaid or debit cards, such as for instance Maestro, Visa
electron or Visa Premier are not accepted for pick-up.</PaymentRule>
</PaymentRules>
<TPA_Extensions>
<TermsConditions xmlns=""
url="https://createpdf.carhire-solutions.com/termsandconditions.aspx?reference=54114770863341183651462362&languageId=2" />
<SupplierLogo xmlns=""
url="https://static.carhire-solutions.com/images/supplier/logo/logo34.png" />
</TPA_Extensions>
</VehAvailInfo>
<AdvanceBooking RulesApplyInd="true" />
</VehAvail>
</VehAvails>
</VehVendorAvail>
</VehVendorAvails>
</VehAvailRSCore>
</VehAvailRateRS>
</soap:Body>
</soap:Envelope>
This should be sufficient to show a listing of search results to the customer.
Note
Search results must not be cached.
Before they book, you should also display a page with offer details. More sample searches
Offers include details about the cars available, which should be used for displaying them to the customer. As this data changes often, the contents of the SOAP response have to take precedence over cached / stored information.
1.6. How-To guides
To help our client partners with various integration scenarios, we are providing a collection of different How-To guides at Advanced How-tos.
1.7. System status
We recommend to subscribe to our Status page. https://status.carnect.com/. Here we will inform about planned downtimes or outages.