Endpoints.
All XML messages within the Smarthotel specifications require a REST Request POST method to an endpoint. Also a HTTP header is required. Name and value can be found below. (Please note that these credentials are only valid for the testing environment.) For testing purposes we advise to use for example the RESTClient plug in for Firefox or something alike.
The endpoints for our testing environment are:
Availability Rates, Inventory, and the PMS OTA_ReadRQ:
https://acceptance.smarthotel.nl/API/API.aspx
Header:
WhiteLabelID: 1020 (only applicapble for OTA & OBE connetions)
For testing purposes, this WhiteLabelID is 1020, in production, this number is variable per hotel.
Availability Rates, Inventory, and the PMS OTA_ReadRQ for SmartCONNECT
https://acceptance.smarthotel.nl/Connect/API/API
no header is required.
OTA Reservations:
These endpoints are for the OTA & OBE connections only.
New reservations: https://acceptance.smarthotel.nl/Reservations/OTA_HotelResNotifRQ.aspx
Modifications: https://acceptance.smarthotel.nl/Reservations/OTA_HotelResModifyNotifRQ.aspx
Cancellations: https://acceptance.smarthotel.nl/Reservations/OTA_CancelRQ.aspx
WhitelabelID header is required.
Extranet Access:
https://acceptance.smarthotel.nl/Connect/UI/login
Please note that above mentioned endpoints are not valid for our production environment and can be used for testing purposes only. You will receive the endpoints for our production environment after a succesfull certification.
Failed messages:
When any XML message pushed to the Smarthotel production or testing endpoints fails, make sure you log the errors, get notified for this, and have retry mechanisms in place.
Header.
Each request and response message contain header attributes.
Please use for each message the Content-Type http header, Content-Type: text/xml.
| Element / @Attribute | Parent | Info | Values | Occurrence |
|---|---|---|---|---|
| @EchoToken | Root | A reference for additional message identification, assigned by the requesting host system. | GUID, Globally unique identifier. | 1 |
| @PrimaryLangID | Root | The primary language preference for the message encoded as ISO 639-3, e.g. ‘eng’ or ‘nld’. | Please refer to the ‘Languages’ code list. | 1 |
| @Target | Root | Test or production target system indicator. | Values: Production | 0..1 |
| @TimeStamp | Root | ISO 8601 encoded timestamp indicating the creation date and time of the message. | [YYYY-MM-DDThh:mm:ssTZD] | 0..1 |
| @Version | Root | The OpenTravel message version indicated by a decimal value. Should be ‘1.0’. | 1.0 | 0..1 |
Request – POS.
In addition, each request message, with the exception of OTA_PingRQ, requires a POS element with validation information directly under the root element.
The authentication of your messages should be done by an Apikey and a message password. Both will be handed out to you by the Smarthotel team. Both attributes should be entered in the POS element of the message. During Development of the connection, your Apikey and password will give you access to the Sandbox environment only. Only after certification, an Apikey will be handed out for the production environment.
| Element / @Attribute | Parent | Info | Values | Occurrence |
|---|---|---|---|---|
| POS | Root | Point of sale object. Point of Sale (POS) identifies the party or connection channel making the request. | 1 | |
| Source | POS | This holds the details about the requestor. It may be repeated to also accommodate the delivery systems. Provides information on the source of a request. | 1 | |
| RequestorID | Source | An identifier of the entity making the request. | 1 | |
| @ID | RequestorID | A unique identifying value assigned by the creating system. | APIKEY (Guid) | 1 |
| @MessagePassword | RequestorID | This password provides an additional level of security that the recipient should use to validate the sending party's authority to use the message. | [string] | 1 |
<POS>
<Source>
<RequestorID ID="APIKEY" MessagePassword="Password"/>
</Source>
</POS>
Responses
Success, warnings, and errors.
Each response message will indicate whether the request has been handled successfully. Therefore, directly underneath the root node, either one of the following two blocks can be found.
Success
| Element / @Attribute | Parent | Info | Values | Occurrence |
|---|---|---|---|---|
| Success | Root | The presence of the empty Success element explicitly indicates that the request message was successful. Returning an empty element of this type indicates the successful processing of an OpenTravel message. This is used in conjunction with the Warning Type to report any warnings or business errors. | 0..1 (either Success or Errors is present) | |
| Warnings | Root | Used in conjunction with the Success element to define one or more business errors. Collection of warnings. | 0..1 | |
| Warning | Warnings | Used when a message has been successfully processed to report any warnings or business errors that occurred. | 1..n | |
| @Type | Warning | The Warning element MUST contain the Type attribute that uses a recommended set of values to indicate the warning type. The validating XSD can expect to accept values that it has NOT been explicitly coded for and process them by using Type ="Unknown". | Refer to ‘Error & warning types’ code list | 1 |
| @Code | Warning | If present, this refers to a table of coded values exchanged between applications to identify errors or warnings. | Refer to ‘Error & warning codes’ code list | 1 |
<Success /> <Warnings> <Warning Type="1" Code="1"> The message was redundant. </Warning> </Warnings>
Error
| Element / @Attribute | Parent | Info | Values | Occurrence |
|---|---|---|---|---|
| Errors | Root | Errors are returned if the request was unable to be processed. A collection of errors that occurred during the processing of a message. | 0..1 | |
| (either Success or Errors is present) | ||||
| Error | Errors | An error that occurred during the processing of a message. Standard way to indicate that an error occurred during the processing of an OpenTravel message. If the message successfully processes, but there are business errors, those errors should be passed in the warning element. | 1..n | |
| @Type | Error | The Error element MUST contain the Type attribute that uses a recommended set of values to indicate the error type. | Refer to ‘Error & warning types’ code list | 1 |
| @Code | Error | If present, this refers to a table of coded values exchanged between applications to identify errors or warnings. | Refer to ‘Error & warning codes’ code list | 0..1 |
<Errors> <Error Type="1" Code="1"> Something went wrong! </Error> </Errors>
Occurrence.
The occurrence column in the specifications determines which information is mandatory or optional. The possible values and their description can be found in the table below.
| Occurrence Indicator | Description | Mandatory / Optional |
|---|---|---|
| 1 | One element | Mandatory |
| 1..n | One or multiple elements | Mandatory |
| 0..1 | Zero or one element | Optional |
| 0..n | Zero or one or multiple elements | Optional |
Code lists.
On this page, you will find all code lists as mentioned in the specifications.
Languages
The following languages are supported by the API:
| ID | Language |
|---|---|
| 1 | Dutch |
| 2 | English UK |
| 3 | German |
| 4 | French |
| 5 | Spanish |
| 6 | English US |
Error & Warning types (EWT)
The following errors and warnings will be sent by the API:
| Value | Description | Used for |
|---|---|---|
| 1 | Unknown | |
| 2 | No implementation | Not implemented messages |
| 3 | Biz rule | Incorrect values (e.g. MaxLOS > 30, Comments.length > 255) or inactive items (hotel offline) |
| 4 | Authentication | Incorrect API key and password |
| 7 | Protocol violation | Sending two or more XML elements where only one is allowed |
| 10 | Required field missing | Element or attribute not provided |
| 11 | Advisory | Warnings (e.g. redundant messages, non-existing room/rate combination) |
| 12 | Processing exception | Parsing errors, non-existing IDs (e.g. hotel/room/rate/reservation), empty strings where non-empty strings required |
| 13 | Application error | Time out of other services (e.g. data service) or databases |
Error & Warning Codes (ERR)
The following errors and warnings will be sent by the API:
| Value | Description |
|---|---|
| 15 | Invalid date |
| 19 | Name is missing or incomplete |
| 26 | At least one adult must be included |
| 28 | No more accommodation available |
| 34 | Requested accommodation is occupied |
| 61 | Invalid currency code |
| 69 | Minimum stay criteria not fulfilled |
| 70 | Maximum stay criteria not fulfilled |
| 87 | Booking reference invalid |
| 98 | Accommodation not found in booking |
| 99 | Booking not owned by requester |
| 104 | Accommodation - no availability |
| 106 | Too many rooms/units |
| 107 | Cannot book - too far in advance |
| 110 | Accommodation closed at this time |
| 111 | Booking invalid |
| 112 | Too many nights |
| 113 | Mandatory booking details missing |
| 115 | Board basis/meal plan invalid |
| 116 | Category of room/unit invalid |
| 118 | Booking Status invalid |
| 119 | Too many people in room/unit |
| 122 | End date has passed |
| 123 | Too many children |
| 124 | Too many babies |
| 125 | Room/unit not offered |
| 127 | Reservation already exists |
| 131 | Room/unit type invalid |
| 132 | Room/unit type - no availability |
| 135 | End date is invalid |
| 136 | Start date is invalid |
| 137 | Adult numbers/occupancy mismatch |
| 138 | Child numbers/occupancy mismatch |
| 141 | Room/unit code incorrect |
| 142 | Occupancy rules not fulfilled |
| 143 | Proice incorrect for room/unit |
| 145 | Duration period or dates incorrect |
| 146 | Service requested incorrect |
| 147 | Taxes incorrect |
| 155 | Accommodation details not complete |
| 160 | Minimum one room/unit or service |
| 161 | Search criteria invalid |
| 163 | Payment type invalid |
| 168 | Agent not recognised |
| 169 | Agent code invalid |
| 171 | Booking not made by this agent |
| 172 | Requested action not possible |
| 173 | Agency code required |
| 175 | Password invalid |
| 181 | Invalid country code |
| 182 | Password required |
| 184 | Language code invalid |
| 240 | Credit card has expired |
| 241 | Expiration date is invalid |
| 242 | Credit card number is invalid or missing |
| 249 | Invalid rate code |
| 285 | Invalid first name |
| 286 | First name contains invalid characters |
| 287 | Invalid last name |
| 288 | Last name contains invalid characters |
| 290 | Invalid state/province/territory code |
| 291 | Invalid zip/postal code |
| 292 | Country in address is invalid |
| 298 | City in address is required |
| 310 | Required data missing: last name |
| 311 | Required data missing: first name |
| 313 | Required data missing: credit card type |
| 315 | Required data missing: confirmation number |
| 316 | Required data missing: phone number |
| 319 | Required data missing: address |
| 320 | Invalid value |
| 321 | Required field missing |
| 322 | No availability |
| 346 | Closed to arrivals |
| 351 | Credit card guarantee not accepted at hotel |
| 352 | Invalid credit card type |
| 353 | Departure date is past dated |
| 361 | Invalid hotel |
| 362 | Invalid number of nights |
| 363 | Invalid number of rooms |
| 365 | Error credit card |
| 366 | Error during processing, please retry |
| 367 | Invalid format |
| 375 | Hotel not active |
| 377 | Invalid - max number of nights exceeded |
| 378 | Invalid - max number of rooms exceeded |
| 385 | Invalid confirmation or cancellation number |
| 386 | Invalid fax number |
| 389 | Invalid guarantee type |
| 392 | Invalid hotel code |
| 395 | Invalid message text |
| 396 | Invalid name |
| 397 | Invalid number of adults |
| 398 | invalid number specified |
| 402 | Invalid room type |
| 404 | invalid start/end date combination |
| 407 | Item too long |
| 409 | Maximum length of stay restriction |
| 410 | Minimum length of stay error |
| 411 | Minimum length of stay restriction |
| 414 | More days were specified than exist in inventory |
| 418 | Name/address missing |
| 420 | Need e-mail address |
| 424 | No hotels found which match this input |
| 425 | No match found |
| 427 | No rooms available for requested dates |
| 435 | Property name required |
| 436 | Rate does not exist |
| 439 | Reenter (message is redundant) |
| 448 | System error |
| 450 | Unable to process |
| 506 | Credit card not accepted at property |
| 523 | Surname too long |
| 524 | Given name/title too long |
| 527 | Invalid number of inventory adjustments |
| 563 | Closed to departure |
| 575 | Closed restriction |
| 635 | Data not found |
| 727 | Maximum length of stay error |
| 730 | Invalid room type for requested hotel |
| 732 | Invalid room type for rate requested |
| 743 | Invalid message length |
| 744 | Invalid field length |
| 745 | Invalid field ID |
| 767 | Invalid room stay index |
| 773 | Invalid length of parameter for search by address |
| 775 | Nothing found for requested criteria |
| 776 | Invalid length of parameter for search by availability status |
| 777 | Invalid format for search on availability status |
| 779 | No available rooms found use search on all availability status |
| 783 | Room or rate not found |
| 784 | Time out |
| 848 | Invalid type of access requested |
Room Amenity Type (RMA)
The following Room Amenity Types are supported by the API:
List will follow asap
HotelStatusCode (HST)
The following Hotel Status Codes are supported by the API:
| Value | Description | Explanation |
|---|---|---|
| 1 | Open | Shown as live in the extranet |
| 5 | Test | Shown as Ready to check in the extranet |
| 3 | Pre Opening | Shown as Setup in the extranet |
| 6 | Inactive | Shown as Offline in the extranet |
Hotel Amenity Code (HAC)
The following Hotel Amenity Code are supported by the API:
List will follow asap
Meal Plan Type (MPT)
The following Meal PLan Types are supported by the API:
| ID | Language |
|---|---|
| 1 | All inclusive |
| 2 | American |
| 3 | Breakfast |
| 4 | Buffet breakfast |
| 5 | Caribbean breakfast |
| 6 | Continental breakfast |
| 7 | English breakfast |
| 8 | European plan |
| 9 | Family plan |
| 10 | Full Board |
| 11 | Full breakfast |
| 12 | Half Board |
| 13 | As brochured |
| 14 | Room only |
| 15 | Self catering |
| 16 | Bermuda |
| 17 | Dinner bed and breakfast plan |
| 18 | Family American |
| 19 | Breakfast |
| 20 | ¾ Board |
| 21 | Lunch |
| 22 | Dinner |
| 23 | Breakfast & lunch |
Age Qualifying Code (AQC)
The following Age Qualifying Codes are supported by the API:
| Code | Description |
|---|---|
| 7 | Infant |
| 8 | Child |
| 10 | Adult |
Phone Technology Type (PTT)
The following Phone technology Types are supported by the API:
| Value | Description |
|---|---|
| 1 | Voice |
| 2 | Fax |
Unique ID Type (UIT)
The following Unique ID Types are supported by the API:
| Value | Description |
|---|---|
| 14 | Reservation |
| 15 | Cancellation |
| 18 | Other |
| 21 | Profile |
Policy Codes
The following Policy Codes are supported by the API:
| Code | description |
|---|---|
| 0 | None |
| 1 | Non-Cancellable |
| 2 | Time Pre-arrival day |
| 3 | Time Arrival Day |
| 4 | Days before arrival day |
| 5 | UVH |
Service Charge Types
The following Service Charge Types are supported by the API:
| Type | Description |
|---|---|
| 0 | None |
| 1 | Per Stay |
| 2 | Per Night |
| 3 | Per Adult per stay |
| 4 | Per adult per night |
| 5 | Selected dates |
| 6 | Selected dates per adult |
| 9 | Per piece |
| 10 | Per piece per night |
| 11 | Per piece per adult |
| 12 | Per piece per adult per night |
| 15 | Per child per stay |
| 16 | Per child per night |
Profile Types (PRT)
The following Profile Types are supported by the API:
| Value | Description |
|---|---|
| 1 | Customer |
| 3 | Corporation |
| 4 | Travel Agent |
| 18 | Billing Contact |
Creator ID
In the OTA_ResRetrieveRS the attribute CreatorID gives an ID for the originator of the reservation. Please find below the list of Creator IDs and the OTA they represent:
| ID | Code | Description |
|---|---|---|
| 2 | BOO | Booking.com |
| 6 | HCO | Hoteliers.com |
| 11 | HSP | Hotelspecials.nl |
| 14 | SPH | SpecialHotels.nl |
| 15 | EXP | Expedia/Hotels.com |
| 16 | AME | VVV Ameland |
| 17 | TOR | VVV Texel |
| 21 | TER | VVV Terschelling |
| 23 | ZWG | Zoweg.nl |
| 24 | HRS | HRS.de |
| 25 | BED | Hotelbeds.com |
| 27 | LMI | Lastminute.com |
| 28 | BNG | Bongo |
| 30 | MXM | MaxMind |
| 33 | BON | Hotelbon |
| 36 | WMS | Worldmeetings |
| 40 | UNI | Unister |
| 41 | HTW | Hotwire |
| 44 | STC | STC |
| 45 | REC | Reconline |
| 46 | OST | Ostrovok |
| 49 | GTA | GTA Travel |
| 50 | GAR | Getaroom |
| 51 | HOT | Hotusa |
| 53 | VAS | VashOtel |
| 54 | ONE | 101Hotels.ru |
| 56 | BCM | Bookit.com |
| 57 | BNL | Bookit.nl |
| 58 | JAC | JacTravel |
| 59 | TRR | Travel Republic |
| 61 | TBH | Tablet Hotels |
| 63 | NTB | Netbooking |
| 64 | FER | Feratel |
| 65 | PRE | Prestigia |
| 67 | MMS | Mr and Mrs Smith |
| 68 | HDR | HotelDirect |
| 69 | INH | Inhores |
| 71 | PBB | Pacific BedBank |
| 72 | NBB | NZ BedBank |
| 73 | ABB | Australia BedBank |
| 74 | OKT | OktoGo |
| 79 | TOM | Tomas Travel |
| 84 | HAM | Tomas Hamburg Travel |
| 85 | VBE | Tomas Visit Berlin |
| 89 | MHS | MyHotelShop.de |
| 95 | HSW | Hostelworld |
| 97 | VTR | Viato Travel |
| 100 | AGA | Agoda |
| 101 | OXI | Opera XChange Interface |
| 102 | KTL | Keytel |
| 103 | RTL | Restel |
| 104 | HRE | HotelREZ |
| 107 | HIH | Hostelling International |
| 108 | HCM | Revato by HotelsCombined |
| 109 | DER | Derbysoft |
| 110 | WKD | Weekendesk |
| 111 | BAS | Bookassist |
| 112 | CTR | Ctrip |
| 113 | MET | Metglobal |
| 114 | CUB | Cubilis |
| 115 | KM2 | Kurz Mal Weg |
| 116 | SBO | SimpleBooking |
| 118 | WBD | WebBeds |
| 119 | KUR | Kurzurlaub |
| 120 | SMO | VVV Schiermonnikoog |
| 121 | REX | Roomex |
| 122 | VOY | Voyage Prive |
| 124 | WAT | VVV Waterland van Friesland |
| 125 | ODI | Odigeo |
| 126 | WB2 | WebBeds (new) |
| 20003 | NTF | Net Affinity |
| 20008 | NST | Nustay |
| 20009 | RVD | Reservado |
| 20011 | SSC | Short Stay Citizens |
| 20013 | OSW | Onsweb |
| 20014 | FST | Fastbooking |
| 20016 | FRB | Freebooking |
| 20018 | TRB | Travelbird |
| 20019 | RYA | Ryanair |
| 20020 | JZT | JazzTour |
| 20021 | TL2 | TravelLine |
| 20023 | OPL | OffPeakLuxury |
| 20026 | ODA | Odamax |
| 20029 | PWN | Powernapp |
| 20035 | HBO | Hotel Bonanza |
| 20036 | BAK | Bakuun |
| 20038 | OZO | Ozon Travel |
| 20040 | GVB | Goedverblijf |
| 20048 | SMA | Smartbox |
| 20049 | DBR | DayBreakHotels |
| 20050 | SHR | SHR/Windsurfer |
| 20052 | HCN | Hotelbank |
| 20054 | OTE | Otelz.com |
| 20055 | BAR | Barboon |
| 20056 | DIB | DIB Hotel |
| 20057 | TRA | Travelanium |
| 20059 | SEM | Sembo |
| 20063 | BID | Bidroom |
| 20067 | AOV | Aovo Reisen |
| 20070 | HH2 | H-Hotels.com |
| 20071 | SNA | SnapiLABS |
| 20072 | CA2 | Caesar Data |
| 20073 | DOR | Dorms.com |
| 20074 | EXR | Hotel Spider |
| 20075 | OGD | OpenGDS |
| 20076 | VO2 | Voordeeluitjes |
| 20078 | VGR | BookVisit |
| 20080 | AER | AeroGuest |
| 20081 | LOG | Logitravel |
| 20085 | CB2 | Citybreak |
| 20086 | CH2 | Charmant Hotel |
| 20087 | C24 | Check24 |
| 20089 | SKH | SK Hotel Management |
| 20091 | TPR | TouristPro |
| 20092 | NWE | Nuweg Exclusief |
| 20096 | HNS | HotelNetSolutions |
| 20097 | DIG | Digibreaks |
| 20098 | DVP | DVP |
| 20099 | OLY | Olympia Europe |
| 20101 | CMA | CMAC Group |
| 20104 | W4T | Weekend4Two |
| 20106 | AMD | Amadeus |
| 20108 | NA2 | Net Affinity (new) |
| 20109 | MIK | Miki Travel |
| 20112 | HOP | Hopper |