alpinebits_python/docs/alpinebits_docs/chapter4/4.1_free_rooms.md

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 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:

<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