Channel API — connecting an OTA

Beyond pushing ARI, the integration can connect an OTA channel (e.g. Booking.com) programmatically via the Channex Channel API, so the PMS can offer its own "connect a channel" flow instead of the Channex dashboard. ChannexChannelService / ChannexChannelController expose it; reads return Channex's JSON verbatim (the per-OTA shapes vary and aren't fully documented, so callers inspect the real payload).

All endpoints take channelId — our channel that holds the Channex API key.

Flow

1. Test the OTA credentials          POST …/channels/test-connection?ota=BookingCom&hotelId=5868189
2. Read the OTA's rooms/rates        POST …/channels/mapping-details?ota=BookingCom&hotelId=5868189
   (optional) expected currency      POST …/channels/connection-details?ota=BookingCom&hotelId=5868189
3. Pick the group                    GET  …/groups
4. Create the channel (inactive)     POST …/channels                (body: mappings)
5. Activate                          POST …/channels/{id}/activate
   (optional) push ARI now           POST …/channels/{id}/load-and-save-ari

Endpoints

Method	Path	Purpose
GET	/api/v1/admin/channex/channels/available	OTAs available to connect
GET	/api/v1/admin/channex/channels	connected channels
GET	/api/v1/admin/channex/channels/{id}	one channel
GET	/api/v1/admin/channex/groups	groups the key can access
POST	/api/v1/admin/channex/channels/test-connection	validate OTA credentials
POST	/api/v1/admin/channex/channels/mapping-details	the OTA's rooms/rates
POST	/api/v1/admin/channex/channels/connection-details	OTA connection info (currency)
POST	/api/v1/admin/channex/channels	create (connect) — returns { "id": "…" }
POST	/api/v1/admin/channex/channels/{id}/activate · /deactivate	go live / pause
POST	/api/v1/admin/channex/channels/{id}/load-and-save-ari	push current ARI to the channel
DELETE	/api/v1/admin/channex/channels/{id}	delete (must be inactive first)

Creating a channel

The OTA's mapping_details returns rooms and rates keyed by integer codes. Map each OTA room+rate to one of our rate plans:

POST /api/v1/admin/channex/channels?channelId=chnl_X
{
  "channel": {
    "channel": "BookingCom",
    "is_active": false,
    "title": "Booking.com — My Hotel",
    "properties": ["<our Channex property UUID>"],
    "settings": { "hotel_id": "5868189" },
    "rate_plans": [
      { "rate_plan_id": "<our rate plan UUID>",
        "settings": { "room_type_code": 586818903, "rate_plan_code": 16385048,
                      "occupancy": 2, "pricing_type": "OBP", "primary_occ": true } }
    ]
  }
}

Guardrails enforced before the call to Channex:

• group_id is required; it defaults to the channel's configured channexGroupId when omitted.
• Room/rate codes are integers — sending strings makes Channex file the mapping under "removed rates".
• No duplicate OTA room+rate+occupancy mappings. Occupancy is part of the key, because an occupancy-based (OBP) rate legitimately maps the same room+rate multiple times — once per occupancy (e.g. occupancy 2 as primary, occupancy 1 as secondary).
• Channels are created inactive; call activate to go live, and deactivate before delete.

Notes

Channel API access may be gated on the account (historically Whitelabel) — the first test-connection call confirms it. For Airbnb, which uses an OAuth connection step instead of hotel_id, see Airbnb.