jonas/alpinebits_python
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 4 Wiki Activity

Added docs extracted from the pdf

Browse Source
This commit is contained in:
Jonas Linter
2025-11-27 17:20:43 +00:00
parent 9830ca7cf9
commit 23effcebea
2 changed files with 164 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

131
docs/alpinebits_docs/chapter4/4.1_free_rooms.md Normal file
View File

@@ -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
<?xml version="1.0" encoding="UTF-8"?>
<OTA_HotelInvCountNotifRQ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.opentravel.org/OTA/2003/05"
Version="4"
xsi:schemaLocation="http://www.opentravel.org/OTA/2003/05 OTA_HotelInvCountNotifRQ.xsd">
<UniqueID Type="16" ID="1" Instance="CompleteSet"/>
<Inventories HotelCode="123" HotelName="Frangart Inn">
<!-- ... Inventory elements ... -->
</Inventories>
</OTA_HotelInvCountNotifRQ>
```
- `Inventories` contains one or more `Inventory` elements, each for a distinct period/room or period/category. Example inner portion:
```xml
<Inventory>
<StatusApplicationControl Start="2022-08-01" End="2022-08-10" InvTypeCode="DOUBLE" />
<InvCounts>
<InvCount CountType="2" Count="3" />
</InvCounts>
</Inventory>
<Inventory>
<StatusApplicationControl Start="2022-08-11" End="2022-08-20" InvTypeCode="DOUBLE" />
</Inventory>
<Inventory>
<StatusApplicationControl Start="2022-08-21" End="2022-08-30" InvTypeCode="DOUBLE" />
<InvCounts>
<InvCount CountType="2" Count="1" />
</InvCounts>
</Inventory>
```
- 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 |

33
docs/alpinebits_docs/chapter4/4_data_exchange_actions.md Normal file
View File

@@ -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.