diff --git a/docs/alpinebits_docs/chapter4/4.1_free_rooms.md b/docs/alpinebits_docs/chapter4/4.1_free_rooms.md new file mode 100644 index 0000000..40b1ab8 --- /dev/null +++ b/docs/alpinebits_docs/chapter4/4.1_free_rooms.md @@ -0,0 +1,131 @@ +# 4.1 FreeRooms: Room Availability Notifications + +When `action=OTA_HotelInvCountNotif:FreeRooms`, the client sends room availability updates to the server. Servers must support at least one capability: `OTA_HotelInvCountNotif_accept_rooms` (distinct rooms) or `OTA_HotelInvCountNotif_accept_categories` (room categories); they may support both. + +## 4.1.1 Client Request (`OTA_HotelInvCountNotifRQ`) + +- The payload is a single `OTA_HotelInvCountNotifRQ` with exactly one `Inventories` element, so only one hotel is covered per request. `HotelCode` is mandatory; `HotelName` is optional. +- Example (outer structure): + +```xml + + + + + + + +``` + +- `Inventories` contains one or more `Inventory` elements, each for a distinct period/room or period/category. Example inner portion: + +```xml + + + + + + + + + + + + + + + +``` + +- Missing `InvCode` means the availability refers to a room category (`InvTypeCode`). Using both `InvTypeCode` and `InvCode` targets a specific room. Matching is case-sensitive. Mixing rooms and categories in one request is not allowed. +- `InvCounts` may contain up to three `InvCount` entries (all absolute, not deltas): + - `CountType=2`: bookable rooms (must be supported). + - `CountType=6`: out of order rooms (requires `OTA_HotelInvCountNotif_accept_out_of_order`). + - `CountType=9`: available but not bookable rooms (requires `OTA_HotelInvCountNotif_accept_out_of_market`). +- Omitted `InvCount` entries imply `Count=0`. If `InvCounts` is omitted, the room/room category is considered fully booked for the period. `Count` is non-negative; for specific rooms it should be `1`. Sum of counts cannot exceed the total rooms; overbooking is not allowed. +- Date ranges are inclusive of the start and end nights (checkout is the morning after `End`). Inventory periods must not overlap for the same room or room category; servers may reject overlaps. + +### CompleteSet + +- Purpose: replace all server-held availability for the hotel with the provided data (e.g., first sync or resync after issues). +- Server capability required: `OTA_HotelInvCountNotif_accept_complete_set`. +- Indicate a complete set with `UniqueID Instance="CompleteSet" Type="16"` (the `ID` value is ignored). `Type="35"` is also accepted and can be used to hint that data was purged by business rules. +- A CompleteSet must list every managed room/room category for all periods the client has on record. Even fully booked periods must be present (with `InvCounts` showing zero or omitted entirely). +- To fully reset availability, a CompleteSet may contain a single empty `Inventory` element with no attributes (needed for OTA validation). +- Do not include periods for which the client has no data source. + +### Deltas + +- If `UniqueID` is missing, the message is a delta: the server updates only what is present and leaves all other stored data untouched. +- Server capability required: `OTA_HotelInvCountNotif_accept_deltas`. +- If a delta explicitly covers an entire period, it overwrites the prior state for that period. +- AlpineBits recommends periodic full CompleteSet syncs when both sides support them. A server should expose at least one of the delta or complete-set capabilities; without CompleteSet support, obsolete data might require manual cleanup. + +### Closing Seasons + +- Indicates periods when the hotel is closed (distinct from fully booked). Requires both parties to expose `OTA_HotelInvCountNotif_accept_closing_seasons`. +- Can only appear as the first `Inventory` elements in a CompleteSet. +- Structure: one `StatusApplicationControl` with mandatory `Start`, `End`, and `AllInvCode="true"`; no `InvCounts` allowed. Multiple closing periods are allowed if they do not overlap with each other or with availability periods. +- Delta messages supersede earlier closed periods; best practice is to avoid such overlaps or follow deltas with a CompleteSet to restate closures explicitly. + +## 4.1.2 Server Response (`OTA_HotelInvCountNotifRS`) + +- Responses return one of the four AlpineBits outcomes (success, advisory, warning, error). The payload is `OTA_HotelInvCountNotifRS`. See section 2.3 for outcome semantics. + +## 4.1.3 Implementation Tips and Best Practice + +- Support for FreeRooms was mandatory in version 2011-11 but is optional now. +- Delta updates were added in 2013-04. +- The action was completely rewritten in 2020-10. +- Forwarders (e.g., channel managers) must not add data beyond what the source provided; do not extend time frames beyond the most future date received. +- For CompleteSet requests, servers are encouraged to delete and reinsert all backend availability rather than perform partial updates. +- The `End` date is the last night of stay; departure is the morning after `End`. +- Length-of-stay and day-of-arrival restrictions were removed from FreeRooms in 2014-04 (they belong in RatePlans). + +## 4.1.4 Tabular Representation of `OTA_HotelInvCountNotifRQ` + +| Level | Element/Attribute | Type | Cardinality | +| --- | --- | --- | --- | +| OTA_HotelInvCountNotifRQ | element | | 1 | +| OTA_HotelInvCountNotifRQ | Version | | 1 | +| OTA_HotelInvCountNotifRQ | UniqueID | element | 0-1 | +| UniqueID | Type | enum (16 \| 35) | 1 | +| UniqueID | ID | | 1 | +| UniqueID | Instance | enum (CompleteSet) | 1 | +| OTA_HotelInvCountNotifRQ | Inventories | element | 1 | +| Inventories | HotelCode | string(1-16) | 1 | +| Inventories | HotelName | string(1-128) | 0-1 | +| Inventories | Inventory | element | 1..∞ | +| Inventory | StatusApplicationControl | element | 0-1 | +| StatusApplicationControl | Start | date (\\S+) | 1 | +| StatusApplicationControl | End | date (\\S+) | 1 | +| StatusApplicationControl | InvTypeCode | string(1-8) | 0-1 | +| StatusApplicationControl | InvCode | string(1-16) | 0-1 | +| StatusApplicationControl | AllInvCode | boolean (\\S+) | 0-1 | +| Inventory | InvCounts | element | 0-1 | +| InvCounts | InvCount | element | 1-3 | +| InvCount | CountType | enum (2 \| 6 \| 9) | 1 | +| InvCount | Count | integer ([0-9]+) | 1 | + +## 4.1.5 Tabular Representation of `OTA_HotelInvCountNotifRS` + +| Level | Element/Attribute | Type | Cardinality | +| --- | --- | --- | --- | +| OTA_HotelInvCountNotifRS | element | | 1 | +| OTA_HotelInvCountNotifRS | Version | | 1 | +| OTA_HotelInvCountNotifRS | TimeStamp | | 0-1 | +| OTA_HotelInvCountNotifRS | Success | element (choice start) | 1 | +| OTA_HotelInvCountNotifRS | Warnings | element (choice start) | 0-1 | +| Warnings | Warning | element | 1..∞ | +| Warning | Type | integer ([0-9]+) | 1 | +| Warning | RecordID | string(1-64) | 0-1 | +| Warning | Status | enum (ALPINEBITS_SEND_HANDSHAKE \| ALPINEBITS_SEND_FREEROOMS \| ALPINEBITS_SEND_RATEPLANS \| ALPINEBITS_SEND_INVENTORY) | 0-1 | +| OTA_HotelInvCountNotifRS | Errors | element (choice end) | 1 | +| Errors | Error | element | 1..∞ | +| Error | Type | enum (11 \| 13) | 1 | +| Error | Code | integer ([0-9]+) | 0-1 | +| Error | Status | enum (ALPINEBITS_SEND_HANDSHAKE \| ALPINEBITS_SEND_FREEROOMS \| ALPINEBITS_SEND_RATEPLANS \| ALPINEBITS_SEND_INVENTORY) | 0-1 | + diff --git a/docs/alpinebits_docs/chapter4/4_data_exchange_actions.md b/docs/alpinebits_docs/chapter4/4_data_exchange_actions.md new file mode 100644 index 0000000..3361de7 --- /dev/null +++ b/docs/alpinebits_docs/chapter4/4_data_exchange_actions.md @@ -0,0 +1,33 @@ +# Chapter 4 - Data Exchange Actions + +These actions define how clients and servers exchange hotel data. For every data exchange request both `action` and `request` parameters are mandatory, and the XML payloads must validate against OTA2015A plus the stricter AlpineBits schema. + +## Action Summary + +| Known as (since) | Usage | Action parameter | Request XML | Response XML | +| --- | --- | --- | --- | --- | +| FreeRooms (2011-11) | Client sends room availability notifications | `OTA_HotelInvCountNotif:FreeRooms` | `OTA_HotelInvCountNotifRQ` | `OTA_HotelInvCountNotifRS` | +| GuestRequests (2012-05) | Client asks server for quote/booking requests | `OTA_Read:GuestRequests` | `OTA_ReadRQ` | `OTA_ResRetrieveRS` | +| GuestRequests Push (2018-10) | Client pushes quote/booking requests to server | `OTA_HotelResNotif:GuestRequests` | `OTA_HotelResNotifRQ` | `OTA_HotelResNotifRS` | +| GuestRequests Status Update Push (2022-10) | Client sends status updates for quote/booking requests | `OTA_HotelResNotif:GuestRequests_StatusUpdate` | `OTA_HotelResNotifRQ` | `OTA_HotelResNotifRS` | +| GuestRequests Acknowledgments (2014-04) | Client acknowledges requests it received | `OTA_NotifReport:GuestRequests` | `OTA_NotifReportRQ` | `OTA_NotifReportRS` | +| Inventory/Basic Push (2015-07) | Client sends room category info and room lists | `OTA_HotelDescriptiveContentNotif:Inventory` | `OTA_HotelDescriptiveContentNotifRQ` | `OTA_HotelDescriptiveContentNotifRS` | +| Inventory/Basic Pull (2017-10) | Client requests room category info and room lists | `OTA_HotelDescriptiveInfo:Inventory` | `OTA_HotelDescriptiveInfoRQ` | `OTA_HotelDescriptiveInfoRS` | +| Inventory/HotelInfo Push (2015-07) | Client sends additional property descriptive content | `OTA_HotelDescriptiveContentNotif:Info` | `OTA_HotelDescriptiveContentNotifRQ` | `OTA_HotelDescriptiveContentNotifRS` | +| Inventory/HotelInfo Pull (2017-10) | Client requests additional property descriptive content | `OTA_HotelDescriptiveInfo:Info` | `OTA_HotelDescriptiveInfoRQ` | `OTA_HotelDescriptiveInfoRS` | +| RatePlans (2014-04) | Client sends rate plans with prices and booking rules | `OTA_HotelRatePlanNotif:RatePlans` | `OTA_HotelRatePlanNotifRQ` | `OTA_HotelRatePlanNotifRS` | +| BaseRates (2017-10) | Client requests rate plan information | `OTA_HotelRatePlan:BaseRates` | `OTA_HotelRatePlanRQ` | `OTA_HotelRatePlanRS` | +| Activities (2020-10) | Client requests hotel activity information | `OTA_HotelPostEventNotif:EventReports` | `OTA_HotelPostEventNotifRQ` | `OTA_HotelPostEventNotifRS` | + +## Encoding and Schema Requirements + +- All XML documents must be UTF-8 encoded. Expect arbitrary Unicode (including emojis or non-Latin characters); validate and sanitize before storage to avoid visualization or data corruption issues. +- Requests and responses must validate against OTA2015A. The AlpineBits schema provided in the documentation kit is stricter: every document that passes AlpineBits validation also passes OTA2015A, not vice versa. +- Sample XML files and the stricter XSD are included in the AlpineBits documentation kit for each protocol version. +- Currency codes follow ISO 4217 (EUR shown in samples but any ISO code is allowed). If a server receives an unsupported currency it must reply with a warning outcome; a client should discard responses using unsupported currencies. + +## Copyright and Licensing of Multimedia Content + +- Many messages carry URLs to multimedia objects. Since XML has no place for license data, AlpineBits recommends embedding licensing metadata (e.g., IPTC/EXIF for images) in the files themselves and preserving it in derived works. +- Alternatively (or additionally), include HTTP headers `X-AlpineBits-License` and `X-AlpineBits-CopyrightHolder` when serving multimedia content. Receivers should honor and propagate these headers to derived assets. +