> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/engineering-reference/api/integrations.md).

# Integrations API

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/api/integrations.md).
{% endhint %}

Property management system (PMS) integrations and the D3x guest-messaging inbox: the Laravel routes the PMS services call, the PMS services' own endpoints, the PMS onboarding actions, and the Guestline setup that the staff admin app uses.

* **Services:** `api_php_live_v2` at `https://z4.snapfix.com` (`/broadcasting`, `/v1/app`, `/v1/d3x`, `/v1/internal`); `php-apis web` at `https://z1.snapfix.com/api/snapfix/web/index.php`; `php-apis guestline` at `https://z1.snapfix.com/api/snapfix/guestline/index.php`; `apipy` at `https://z2.snapfix.com`; `cloudbeds_py_server` at `https://pms-integration.snapfix.com/cloudbeds`; `clock_py_server` at `https://pms-integration.snapfix.com/clock` \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; `comtrol_py_server` at `https://comtrol.snapfix.com` (php-apis calls it at `https://pms-integration.snapfix.com/comtrol` instead); `deputy_py_server` at `https://pms-integration.snapfix.com` (going by its sign-in redirect) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; `guestline_py_server` at `https://pms-integration.snapfix.com/guestline`; `hotsoft_py_server` at `https://pms-integration.snapfix.com/hotsoft`; `jonaschorum_py_server` at `https://pms-integration.snapfix.com/jonaschorum`; `opera_py_server` at `https://pms-integration.snapfix.com/opera`; `protel_py_server` at `https://pms-integration.snapfix.com/protel` (going by its `root_path`; no repo names its host) \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]; `stayntouch_py_server` at `https://pms-integration.snapfix.com/stayntouch`. Paths in the table are relative to these base URLs.
* **Auth:** api\_php\_live\_v2: the PMS routes take the building's own PMS login (HTTP Basic) plus `integrationSource` ([PMS logins](#pms-logins)); the D3x webhook takes the `X-D3x-Webhook-Secret` header; `/broadcasting/auth` uses the web session; the inbox rules take a user token. php-apis: the `guestline` dispatcher takes HTTP Basic with `GL_AUTH_USERNAME`; the `web` onboarding actions take a user token while `JWT_AUTH_ENABLED` is on \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)] and check no access to the site they name. apipy: user token (authpy JWT in `Authorization: Bearer`); the Guestline routes check only that the caller is signed in. PMS services: their own Basic login on the room status routes and on the Cloudbeds, Opera and Jonas Chorum router triggers; the building's `x-api-key` on `/api/v1/inbound` and `/api/v1/outbound` (Clock, Guestline, Protel and Stayntouch); a per-site Basic login on Comtrol's `/inbound` and `/outbound`, whose passwords are stored in plain text. No login on the triggers that Cloudbeds and Opera define in `app/main.py` (`/trigger/inbound-sync`, `/trigger/outbound-sync` and Opera's redirects), the other services' trigger and cache routes, and the Deputy proxy; nor on Guestline's `/encrypt` and `/decrypt`, the Cloudbeds OAuth routes and the Deputy sign-in pages. The Cloudbeds webhook and the Jonas Chorum listener accept unsigned requests, and the Stayntouch webhook accepts a bad signature.
* **Used by:** webadmin\_angular (the Guestline setup on apipy); php-apis (the apps' room status changes, to seven PMS services); api\_php\_live\_v2 (the `MapRoomStatus` job, to every PMS of the building); the PMS services (room status changes to `POST /v1/internal/rooms/{uuid}/status`); deputy\_py\_server's own sign-in page; and external partners: Clock PMS+, Comtrol, Cloudbeds, D3x, Deputy, Guestline, Jonas Chorum ARC, Protel and Stayntouch. 100 of the 131 endpoints have no known caller.
* **Answers and errors:** api\_php\_live\_v2 uses its envelope ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)); apipy and php-apis answer with `result` and `message`. The PMS services have shapes of their own, and most of their errors come back as HTTP `200` ([PMS result object](#pms-result-object)).

| Method    | Path                                                                                                                                                                        | Service                 | Purpose                                                                                                                                                                                                                                 |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET, POST | `/broadcasting/auth`                                                                                                                                                        | api\_php\_live\_v2      | Authorize a subscription to a real-time channel, such as a site's inbox (no caller)                                                                                                                                                     |
| GET       | `/v1/app/inbox/{parentUuid}/automation-rules`                                                                                                                               | api\_php\_live\_v2      | List a site's inbox automation rules (no caller)                                                                                                                                                                                        |
| POST      | `/v1/app/inbox/{parentUuid}/automation-rules`                                                                                                                               | api\_php\_live\_v2      | Create an inbox automation rule (no caller)                                                                                                                                                                                             |
| PUT       | `/v1/app/inbox/{parentUuid}/automation-rules/{ruleUuid}`                                                                                                                    | api\_php\_live\_v2      | Change an inbox automation rule (no caller)                                                                                                                                                                                             |
| DELETE    | `/v1/app/inbox/{parentUuid}/automation-rules/{ruleUuid}`                                                                                                                    | api\_php\_live\_v2      | Delete an inbox automation rule (no caller)                                                                                                                                                                                             |
| POST      | [`/v1/d3x/webhook`](#post-v1d3xwebhook)                                                                                                                                     | api\_php\_live\_v2      | Receive a D3x guest-messaging webhook for the inbox                                                                                                                                                                                     |
| POST      | `/v1/internal/rooms/status/multi`                                                                                                                                           | api\_php\_live\_v2      | Apply room status changes from a PMS, several at once (no caller)                                                                                                                                                                       |
| POST      | [`/v1/internal/rooms/{uuid}/status`](#post-v1internalroomsuuidstatus)                                                                                                       | api\_php\_live\_v2      | Apply a room status change from a PMS                                                                                                                                                                                                   |
| ANY       | `?action=cloudbeds_existingbuilding`                                                                                                                                        | php-apis web            | Cloudbeds onboarding: existing building (no caller)                                                                                                                                                                                     |
| ANY       | `?action=cloudbeds_housekeepingrules`                                                                                                                                       | php-apis web            | Cloudbeds onboarding: housekeeping rules (no caller)                                                                                                                                                                                    |
| ANY       | `?action=cloudbeds_newbuilding`                                                                                                                                             | php-apis web            | Cloudbeds onboarding: new building (no caller)                                                                                                                                                                                          |
| ANY       | `?action=cloudbeds_onboard`                                                                                                                                                 | php-apis web            | Cloudbeds onboarding: onboard (no caller)                                                                                                                                                                                               |
| ANY       | `?action=comtrol_existingbuilding`                                                                                                                                          | php-apis web            | Comtrol onboarding: existing building (no caller)                                                                                                                                                                                       |
| ANY       | `?action=comtrol_newbuilding`                                                                                                                                               | php-apis web            | Comtrol onboarding: new building (no caller)                                                                                                                                                                                            |
| ANY       | `?action=comtrol_onboard`                                                                                                                                                   | php-apis web            | Comtrol onboarding: onboard (no caller)                                                                                                                                                                                                 |
| ANY       | `?action=guestline_existingbuilding`                                                                                                                                        | php-apis web            | Guestline onboarding: existing building (no caller)                                                                                                                                                                                     |
| ANY       | `?action=guestline_housekeepingrules`                                                                                                                                       | php-apis web            | Guestline onboarding: housekeeping rules (no caller)                                                                                                                                                                                    |
| ANY       | `?action=guestline_newbuilding`                                                                                                                                             | php-apis web            | Guestline onboarding: new building (no caller)                                                                                                                                                                                          |
| ANY       | `?action=guestline_onboard`                                                                                                                                                 | php-apis web            | Guestline onboarding: onboard (no caller)                                                                                                                                                                                               |
| ANY       | `?action=hotsoft_existingbuilding`                                                                                                                                          | php-apis web            | Hotsoft onboarding: existing building (no caller)                                                                                                                                                                                       |
| ANY       | `?action=hotsoft_housekeepingrules`                                                                                                                                         | php-apis web            | Hotsoft onboarding: housekeeping rules (no caller)                                                                                                                                                                                      |
| ANY       | `?action=hotsoft_newbuilding`                                                                                                                                               | php-apis web            | Hotsoft onboarding: new building (no caller)                                                                                                                                                                                            |
| ANY       | `?action=hotsoft_onboard`                                                                                                                                                   | php-apis web            | Hotsoft onboarding: onboard (no caller)                                                                                                                                                                                                 |
| ANY       | `?action=jonaschorum_existingbuilding`                                                                                                                                      | php-apis web            | Jonas Chorum onboarding: existing building (no caller)                                                                                                                                                                                  |
| ANY       | `?action=jonaschorum_housekeepingrules`                                                                                                                                     | php-apis web            | Jonas Chorum onboarding: housekeeping rules (no caller)                                                                                                                                                                                 |
| ANY       | `?action=jonaschorum_newbuilding`                                                                                                                                           | php-apis web            | Jonas Chorum onboarding: new building (no caller)                                                                                                                                                                                       |
| ANY       | `?action=jonaschorum_onboard`                                                                                                                                               | php-apis web            | Jonas Chorum onboarding: onboard (no caller)                                                                                                                                                                                            |
| ANY       | `?action=opera_existingbuilding`                                                                                                                                            | php-apis web            | Opera onboarding: existing building (no caller)                                                                                                                                                                                         |
| ANY       | `?action=opera_housekeepingrules`                                                                                                                                           | php-apis web            | Opera onboarding: housekeeping rules (no caller)                                                                                                                                                                                        |
| ANY       | `?action=opera_newbuilding`                                                                                                                                                 | php-apis web            | Opera onboarding: new building (no caller)                                                                                                                                                                                              |
| ANY       | `?action=opera_onboard`                                                                                                                                                     | php-apis web            | Opera onboarding: onboard (no caller)                                                                                                                                                                                                   |
| ANY       | `?action=stayntouch_existingbuilding`                                                                                                                                       | php-apis web            | Stayntouch onboarding: existing building (no caller)                                                                                                                                                                                    |
| ANY       | `?action=stayntouch_housekeepingrules`                                                                                                                                      | php-apis web            | Stayntouch onboarding: housekeeping rules (no caller)                                                                                                                                                                                   |
| ANY       | `?action=stayntouch_newbuilding`                                                                                                                                            | php-apis web            | Stayntouch onboarding: new building (no caller)                                                                                                                                                                                         |
| ANY       | `?action=stayntouch_onboard`                                                                                                                                                | php-apis web            | Stayntouch onboarding: onboard; the method it calls does not exist, so every call fails (no caller)                                                                                                                                     |
| ANY       | `?action=gl_housekeeping`                                                                                                                                                   | php-apis guestline      | Save Guestline housekeeping tasks (`saveJobs`); the method does not exist, so every call fails (no caller)                                                                                                                              |
| POST      | [`/guestline-parent`](#post-guestline-parent)                                                                                                                               | apipy                   | Create a Guestline site                                                                                                                                                                                                                 |
| GET       | [`/guestline-parent/{gl_parent_uuid}/business/{gl_business_uuid}/status/{enabled_status}`](#get-guestline-parentgl_parent_uuidbusinessgl_business_uuidstatusenabled_status) | apipy                   | Set whether a group of a Guestline site is enabled                                                                                                                                                                                      |
| GET       | [`/guestline-parent/{gl_parent_uuid}/businesses`](#get-guestline-parentgl_parent_uuidbusinesses)                                                                            | apipy                   | List a Guestline site's groups                                                                                                                                                                                                          |
| GET       | `/guestline-parent/{uuid}`                                                                                                                                                  | apipy                   | Get a Guestline site (no caller)                                                                                                                                                                                                        |
| PUT       | [`/guestline-parent/{uuid}`](#put-guestline-parentuuid)                                                                                                                     | apipy                   | Change a Guestline site                                                                                                                                                                                                                 |
| GET       | [`/guestline-parent/{uuid}/status/{enabled_status}`](#get-guestline-parentuuidstatusenabled_status)                                                                         | apipy                   | Set whether a Guestline site is enabled                                                                                                                                                                                                 |
| GET       | [`/guestline-parents`](#get-guestline-parents)                                                                                                                              | apipy                   | List Guestline sites                                                                                                                                                                                                                    |
| GET       | `/oauth/authorize`                                                                                                                                                          | cloudbeds\_py\_server   | Cloudbeds OAuth: authorize (no caller)                                                                                                                                                                                                  |
| GET       | [`/oauth/callback`](#get-oauthcallback)                                                                                                                                     | cloudbeds\_py\_server   | Cloudbeds OAuth: callback; stores the building's tokens                                                                                                                                                                                 |
| GET       | `/trigger/inbound-sync`                                                                                                                                                     | cloudbeds\_py\_server   | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| GET       | `/trigger/outbound-sync`                                                                                                                                                    | cloudbeds\_py\_server   | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| GET       | `/trigger/room_mapping_sync/{buildingUUID}`                                                                                                                                 | cloudbeds\_py\_server   | Sync a building's room mappings now (no caller)                                                                                                                                                                                         |
| GET       | `/trigger/room_reservation_sync/{buildingUUID}`                                                                                                                             | cloudbeds\_py\_server   | Sync a building's reservations now (no caller)                                                                                                                                                                                          |
| GET       | `/trigger/room_status_sync/{buildingUUID}`                                                                                                                                  | cloudbeds\_py\_server   | Sync a building's room statuses now (no caller)                                                                                                                                                                                         |
| GET       | `/trigger/room_sync/{buildingUUID}`                                                                                                                                         | cloudbeds\_py\_server   | Sync a building's rooms now (no caller)                                                                                                                                                                                                 |
| GET       | `/trigger/sync_inbound_queue`                                                                                                                                               | cloudbeds\_py\_server   | Apply the inbound queue to Snapfix now (no caller)                                                                                                                                                                                      |
| GET       | `/trigger/sync_outbound_queue`                                                                                                                                              | cloudbeds\_py\_server   | Send the outbound queue to Cloudbeds now (no caller)                                                                                                                                                                                    |
| POST      | [`/webhook/receive`](#post-webhookreceive)                                                                                                                                  | cloudbeds\_py\_server   | Receive a Cloudbeds webhook; store it, and apply housekeeping and reservation events                                                                                                                                                    |
| POST      | `/webhook/subscribe/{buildingUUID}`                                                                                                                                         | cloudbeds\_py\_server   | Subscribe a building to Cloudbeds webhooks (no caller)                                                                                                                                                                                  |
| GET       | [`/{roomStatusChangeLogUUID}`](#get-roomstatuschangeloguuid-cloudbeds)                                                                                                      | cloudbeds\_py\_server   | Receive a Snapfix room status change, queue it for Cloudbeds and push the queue at once                                                                                                                                                 |
| GET       | [`/api/v1/inbound`](#get-apiv1inbound-clock)                                                                                                                                | clock\_py\_server       | Clock PMS+ polls for Snapfix changes                                                                                                                                                                                                    |
| POST      | [`/api/v1/outbound`](#post-apiv1outbound-clock)                                                                                                                             | clock\_py\_server       | Clock PMS+ posts its changes                                                                                                                                                                                                            |
| GET       | `/cache/clear`                                                                                                                                                              | clock\_py\_server       | Clear the cache (no caller)                                                                                                                                                                                                             |
| GET       | `/cache/stats`                                                                                                                                                              | clock\_py\_server       | Cache statistics; no login (no caller)                                                                                                                                                                                                  |
| PUT       | `/trigger/inbound-sync`                                                                                                                                                     | clock\_py\_server       | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| PUT       | `/trigger/outbound-sync`                                                                                                                                                    | clock\_py\_server       | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| POST      | `/trigger/room-mapping-sync`                                                                                                                                                | clock\_py\_server       | Start the room mapping sync (no caller)                                                                                                                                                                                                 |
| POST      | `/trigger/room-sync`                                                                                                                                                        | clock\_py\_server       | Start the room sync (no caller)                                                                                                                                                                                                         |
| GET       | [`/{uuid}`](#get-uuid)                                                                                                                                                      | clock\_py\_server       | Receive a Snapfix room status change and queue it for Clock PMS+                                                                                                                                                                        |
| GET       | [`/inbound`](#get-inbound)                                                                                                                                                  | comtrol\_py\_server     | Comtrol polls for Snapfix room status changes                                                                                                                                                                                           |
| POST      | [`/outbound`](#post-outbound)                                                                                                                                               | comtrol\_py\_server     | Comtrol posts room status changes                                                                                                                                                                                                       |
| GET       | [`/{roomStatusChangeLogUUID}`](#get-roomstatuschangeloguuid-comtrol)                                                                                                        | comtrol\_py\_server     | Receive a Snapfix room status change and queue it for Comtrol; php-apis sends its changes to `pms-integration.snapfix.com/comtrol/` instead                                                                                             |
| GET       | [`/staycity/auth`](#get-staycityauth)                                                                                                                                       | deputy\_py\_server      | Deputy's sign-in redirect; answers an HTML page that finishes the sign-in                                                                                                                                                               |
| GET       | [`/staycity/auth/complete`](#get-staycityauthcomplete)                                                                                                                      | deputy\_py\_server      | Finish the Deputy sign-in                                                                                                                                                                                                               |
| GET       | `/staycity/locations`                                                                                                                                                       | deputy\_py\_server      | Deputy locations, proxied (no caller)                                                                                                                                                                                                   |
| GET       | `/staycity/rosters`                                                                                                                                                         | deputy\_py\_server      | Deputy rosters, proxied (no caller)                                                                                                                                                                                                     |
| GET       | `/staycity/rosters-sync`                                                                                                                                                    | deputy\_py\_server      | Start the Deputy sign-in for a property and user (`parentUuid`, `userUuid`), and return its URL \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)] (no caller) |
| GET       | [`/api/v1/inbound`](#get-apiv1inbound-guestline)                                                                                                                            | guestline\_py\_server   | Guestline polls for Snapfix changes                                                                                                                                                                                                     |
| POST      | `/api/v1/outbound`                                                                                                                                                          | guestline\_py\_server   | Queue room changes that Guestline posts; no posted row exists \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)] (no caller)               |
| GET       | [`/api/v1/{roomStatusChangeLogUUID}`](#get-apiv1roomstatuschangeloguuid-guestline)                                                                                          | guestline\_py\_server   | Receive a Snapfix room status change and queue it for Guestline \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]                                                |
| POST      | `/decrypt`                                                                                                                                                                  | guestline\_py\_server   | Decrypt a Guestline password (no caller)                                                                                                                                                                                                |
| POST      | `/encrypt`                                                                                                                                                                  | guestline\_py\_server   | Encrypt a Guestline password (no caller)                                                                                                                                                                                                |
| POST      | `/trigger/guest-sync`                                                                                                                                                       | guestline\_py\_server   | Start the guest sync (no caller)                                                                                                                                                                                                        |
| POST      | `/trigger/guest-sync-arrivals`                                                                                                                                              | guestline\_py\_server   | Start the guest arrivals sync (no caller)                                                                                                                                                                                               |
| POST      | `/trigger/guest-sync-departures`                                                                                                                                            | guestline\_py\_server   | Start the guest departures sync (no caller)                                                                                                                                                                                             |
| POST      | `/trigger/guest-sync-residents`                                                                                                                                             | guestline\_py\_server   | Start the guest residents sync (no caller)                                                                                                                                                                                              |
| PUT       | `/trigger/inbound-sync`                                                                                                                                                     | guestline\_py\_server   | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| PUT       | `/trigger/outbound-sync`                                                                                                                                                    | guestline\_py\_server   | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| POST      | `/trigger/room-sync`                                                                                                                                                        | guestline\_py\_server   | Start the room sync (no caller)                                                                                                                                                                                                         |
| POST      | `/trigger/room-sync-master`                                                                                                                                                 | guestline\_py\_server   | Start the room master sync (no caller)                                                                                                                                                                                                  |
| GET       | [`/api/v1/{roomStatusChangeLogUUID}`](#get-apiv1roomstatuschangeloguuid-hotsoft)                                                                                            | hotsoft\_py\_server     | Receive a Snapfix room status change and queue it for Hotsoft \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]                                                  |
| GET       | `/cache/clear`                                                                                                                                                              | hotsoft\_py\_server     | Clear the cache (no caller)                                                                                                                                                                                                             |
| GET       | `/cache/stats`                                                                                                                                                              | hotsoft\_py\_server     | Cache statistics; no login (no caller)                                                                                                                                                                                                  |
| PUT       | `/trigger/inbound-sync`                                                                                                                                                     | hotsoft\_py\_server     | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| PUT       | `/trigger/outbound-sync`                                                                                                                                                    | hotsoft\_py\_server     | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| POST      | `/trigger/room-mapping-sync`                                                                                                                                                | hotsoft\_py\_server     | Start the room mapping sync (no caller)                                                                                                                                                                                                 |
| POST      | `/trigger/room-sync`                                                                                                                                                        | hotsoft\_py\_server     | Start the room sync (no caller)                                                                                                                                                                                                         |
| POST      | [`/chorum/listener/submit`](#post-chorumlistenersubmit)                                                                                                                     | jonaschorum\_py\_server | Receive Jonas ARC SOAP push events                                                                                                                                                                                                      |
| GET       | `/chorum/trigger/inbound-sync`                                                                                                                                              | jonaschorum\_py\_server | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| GET       | `/chorum/trigger/outbound-sync`                                                                                                                                             | jonaschorum\_py\_server | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| GET       | `/chorum/trigger/reservation-sync`                                                                                                                                          | jonaschorum\_py\_server | Start the reservation sync (no caller)                                                                                                                                                                                                  |
| GET       | `/chorum/trigger/room_reservation_sync/{building_uuid}`                                                                                                                     | jonaschorum\_py\_server | Sync a building's reservations now (no caller)                                                                                                                                                                                          |
| GET       | `/chorum/trigger/room_status_sync/{building_uuid}`                                                                                                                          | jonaschorum\_py\_server | Sync a building's room statuses now (no caller)                                                                                                                                                                                         |
| GET       | `/chorum/trigger/room_sync/{building_uuid}`                                                                                                                                 | jonaschorum\_py\_server | Sync a building's rooms now (no caller)                                                                                                                                                                                                 |
| GET       | [`/chorum/{log_uuid}`](#get-chorumlog_uuid)                                                                                                                                 | jonaschorum\_py\_server | Receive a Snapfix room status change and push it to Jonas Chorum at once \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)]                                       |
| GET       | `/trigger/inbound-sync`                                                                                                                                                     | opera\_py\_server       | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| GET       | `/trigger/outbound-sync`                                                                                                                                                    | opera\_py\_server       | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| GET       | `/trigger/room_mapping_sync/{buildingUUID}`                                                                                                                                 | opera\_py\_server       | Sync a building's room mappings now (no caller)                                                                                                                                                                                         |
| GET       | `/trigger/room_reservation_sync/{buildingUUID}`                                                                                                                             | opera\_py\_server       | Sync a building's reservations now (no caller)                                                                                                                                                                                          |
| GET       | `/trigger/room_status_change/{room_status_change_log_uuid}`                                                                                                                 | opera\_py\_server       | Room status change trigger; answers with a redirect to a path outside `/opera` (no caller)                                                                                                                                              |
| GET       | `/trigger/room_status_sync/{buildingUUID}`                                                                                                                                  | opera\_py\_server       | Sync a building's room statuses now (no caller)                                                                                                                                                                                         |
| GET       | `/trigger/room_sync/{buildingUUID}`                                                                                                                                         | opera\_py\_server       | Sync a building's rooms now (no caller)                                                                                                                                                                                                 |
| GET       | `/trigger/sync_inbound_queue`                                                                                                                                               | opera\_py\_server       | Apply the inbound queue to Snapfix now (no caller)                                                                                                                                                                                      |
| GET       | `/trigger/sync_outbound_queue`                                                                                                                                              | opera\_py\_server       | Send the outbound queue to Opera now (no caller)                                                                                                                                                                                        |
| GET       | [`/{roomStatusChangeLogUUID}`](#get-roomstatuschangeloguuid-opera)                                                                                                          | opera\_py\_server       | Receive a Snapfix room status change, queue it for Opera and push the queue at once                                                                                                                                                     |
| GET       | [`/api/v1/inbound`](#get-apiv1inbound-protel)                                                                                                                               | protel\_py\_server      | Protel polls for Snapfix changes                                                                                                                                                                                                        |
| POST      | [`/api/v1/outbound`](#post-apiv1outbound-protel)                                                                                                                            | protel\_py\_server      | Protel posts its changes                                                                                                                                                                                                                |
| GET       | `/cache/clear`                                                                                                                                                              | protel\_py\_server      | Clear the cache (no caller)                                                                                                                                                                                                             |
| GET       | `/cache/stats`                                                                                                                                                              | protel\_py\_server      | Cache statistics; no login (no caller)                                                                                                                                                                                                  |
| PUT       | `/trigger/inbound-sync`                                                                                                                                                     | protel\_py\_server      | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| PUT       | `/trigger/outbound-sync`                                                                                                                                                    | protel\_py\_server      | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| POST      | `/trigger/room-mapping-sync`                                                                                                                                                | protel\_py\_server      | Start the room mapping sync (no caller)                                                                                                                                                                                                 |
| POST      | `/trigger/room-sync`                                                                                                                                                        | protel\_py\_server      | Start the room sync (no caller)                                                                                                                                                                                                         |
| GET       | [`/{log_uuid}`](#get-log_uuid-protel)                                                                                                                                       | protel\_py\_server      | Receive a Snapfix room status change and queue it for Protel                                                                                                                                                                            |
| GET       | [`/api/v1/inbound`](#get-apiv1inbound-stayntouch)                                                                                                                           | stayntouch\_py\_server  | Stayntouch polls for Snapfix changes                                                                                                                                                                                                    |
| POST      | `/api/v1/outbound`                                                                                                                                                          | stayntouch\_py\_server  | Queue room changes that Stayntouch posts; no posted row exists \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)] (no caller)              |
| GET       | `/cache/clear`                                                                                                                                                              | stayntouch\_py\_server  | Clear the cache (no caller)                                                                                                                                                                                                             |
| GET       | `/cache/stats`                                                                                                                                                              | stayntouch\_py\_server  | Cache statistics; no login (no caller)                                                                                                                                                                                                  |
| PUT       | `/trigger/inbound-sync`                                                                                                                                                     | stayntouch\_py\_server  | Start the inbound sync (no caller)                                                                                                                                                                                                      |
| PUT       | `/trigger/outbound-sync`                                                                                                                                                    | stayntouch\_py\_server  | Start the outbound sync (no caller)                                                                                                                                                                                                     |
| POST      | `/trigger/room-mapping-sync`                                                                                                                                                | stayntouch\_py\_server  | Start the room mapping sync (no caller)                                                                                                                                                                                                 |
| POST      | `/trigger/room-reservation-sync`                                                                                                                                            | stayntouch\_py\_server  | Start the reservation sync (no caller)                                                                                                                                                                                                  |
| POST      | `/trigger/room-sync`                                                                                                                                                        | stayntouch\_py\_server  | Start the room sync (no caller)                                                                                                                                                                                                         |
| POST      | [`/webhook`](#post-webhook)                                                                                                                                                 | stayntouch\_py\_server  | Receive a Stayntouch webhook                                                                                                                                                                                                            |
| GET       | [`/{log_uuid}`](#get-log_uuid-stayntouch)                                                                                                                                   | stayntouch\_py\_server  | Receive a Snapfix room status change, queue it for Stayntouch and push the queue at once                                                                                                                                                |

Notes on the table:

* "(no caller)": no code in any repo calls the route, and no partner system is known to call it. Partner systems (Clock PMS+, Comtrol, Cloudbeds, D3x, Deputy, Guestline, Jonas Chorum ARC, Protel, Stayntouch) count as callers of the routes built for them; their code is not in the repos. Test scripts (`test_*.py`) and READMEs that call routes by hand are not counted. Whether to remove the uncalled routes is open \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)].
* Clock, Guestline, Protel and Stayntouch each have a poll route (`GET /api/v1/inbound`) and a post route (`POST /api/v1/outbound`) for the partner, next to their own syncs, which send queued changes to the partner's API and read the partner's changes from it (for example guestline\_py\_server @ 6aa8239243, `app/core/background_tasks.py:990-1060`). Guestline's and Stayntouch's post routes have no caller: in the staging database, a copy of production, no row of `guestline_InboundQueue` or `stayntouch_InboundQueue` has the creator `external_system` that the post route writes, although both integrations have live buildings \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].
* The health and root routes of the PMS services (`/health`, `/`) are not listed. In Cloudbeds, Clock and Opera, `GET /health` never reaches its handler: the room status route, registered first, catches it.
* The 27 onboarding actions take the site (`parentUUID`) and the building (`buildingUUID`) from the request and check no access to the site. The Cloudbeds onboarding guide sends staff to a Laravel route, `POST /v1/internal/pms/onboard`, which api\_php\_live\_v2 does not define \[[ASK-11](https://github.com/snapfix/docs/blob/main/ASK.md#ask-11-which-unused-api-endpoints-are-still-needed)] (cloudbeds\_py\_server @ 17b14a0ee2, `docs/Cloudbeds PMS Customer Onboarding Guide.txt:94-96`).
* The inbox automation rules can be saved, but nothing applies them: the D3x job's task trigger is commented out \[[ASK-14](https://github.com/snapfix/docs/blob/main/ASK.md#ask-14-does-d3x-create-tasks-in-snapfix-today)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/Inbox/ProcessD3xWebhook.php:51`).
* `POST /v1/internal/rooms/status/multi` has no caller: the PMS services post one room at a time. Unlike the single-room route, it queues a push of the changes to every PMS of the building, the sending one included \[[ASK-161](https://github.com/snapfix/docs/blob/main/ASK.md#ask-161-is-post-v1internalroomsstatusmulti-still-needed-and-should-it-push-a-pmss-own-change-back)] (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:311-325`).
* php-apis sends each room status change that an app saves (`save_pri_log_roomstatuschange`) to one PMS: the first of Guestline, Hotsoft, Opera, Stayntouch, Cloudbeds, Jonas Chorum and Comtrol whose room mappings hold any room of the batch (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45329-45405`, called from `html/api/snapfix/index.php:4504-4508`). It calls `GET https://pms-integration.snapfix.com/<pms>/<log uuid>` with that service's Basic login, and `/dev-stayntouch/` instead of `/stayntouch/` unless the server mode is `LIVE` (`class.functions.php:45468-45562`). It never calls Clock or Protel.
* Laravel's `MapRoomStatus` job calls `GET <PMS URL>/<log uuid>` with the PMS's service login for every PMS the building has a mapping row for, 10 seconds after the change, and skips changes that a newer change of the same room has overtaken (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:27-79`). The web's room status routes, task completion and the multi-room route queue it (`app/Http/Controllers/v1/Versions/v1_0/App/RoomController.php:272`, `app/Traits/Room/RoomMultiActions.php:111`, `:243`, `app/Services/TaskCompletionService.php:127`). The web and task completion log their changes with an empty integration source (`RoomController.php:264-270`, `TaskCompletionService.php:119-124`). The PMS URLs and logins come from the server's settings (`config/pms.php`), which no repo holds. A PMS whose mapping table does not exist is skipped; the staging database has no `clock_*` or `protel_*` tables \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].
* The four Guestline setup actions on the php-apis mobile dispatcher (`admin_read_gl_parent`, `admin_modify_gl_parent`, `admin_guestline_login`, `admin_guestline_statuses`) and the four `/v1/admin/parents/.../guest-line` routes are in the [Staff API](https://docs.snapfix.com/engineering-reference/api/staff.md). The admin app calls the four php-apis actions, from its Guestline dialogs ([admin\_read\_gl\_parent](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_gl_parent), [admin\_modify\_gl\_parent](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_modify_gl_parent), [admin\_guestline\_login](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_guestline_login), [admin\_guestline\_statuses](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_guestline_statuses)).

## PMS logins

Each PMS has a building login for Laravel's PMS routes: two columns of the building's mapping row for that PMS, sent as the HTTP Basic username and password. Laravel checks the pair against the table of the PMS that `integrationSource` names, with plain equality (api\_php\_live\_v2 @ ef3c4319f6, `app/Services/Pms/Providers/`, `getIntegration` at `:44-50` of each). The PMS services also take a key or a login of their own on their inbound, outbound and room status routes.

| PMS          | Login on `POST /v1/internal/rooms/{uuid}/status` (username, password) | Key or login on the PMS service                                                                                                                         |
| ------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloudbeds    | building UUID, `cloudbeds_propertyId`                                 | the service's Basic login on `/{roomStatusChangeLogUUID}`                                                                                               |
| Clock        | `subscription_id`, `account_id`                                       | `x-api-key` (`webhook_apikey`) on `/api/v1/inbound` and `/api/v1/outbound`; the service's Basic login on `/{uuid}`                                      |
| Comtrol      | `basicauth_username`, `basicauth_password`                            | the same per-site login on `/inbound` and `/outbound`; one shared login on `/{roomStatusChangeLogUUID}`                                                 |
| Guestline    | `uuid` and `siteid` of `guestline_BuildingSiteMapping`                | `x-api-key` (`webhook_apikey`) on `/api/v1/inbound` and `/api/v1/outbound`; the service's Basic login on `/api/v1/{roomStatusChangeLogUUID}`            |
| Hotsoft      | `hotel_code`, `hotel_provider_key`                                    | any non-empty Basic login on `/api/v1/{roomStatusChangeLogUUID}`                                                                                        |
| Jonas Chorum | building UUID, `hotel_code`                                           | the service's Basic login on `/chorum/{log_uuid}`; a building's partner key on `/chorum/listener/submit`, which a plain payload skips                   |
| Opera        | building UUID, `client_id`                                            | the service's Basic login on `/{roomStatusChangeLogUUID}`                                                                                               |
| Protel       | `hotel_key`, `webhook_apikey`                                         | `x-api-key` (`webhook_apikey`) on `/api/v1/inbound` and `/api/v1/outbound`; the service's Basic login on `/{log_uuid}`                                  |
| Stayntouch   | `hotel_id`, `webhook_apikey`                                          | `x-api-key` (`webhook_apikey`) on `/api/v1/inbound` and `/api/v1/outbound`; the service's Basic login on `/{log_uuid}`; an HMAC signature on `/webhook` |

* Several of the login values are identifiers, not secrets, and Snapfix neither issues nor hashes them. Anyone who holds a building's pair can post its room changes.
* Each PMS service names itself in `integrationSource`, for example `"integrationSource": "comtrol"` (comtrol\_py\_server @ 70129b5d33, `app/core/background_tasks.py:90-104`).
* Jonas Chorum writes its login, the building UUID and the hotel code, to its log before every room status post, and Guestline logs the whole request headers, Basic login included, when Snapfix answers anything but `200` (jonaschorum\_py\_server @ ca557086fd, `app/core/internal_api.py:183-186`; guestline\_py\_server @ 6aa8239243, `app/core/background_tasks.py:1502-1505`).

## POST /v1/d3x/webhook

Receives one D3x guest-messaging event for a site's inbox. The route checks the shared secret and queues the event; the queued job sends the message to the site's inbox channel and to its staff's phones.

* **Auth:** a shared secret, not one of the kinds in [Authentication](https://docs.snapfix.com/engineering-reference/api.md#authentication). The caller sends it in the `X-D3x-Webhook-Secret` header, and the route compares it in constant time with the server's `D3X_WEBHOOK_SECRET`, one secret for every site (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Middleware/AuthorizeD3xWebhook.php:15-32`, `config/d3x.php:6`). No user token. A missing or wrong secret is meant to get `401`, but gets `500` (see Errors).
* **Used by:** D3x, external. The route is the inbound endpoint for D3x's webhooks; D3x's code is not in the repos. Whether D3x sends events today is open \[[ASK-157](https://github.com/snapfix/docs/blob/main/ASK.md#ask-157-is-the-d3x-inbox-live-and-should-its-webhook-accept-only-connected-sites)].

**Request** (JSON body)

| Name                   | In     | Type    | Required | Rules                                                                                                                           |
| ---------------------- | ------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `X-D3x-Webhook-Secret` | header | string  | yes      | Must equal the server's `D3X_WEBHOOK_SECRET`                                                                                    |
| `event_type`           | body   | string  | yes      | Only `message.received` does anything; other types are accepted and dropped (`app/Jobs/Inbox/ProcessD3xWebhook.php:49-55`)      |
| `event_id`             | body   | string  | yes      | The idempotency key, for 24 hours. An empty value makes the job do nothing (`ProcessD3xWebhook.php:41`, `:62-73`)               |
| `thread_id`            | body   | string  | yes      | The guest conversation                                                                                                          |
| `timestamp`            | body   | integer | yes      | The event time as D3x sends it; the code sets no unit                                                                           |
| `parent_uuid`          | body   | string  | no       | The site the event is for. Empty when missing, and not checked against the database                                             |
| `data`                 | body   | object  | no       | For `message.received` the job reads `channel` and `guest_name` and passes the whole object on (`ProcessD3xWebhook.php:79-104`) |

A body without `event_type`, `event_id`, `thread_id` or `timestamp` fails while the event is read, before anything is logged or queued (`app/Services/D3x/DTO/D3xWebhookEvent.php:16-26`).

**Response** `200`, as the handler means it. The route does not return it today (see Errors):

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": { "received": true }
}
```

**Errors:**

* `500` "An unexpected error occurred. Please try again later." after every accepted event: the handler passes an array to `ApiResponse::success()`, which takes a resource, so PHP raises a `TypeError` once the event is queued (`app/Http/Controllers/v1/Versions/v1_0/D3x/D3xWebhookController.php:34`; `app/Http/Responses/ApiResponse.php:18`; `app/Exceptions/Handler.php:78-82`).
* `500` with the same message for a missing or wrong secret, and when `D3X_WEBHOOK_SECRET` is empty: the middleware passes `null` to `ApiResponse::error()`, which takes a `Throwable`. The intended answers are `401` "Unauthorized" and `500` "Webhook not configured" (`AuthorizeD3xWebhook.php:20`, `:31`; `ApiResponse.php:39`).
* `500` with the same message when a required body field is missing.
* Every `500` writes the whole request body, the guest's message data included, to the Laravel error log (`app/Exceptions/Handler.php:96-109`).

**Side effects:**

* Writes an `inbound` line to the `d3x` log channel with the event type, the site, the event ID and the thread ID, not the guest data. A failed secret check writes an `auth` line with the reason and the caller's IP instead (`app/Services/D3x/D3xLogger.php:9-16`, `:37-46`).
* Queues `ProcessD3xWebhook`. Each `event_id` is processed once within 24 hours, through the cache key `d3x:webhook:processed:{event_id}`; a repeat delivery does nothing (`ProcessD3xWebhook.php:58-73`).
* For `message.received`, the job broadcasts `InboxMessageReceived` on the private channel `inbox.property.{parent_uuid}` with the guest's name, the channel, the time and the event data, and queues a push with the same data to the devices of the site's admins and of users with an inbox permission, titled "New Guest Message" (`ProcessD3xWebhook.php:79-104`; `app/Events/Inbox/InboxMessageReceived.php:28-31`; `app/Jobs/Inbox/SendInboxFcmNotification.php:108-141`). The push job then tries to write the push body and the device tokens to the notification log, but it passes neither `authUser` nor `tokensCount`, so the write throws and the job drops the error: no inbox push is logged today (`app/Jobs/Inbox/SendInboxFcmNotification.php:91-105`, `app/Services/LogNotificationService.php:82-87`).
* The controller and `ProcessD3xWebhook` write no database rows.

## POST /v1/internal/rooms/{uuid}/status

Applies a room status change that a PMS integration posts: it sets the room's main status and, when sent, its secondary status, then runs the room's housekeeping steps.

* **Auth:** the building's PMS login ([PMS logins](#pms-logins)): HTTP Basic with two values from the building's mapping row for the PMS that `integrationSource` names. No user token. The middleware takes the building from the matched row and overwrites any `buildingUuid` in the body, so a caller reaches only its own building's rooms (api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Middleware/AuthorizePmsApi.php:39-61`; `routes/internal.php:18-21`).
* **Used by:** the PMS services, each with the building's login and its own `integrationSource`:

  * Cloudbeds, from its periodic inbound sync and its webhook (cloudbeds\_py\_server @ 17b14a0ee2, `app/core/background_tasks.py:871-897`);
  * Comtrol, from a background task of its `POST /outbound` (comtrol\_py\_server @ 70129b5d33, `app/core/background_tasks.py:90-104`);
  * Guestline, from its periodic inbound sync (guestline\_py\_server @ 6aa8239243, `app/core/background_tasks.py:1483-1499`);
  * Jonas Chorum, from its push listener and its periodic inbound sync (jonaschorum\_py\_server @ ca557086fd, `app/core/internal_api.py:171-194`; `app/core/listening_service.py:406-416`);
  * Opera, from its periodic inbound sync (opera\_py\_server @ 61bc356c45, `app/core/background_tasks.py:1155-1170`);
  * Stayntouch, from its webhook and its daily fallback sync (stayntouch\_py\_server @ 21e55b9071, `app/core/background_tasks.py:415-426`; `app/main.py:697`).

  Clock, Hotsoft and Protel make the same call from their inbound sync (clock\_py\_server @ ab0a701fdf, `app/core/background_tasks.py:366-376`; hotsoft\_py\_server @ e30355215a, `app/core/background_tasks.py:803-818`; protel\_py\_server @ 90a79f14d1, `app/core/background_tasks.py:340-350`). In their code that sync starts only from `PUT /trigger/inbound-sync`, which nothing in the repos calls, because the periodic start is commented out (`app/main.py:56-57` in Clock and Protel, `:46-47` in Hotsoft). Yet the staging database, a copy of production, holds many changes logged with the source `hotsoft`, so something outside the repos runs Hotsoft's syncs \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)]. Clock and Protel have no tables in that copy \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

**Request** (JSON body)

| Name                  | In     | Type           | Required | Rules                                                                                                                                                                                                                                                               |
| --------------------- | ------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                | path   | string         | yes      | The room. It must be in the login's building, else `403`. Unknown, or in a deleted building: `404` (`app/Services/RoomService.php:110-122`)                                                                                                                         |
| `Authorization`       | header | Basic          | yes      | The building's login for `integrationSource`                                                                                                                                                                                                                        |
| `integrationSource`   | body   | string         | yes      | One of `clock`, `cloudbeds`, `comtrol`, `guestline`, `hotsoft`, `jonaschorum`, `opera`, `protel` or `stayntouch` (`app/Enums/Pms.php:5-15`). It names the mapping table that the login is checked against. Missing or another value: `422`                          |
| `statusUuid`          | body   | string         | yes      | A main room status (`tPri_BuildingRoomStatusMain`) in a room section of the room's building, else `403`. Unknown: `404` (`app/Services/RoomStatusService.php:35-38`; `app/Http/Controllers/v1/Versions/v1_0/Internal/InternalController.php:86-91`). Missing: `422` |
| `statusSecondaryUuid` | body   | string or null | no       | Left out: the room keeps its secondary status. `null`: the secondary status is cleared. Any other string is written as sent; the route does not check that it belongs to the building (`InternalController.php:93-95`, `:135-140`)                                  |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Operation was successful",
  "data": null
}
```

**Errors:**

* `401` when the pair matches no row of the named PMS's mapping table, also when no login is sent. The message is the lookup's own text, which names a Laravel model (`AuthorizePmsApi.php:60-61`).
* `422` with the first failed rule's text: `integrationSource` missing or not one of the nine, or `statusUuid` missing.
* `403` "Access denied": the room is not in the login's building, or the status is not in a room section of that building.
* `404` "Resource not found": the room or the status does not exist, or the room's building is deleted.
* `503` "Service temporarily unavailable", with `Retry-After: 1`, when the database stays unreachable after two retries (`AuthorizePmsApi.php:58-72`).
* `500` for other failures.

**Side effects:**

* Cancels the room's red departure cleans created today, in the site's time zone, when the room's next stay is back-to-back (`app/Services/Housekeeping/HousekeepingBackToBackReservationService.php:339-365`; `InternalController.php:102-110`). Errors are logged and ignored.
* When the room comes back from "OUT OF ORDER" or "OUT OF SERVICE" to an available status, housekeeping is on and the site has an admin user, creates an inspection task as that admin, unless the room has an open one \[[ASK-83](https://github.com/snapfix/docs/blob/main/ASK.md#ask-83-which-room-status-changes-should-create-inspections-and-cleaning-tasks-and-reach-the-pms)] (`app/Services/Housekeeping/UnavailableRoomReturnInspectionService.php:73-94`; `InternalController.php:112-133`). Errors are logged and ignored.
* Sets `uuid_tBuildingRoomStatusMain` on the room, and `uuid_tBuildingRoomStatusSecondary` when `statusSecondaryUuid` is sent ([`tPri_Room`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_room.md)).
* When housekeeping is on for the room, the site has an admin user, and the room did not just come back from an unavailable status, generates the room's daily tasks (`InternalController.php:142-158`).
* Queues a [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row with `integrationSource` as the source and `admin` as the creator (`InternalController.php:160-166`).
* Pushes the change to no PMS; only the multi-room route does. The building's manual room status setting is not read \[[ASK-84](https://github.com/snapfix/docs/blob/main/ASK.md#ask-84-what-should-the-building-setting-manual-room-status-do)].

## POST /guestline-parent

Creates a Guestline site: it links a Snapfix site to a Guestline account, with the room status and housekeeping mappings. The password is stored encrypted.

* **Auth:** user token. The route checks no staff flag and no membership of the site, so any signed-in user can link any site. The creator is the token's user (apipy @ 0e83c85e5a, `app.py:3958-3978`).
* **Used by:** webadmin\_angular, the Guestline page's "Guestline Snapfix Integration Details" dialog, opened from "Create a new Guestline Mapping", when the site has no Guestline account yet (`GuestlineService.saveGuestlineAccountStatuses`: webadmin\_angular @ db972390b8, `src/app/services/guestline/guestline.service.ts:65-97`; `src/app/pages/guestline/components/guestline-modal/guestline-modal.component.ts:53-54`).

**Request** (JSON body)

| Name                               | In   | Type                | Required | Rules                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------------------- | ---- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid`                      | body | string              | yes      | The site. Empty: "invalid parent\_uuid". A missing or deleted site: "invalid parentData!"                                                                                                                                                                                                                                                                        |
| `admin_user_uuid`                  | body | string              | yes      | The site's Guestline admin. Empty: "invalid admin\_user\_uuid". An unknown or deleted user: "user not found"                                                                                                                                                                                                                                                     |
| `gl_siteid`                        | body | string              | yes      | The Guestline site ID. Empty: "invalid gl\_siteid"                                                                                                                                                                                                                                                                                                               |
| `gl_interfaceid`                   | body | any non-empty value | yes      | The Guestline interface ID. Empty: "invalid gl\_interfaceid"                                                                                                                                                                                                                                                                                                     |
| `gl_operatorcode`                  | body | string              | yes      | The Guestline operator code. Empty: "invalid gl\_operatorcode"                                                                                                                                                                                                                                                                                                   |
| `gl_pw_plain`                      | body | string              | yes      | The Guestline password. Empty: "invalid gl\_pw\_plain". Encrypted with a key written in the code before it is stored (apipy @ 0e83c85e5a, `model/gl/gl_parent.py:193-196`)                                                                                                                                                                                       |
| `gl_housekeeping_gl_to_sf_mapping` | body | object              | yes      | `red`, `amber` and `green`, each a non-empty list of Guestline housekeeping codes. Otherwise "invalid gl\_housekeeping\_gl\_to\_sf\_mapping", or that message with `.red`, `.amber` or `.green`                                                                                                                                                                  |
| `gl_roomstatus_gl_to_sf_mapping`   | body | object              | yes      | `red`, `amber` and `green`, each a non-empty string. Otherwise "invalid gl\_roomstatus\_gl\_to\_sf\_mapping", or that message with `.red`, `.amber` or `.green`. The admin app sends one of that colour's housekeeping codes \[[ASK-153](https://github.com/snapfix/docs/blob/main/ASK.md#ask-153-should-the-admin-apps-guestline-page-feed-the-guestline-sync)] |

The checks run in this order: the fields, the site, the admin, then an existing link (`model/gl/gl_parent.py:104-183`).

**Response** `200`: `data` is the new link as a [Guestline site object](#guestline-site-object).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "parent_uuid": "123",
    "parent_name": "Riverside Hotel",
    "gl_parent_uuid": "456",
    "gl_siteid": "SITE01",
    "gl_parent_enabled": 1
  }
}
```

The example shows some of the object's fields.

**Errors:** HTTP `200` with `result` `false`:

* "invalid params" when the body is the JSON value `null`. An empty body, or one that is not JSON, gives HTTP `500`.
* The field messages in the request table, "invalid parentData!" and "user not found".
* "Guestline Parent exists but deleted. Please contact support to activate the account!", "Guestline Parent exists but disabled. Please contact support to enable the account!" or "Guestline Parent account already exists!" when the site already has a link that is deleted, disabled or enabled.

Other exceptions are not caught and give HTTP `500`.

**Side effects:**

* Inserts a [`guestline_parent`](https://docs.snapfix.com/engineering-reference/db/tables/guestline_parent.md) row with the encrypted password (`gl_pw_encrypted`), both mappings as JSON text, and the token's user as creator and modifier (`model/gl/gl_parent.py:201-220`).
* Writes the request body to apipy's daily API log table (`apilog_<date>`). The log masks only `password`, `password_new` and `password_old`, so `gl_pw_plain` is stored in plain text (apipy @ 0e83c85e5a, `model/t_log_ip_blocked_v3.py:343-351`, `:943-954`, `:1143-1149`).
* Sends no email and no notification.

## GET /guestline-parent/{gl\_parent\_uuid}/business/{gl\_business\_uuid}/status/{enabled\_status}

Would set whether a group of a Guestline site is enabled. Today it changes nothing: the route stops first.

* **Auth:** user token. No staff flag or membership check.
* **Used by:** webadmin\_angular, the on/off switch of a group under a Guestline site (`GuestlineComponent.changeGuestlineItemState` through `GuestlineService.updateGuestlineItemState`: webadmin\_angular @ db972390b8, `src/app/pages/guestline/guestline.component.ts:55-63`; `src/app/pages/guestline/guestline.component.html:95`; `src/app/services/guestline/guestline.service.ts:59-63`). It sends the site's `parent_uuid` as `gl_parent_uuid` and the Snapfix group's `business_uuid` as `gl_business_uuid`, where the route expects the Guestline IDs.

**Request**

| Name               | In   | Type   | Required | Rules                                                                           |
| ------------------ | ---- | ------ | -------- | ------------------------------------------------------------------------------- |
| `gl_parent_uuid`   | path | string | yes      | The Guestline site (`guestline_parent.uuid`)                                    |
| `gl_business_uuid` | path | string | yes      | The Guestline group (`guestline_business.uuid`)                                 |
| `enabled_status`   | path | string | yes      | `1` to enable, `0` to disable. Not checked today, because the route stops first |

**Response** `200` for every call:

```json
{
  "result": false,
  "message": "service temporarily not available!",
  "serverTs": 1794387595000
}
```

**Errors:** the only answer is the one above, raised before any check \[[ASK-152](https://github.com/snapfix/docs/blob/main/ASK.md#ask-152-should-the-guestline-pages-on-and-off-switches-work)] (apipy @ 0e83c85e5a, `model/gl/gl_business.py:103-105`). The code below the stop would answer "invalid status!", "Guestline Parent account not found!", "Guestline Business account already enabled!" or "Guestline Business account already disabled!"; its lookup calls `self._executeRO_v2`, which the class does not have, so it would fail with HTTP `500` (`gl_business.py:107-126`, the call at `:118`).

**Side effects:** none today. The code below the stop would set `fEnabled`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` on the `guestline_business` row (`gl_business.py:128`). The admin app shows the server's message as an error and leaves the switch as it was (webadmin\_angular @ db972390b8, `src/app/services/guestline/guestline.service.ts:59-63`, `src/app/pages/guestline/guestline.component.ts:68-70`).

## GET /guestline-parent/{gl\_parent\_uuid}/businesses

Lists the groups of a Guestline site, 50 per page by default, with their Snapfix group, their Guestline state and their admin.

* **Auth:** user token. No staff flag or membership check.
* **Used by:** webadmin\_angular, when a Guestline site's row is expanded on the Guestline page. It sends the site's `gl_parent_uuid` and no paging (webadmin\_angular @ db972390b8, `src/app/pages/guestline/guestline.component.ts:41-49`, `:121-133`; `src/app/pages/guestline/guestline.component.html:48`; `src/app/services/guestline/guestline.service.ts:53-57`).

**Request**

| Name             | In    | Type    | Required | Rules                                                                                                                                        |
| ---------------- | ----- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `gl_parent_uuid` | path  | string  | yes      | The Guestline site (`guestline_parent.uuid`). It is put into the SQL text without binding (apipy @ 0e83c85e5a, `model/gl/gl_business.py:49`) |
| `offset`         | query | integer | no       | Default `0`. Not checked; it goes into `LIMIT` (`gl_business.py:62`)                                                                         |
| `limit`          | query | integer | no       | Default `50`. Not checked, with no maximum; it goes into `LIMIT`                                                                             |
| `sort_field`     | query | string  | no       | `id`, `fName` or `enum_integration_type`. Default `fName`. Other values: "invalid sort\_field" (`gl_business.py:23-24`)                      |
| `sort_type`      | query | string  | no       | `-1` sorts descending; any other value sorts ascending                                                                                       |
| `search_field`   | query | string  | no       | `fName` or `enum_integration_type`, used with `search_value`. Other values: "invalid search field"                                           |
| `search_value`   | query | string  | no       | Matched as a substring, ignoring case, with a bound value                                                                                    |

**Response** `200`: `data` is `{ "total_count", "items" }`, with one [Guestline group object](#guestline-group-object) per item. `total_count` counts the live groups of every Guestline site, not only this site's, because its query has no site filter (`gl_business.py:72-91`).

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "total_count": 1,
    "items": [
      {
        "business_uuid": "321",
        "business_name": "Floor 2",
        "gl_business_uuid": "654",
        "gl_business_enabled": 1,
        "admin_user_email": "jane@example.com"
      }
    ]
  }
}
```

The example shows some of the object's fields.

**Errors:** HTTP `200` with `result` `false`: "no records found" when the page is empty; "invalid sort\_field"; "invalid search field". Other exceptions give HTTP `500`.

**Side effects:** none.

## PUT /guestline-parent/{uuid}

Changes a Guestline site's link. A field that is left out or empty keeps its stored value.

* **Auth:** user token. No staff flag or membership check.
* **Used by:** webadmin\_angular, the same dialog as [POST /guestline-parent](#post-guestline-parent) when the site already has a Guestline account (`GuestlineService.saveGuestlineAccountStatuses` with the account's ID: webadmin\_angular @ db972390b8, `src/app/services/guestline/guestline.service.ts:92-95`; `src/app/pages/guestline/components/guestline-modal/guestline-modal.component.ts:53-54`).

**Request** (JSON body)

| Name                                                                 | In   | Type   | Required | Rules                                                                                                                                                          |
| -------------------------------------------------------------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                                                               | path | string | yes      | The Guestline site (`guestline_parent.uuid`). Unknown or deleted: "Guestline Parent account not found!"                                                        |
| `parent_uuid`                                                        | body | string | no       | Moves the link to another site, which must exist and not be deleted, else "invalid parentData!"                                                                |
| `admin_user_uuid`                                                    | body | string | no       | The site's Guestline admin. An unknown or deleted user: "user not found"                                                                                       |
| `gl_siteid`, `gl_interfaceid`, `gl_operatorcode`                     | body | string | no       | The Guestline login values                                                                                                                                     |
| `gl_pw_plain`                                                        | body | string | no       | A new Guestline password, encrypted with the key in the code (apipy @ 0e83c85e5a, `model/gl/gl_parent.py:335-342`). Missing or empty keeps the stored password |
| `gl_housekeeping_gl_to_sf_mapping`, `gl_roomstatus_gl_to_sf_mapping` | body | object | no       | A value that is not an object keeps the stored mapping. The mapping that results must pass the rules of [POST /guestline-parent](#post-guestline-parent)       |

**Response** `200`: `result` `true`, `message` "updated successfully", and `data` is the link after the change, as a [Guestline site object](#guestline-site-object).

**Errors:** HTTP `200` with `result` `false`: "Guestline Parent account not found!"; "invalid parentData!"; "user not found"; the mapping messages of [POST /guestline-parent](#post-guestline-parent) (`model/gl/gl_parent.py:253-346`). A body that is empty, not JSON, or the JSON value `null` gives HTTP `500`: the handler adds the path's `uuid` to the body before any check (apipy @ 0e83c85e5a, `app.py:3985-3986`). Other exceptions give HTTP `500` too.

**Side effects:**

* Updates the `guestline_parent` row: the site, the admin, the Guestline login values, `gl_pw_encrypted` when a new password is sent, both mappings, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` (the token's user) (`model/gl/gl_parent.py:344`).
* Writes the request body, with the plain password, to apipy's API log, as [POST /guestline-parent](#post-guestline-parent) does.

## GET /guestline-parent/{uuid}/status/{enabled\_status}

Would set whether a Guestline site is enabled. Today it changes nothing: the route stops before it reads or writes anything.

* **Auth:** user token. No staff flag or membership check.
* **Used by:** webadmin\_angular, the on/off switch of a Guestline site on the Guestline page (`GuestlineComponent.changeGuestlineItemState`: webadmin\_angular @ db972390b8, `src/app/pages/guestline/guestline.component.ts:55-68`; `src/app/pages/guestline/guestline.component.html:63`; `src/app/services/guestline/guestline.service.ts:59-63`). It sends the site's `parent_uuid` as `uuid`, where the route expects the Guestline site's ID.

**Request**

| Name             | In   | Type   | Required | Rules                                                                           |
| ---------------- | ---- | ------ | -------- | ------------------------------------------------------------------------------- |
| `uuid`           | path | string | yes      | The Guestline site, looked up as `guestline_parent.uuid`                        |
| `enabled_status` | path | string | yes      | `1` to enable, `0` to disable. Not checked today, because the route stops first |

**Response** `200` for every call:

```json
{
  "result": false,
  "message": "service temporarily not available!",
  "serverTs": 1794387595000
}
```

**Errors:** the only answer is the one above, raised before any read or write \[[ASK-152](https://github.com/snapfix/docs/blob/main/ASK.md#ask-152-should-the-guestline-pages-on-and-off-switches-work)] (apipy @ 0e83c85e5a, `model/gl/gl_parent.py:348-350`). The code below the stop would answer "invalid status!", "Guestline Parent account not found!", "Guestline Parent account already enabled!" or "Guestline Parent account already disabled!".

**Side effects:** none today. The code below the stop would set `fEnabled`, `fModifiedTs`, `fServerTs` and `uuid_tUser_ModifiedBy` on the `guestline_parent` row (`gl_parent.py:365`). The admin app shows the server's message as an error and leaves the switch as it was (webadmin\_angular @ db972390b8, `src/app/services/guestline/guestline.service.ts:59-63`, `src/app/pages/guestline/guestline.component.ts:68-70`).

## GET /guestline-parents

Lists the Guestline sites, 50 per page by default, with their Snapfix site, Guestline admin and mappings.

* **Auth:** user token. No staff flag is checked, so any signed-in user can list every Guestline site, with each Guestline admin's email and mobile number (apipy @ 0e83c85e5a, `app.py:3937-3956`).
* **Used by:** webadmin\_angular, the Guestline page on load. It sends no paging, so the page shows the first 50 sites (webadmin\_angular @ db972390b8, `src/app/services/guestline/guestline.service.ts:49-51`; `src/app/pages/guestline/guestline.component.ts:36-39`, `:111-119`).

**Request** (query)

| Name           | In    | Type    | Required | Rules                                                                                                                                                                                                      |
| -------------- | ----- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `offset`       | query | integer | no       | Default `0`. Not checked; it goes into `LIMIT` (apipy @ 0e83c85e5a, `model/gl/gl_parent.py:56`)                                                                                                            |
| `limit`        | query | integer | no       | Default `50`. Not checked, with no maximum; it goes into `LIMIT`                                                                                                                                           |
| `sort_field`   | query | string  | no       | `id`, `fName`, `email_key`, `gl_siteid`, `gl_interfaceid` or `gl_operatorcode`. Default `fName`. Other values: "invalid sort\_field" (`gl_parent.py:19-20`)                                                |
| `sort_type`    | query | string  | no       | `-1` sorts descending; any other value sorts ascending                                                                                                                                                     |
| `search_field` | query | string  | no       | `fName`, `fCustomerType`, `timezone_name`, `origin`, `fAddress`, `gl_siteid`, `gl_interfaceid` or `gl_operatorcode`, used with `search_value`. Other values: "invalid search field" (`gl_parent.py:46-47`) |
| `search_value` | query | string  | no       | Matched as a substring, ignoring case, with a bound value                                                                                                                                                  |

**Response** `200`: `data` is `{ "total_count", "items" }`, with one [Guestline site object](#guestline-site-object) per live link.

```json
{
  "result": true,
  "message": "success",
  "serverTs": 1794387595000,
  "data": {
    "total_count": 1,
    "items": [
      {
        "parent_uuid": "123",
        "parent_name": "Riverside Hotel",
        "gl_parent_uuid": "456",
        "admin_user_email": "jane@example.com",
        "admin_user_mobile": "7700900123"
      }
    ]
  }
}
```

The example shows some of the object's fields.

**Errors:** HTTP `200` with `result` `false`: "no records found" when the page is empty; "invalid sort\_field"; "invalid search field" (`gl_parent.py:19-20`, `:46-47`, `:62-63`). Other exceptions give HTTP `500`.

**Side effects:** none.

## GET /oauth/callback

Cloudbeds' redirect target after a user approves access. It exchanges the code for the building's Cloudbeds access token, or its API key, and stores it.

* **Auth:** none. The route checks no login and no session, and its `state` is the building's UUID, not a value stored when the consent started, so any caller with a Cloudbeds code can attach it to any building (cloudbeds\_py\_server @ 17b14a0ee2, `app/api/v1/endpoints/cloudbeds.py:81-137`). The service's README says every endpoint except the webhooks needs a Basic login (`README.md:161`), which this route does not check.
* **Used by:** Cloudbeds, external: it redirects the browser here after the user approves the app. The customer registers this URL, `https://pms-integration.snapfix.com/cloudbeds/oauth/callback`, as the redirect URI of the Snapfix integration in Cloudbeds (`docs/Cloudbeds PMS Customer Onboarding Guide.txt:48`).

**Request** (query)

| Name    | In    | Type   | Required        | Rules                                                                            |
| ------- | ----- | ------ | --------------- | -------------------------------------------------------------------------------- |
| `code`  | query | string | yes             | The authorization code from Cloudbeds. Missing: `422`                            |
| `state` | query | string | yes in practice | The building's UUID. Missing or empty: "Missing state (building UUID) parameter" |

**Response** `200`:

```json
{
  "status": "success",
  "message": "OAuth tokens stored successfully",
  "data": {
    "buildingUUID": "123",
    "propertyId": "456",
    "auth_mode": "oauth",
    "token_expires_at": 1800003600
  },
  "error": null
}
```

* When Cloudbeds returns an API key (a token that starts with `cbat_`), the message is "API Key stored successfully", `auth_mode` is `api_key` and `token_expires_at` is `null`.
* `token_expires_at` is in Unix seconds, not milliseconds.

**Errors:**

* `422` "Validation error" when `code` is missing.
* HTTP `200` with `status` `error`: "Missing state (building UUID) parameter" (error "Bad request"); "Building site mapping not found" (error "Not found"), when no active, live mapping has that building; "Failed to exchange authorization code" (error "OAuth error"), when Cloudbeds refuses the code.

**Side effects:**

* Calls Cloudbeds' `POST {CLOUDBEDS_API_BASE_URL}/access_token` with the mapping's client ID and secret (`app/core/cloudbeds_client.py:655-678`).
* Replaces `access_token`, `refresh_token` (empty for an API key) and `token_expires_at` on the building's [`cloudbeds_BuildingSiteMapping`](https://docs.snapfix.com/engineering-reference/db/tables/cloudbeds_buildingsitemapping.md) row, whatever it held before, and sets `fModifiedTs` and `fServerTs` (`cloudbeds.py:112-121`).
* Logs the first ten characters of the new token (`cloudbeds.py:124-128`).

## POST /webhook/receive

Cloudbeds' webhook receiver. It stores each event and, while processing is on, applies housekeeping and reservation events to Snapfix.

* **Auth:** none. The route checks no signature, token or login, so any caller can post events for any property. The `webhook_secret` column of the site mapping is never read or written (cloudbeds\_py\_server @ 17b14a0ee2, `app/models/models.py:20`).
* **Used by:** Cloudbeds, external. It posts the events to `{WEBHOOK_BASE_URL}/cloudbeds/webhook/receive`, the URL that `POST /webhook/subscribe/{buildingUUID}` (no caller) registers (`app/api/v1/endpoints/cloudbeds.py:871-873`); the repo's scripts subscribe buildings through Cloudbeds' API directly (`scripts/subscribe_webhooks.py`). The README says the webhook routes are not enabled in production yet (`README.md:187`), but the staging database, a copy of production, holds subscriptions and stored events.

**Request** (JSON body; any object is accepted, and the route reads these fields)

| Name               | In   | Type   | Required | Rules                                                                                                                                                                                          |
| ------------------ | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`, `action` | body | string | no       | The event's object, such as `housekeeping` or `reservation`, and its action, such as `room_condition_changed` or `notes_changed`. When `object` is empty, `event` is split on `/` into the two |
| `propertyID`       | body | string | no       | The Cloudbeds property; `propertyId` and `propertyID_str` are read too. Stored as text, and matched with a site mapping when the event is processed                                            |
| `reservationID`    | body | string | no       | The Cloudbeds reservation; `reservationId` is read too                                                                                                                                         |
| `data`             | body | object | no       | Event data: `roomID`, `roomCondition`, `frontdeskStatus` and `doNotDisturb` for housekeeping; `notes`, `note` or `reservationNote` for note text                                               |

**Response** `200`, without the usual envelope ([Responses](https://docs.snapfix.com/engineering-reference/api.md#responses)):

```json
{
  "success": true
}
```

**Errors:** none that the sender can see. Every request answers `200` with `{"success": true}`, also for a body that is not JSON and after a storage error: the handler logs the error and rolls back (`cloudbeds.py:144-189`).

**Side effects:**

* Inserts a [`cloudbeds_webhook`](https://docs.snapfix.com/engineering-reference/db/tables/cloudbeds_webhook.md) row with the whole body, the object, the action, the property and `processed` `0`, also when no site mapping matches the property (`cloudbeds.py:164-173`).
* A `housekeeping` event, while `CLOUDBEDS_PROCESS_HOUSEKEEPING` is on (the default), reads the room's live state from Cloudbeds with the building's token, cached for 10 seconds, and falls back to the payload's values when Cloudbeds does not answer. It then inserts a `cloudbeds_InboundQueue` row and schedules the room's status update to Snapfix's [POST /v1/internal/rooms/{uuid}/status](#post-v1internalroomsuuidstatus) (`cloudbeds.py:228-390`; `app/core/config.py:40`).
* A `reservation` event, while `CLOUDBEDS_PROCESS_RESERVATIONS` is on (the default): `notes_changed` writes the note text into `tPri_RoomGuestStatus.hsk_traces` in a background thread, from the payload when Cloudbeds does not answer; any other action starts the building's reservation sync, debounced for 5 seconds. That sync reads the reservations from Cloudbeds and writes rooms, guests, guest statuses and checkout tasks (`tPri_Room`, `tPri_RoomGuests`, `tPri_RoomGuestStatus`, `tPri_Job`) (`cloudbeds.py:503-645`; `app/core/config.py:41`).
* Sets `processed` to `1` on the stored row when a handler ran (`cloudbeds.py:217-223`).

## GET /{roomStatusChangeLogUUID} (Cloudbeds)

Sends one Snapfix room status change to Cloudbeds: it queues the change and runs the whole outbound queue before it answers.

* **Auth:** the Cloudbeds service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`), not a building's (cloudbeds\_py\_server @ 17b14a0ee2, `app/core/security.py:11-40`).
* **Used by:** php-apis, after an app saves a room status change (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45531-45544`), and api\_php\_live\_v2's `MapRoomStatus` job, with the server's `CLOUDBEDS_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:47-51`).

**Request**

| Name                      | In   | Type   | Required | Rules                                                                                                                                                                             |
| ------------------------- | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomStatusChangeLogUUID` | path | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. The route does not check the row's integration source |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully",
  "data": {
    "outbound_queue_uuid": "5c1e2b7a-0f3d-4e6a-9b8c-1d2e3f4a5b6c",
    "room_uuid": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a",
    "cloudbeds_room_id": "1042",
    "room_condition": "clean"
  },
  "error": null
}
```

`room_condition` is the Cloudbeds condition mapped to the change's main status, or `dirty` when no mapping exists (`app/api/v1/endpoints/cloudbeds.py:975-1009`).

**Errors:**

* `401` "Not authenticated" with no login; `401` "Incorrect username or password" for a wrong one; `500` "Authentication not configured" when the service has no login set.
* HTTP `200` with `status` `error`: "Room status change log not found", "Building not found for room", "Building site mapping not found" and "Room mapping not found" (each with error "Not found"); "Internal server error", with the exception text in `error` (`cloudbeds.py:926-1047`).

**Side effects:**

* Inserts a `cloudbeds_OutboundQueue` row for the room, with `cloudbedsSynced` `0` (`cloudbeds.py:1012-1029`).
* Runs the outbound sync before it answers: every unsynced row of every building is posted to Cloudbeds (`cloudbeds.py:1032`). Each row is marked synced on success; a failure adds a retry, and the fifth failure deletes the row. A success clears the room's status cache key, and a failed push of the "inspected" condition turns that condition off for the building (`app/core/background_tasks.py:43-141`).

## GET /api/v1/inbound (Clock)

Clock PMS+ polls this route for Snapfix changes. It returns the building's queued room status changes that the outbound sync has not marked yet.

* **Auth:** the building's API key: the `x-api-key` header must equal the `webhook_apikey` of an active, live `clock_BuildingSiteMapping` row (clock\_py\_server @ ab0a701fdf, `app/api/v1/endpoints/clock.py:37-53`, `:60-63`). The key picks the building.
* **Used by:** Clock PMS+, external, which polls with the building's key; the service's README documents the route (`README.md:65-66`). The service's outbound sync also sends each row to Clock's API itself, and the staging database, a copy of production, has no Clock tables \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production), [ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

**Request**

| Name        | In     | Type   | Required | Rules                                                                                            |
| ----------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `x-api-key` | header | string | yes      | The building's API key. Missing: `422`; empty: "API key is required"; unknown: "Invalid API key" |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Found 2 unsynced items",
  "data": [
    { "clock_roomId": "101", "clock_roomStatusCode": "2" },
    { "clock_roomId": "102", "clock_roomStatusCode": "5" }
  ]
}
```

`data` holds every `clock_OutboundQueue` row of the key that is not synced and not deleted, with no limit; an empty status is `null` (`clock.py:71-93`).

**Errors:** `422` "Validation error" when the header is missing (`app/main.py:116-126`). HTTP `200` with `status` `error`: "API key is required", "Invalid API key" and "Internal server error"; a wrong key does not get a `401`. With `APP_DEBUG` on, errors also carry a `debug` traceback \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)].

**Side effects:** none. The route does not mark the rows, so they come back on every poll until the outbound sync sends them to Clock's API and sets `clockSynced` (`app/core/background_tasks.py:33-95`). That sync runs only from `PUT /trigger/outbound-sync`, because its periodic start is commented out (`app/main.py:56-57`) \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

## POST /api/v1/outbound (Clock)

Clock PMS+ posts its room changes. The route queues them for Snapfix.

* **Auth:** the building's API key, as on [GET /api/v1/inbound (Clock)](#get-apiv1inbound-clock) (clock\_py\_server @ ab0a701fdf, `app/api/v1/endpoints/clock.py:102-114`).
* **Used by:** Clock PMS+, external, with the building's key; no Clock tables exist in the staging copy of production \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production), [ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

**Request** (JSON body)

| Name                           | In     | Type   | Required | Rules                                                                               |
| ------------------------------ | ------ | ------ | -------- | ----------------------------------------------------------------------------------- |
| `x-api-key`                    | header | string | yes      | The building's API key, as above                                                    |
| `items`                        | body   | array  | yes      | One object per room change. An empty array: "Request body must contain items array" |
| `items[].clock_roomId`         | body   | string | yes      | The Clock room ID                                                                   |
| `items[].clock_roomStatusCode` | body   | string | yes      | The Clock status code                                                               |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Successfully processed 2 items"
}
```

**Errors:** `422` "Validation error" when the header is missing or an item lacks a field. HTTP `200` with `status` `error`: "Invalid API key", "Request body must contain items array" and "Internal server error", after a rollback (`clock.py:117-118`, `:148-156`).

**Side effects:** inserts one `clock_InboundQueue` row per item, with `snapfixSynced` `0` and `external_system` as the creator, and commits them together (`clock.py:123-146`). The inbound sync applies these rows to Snapfix through [POST /v1/internal/rooms/{uuid}/status](#post-v1internalroomsuuidstatus) (`app/core/background_tasks.py:305-376`), but it runs only from `PUT /trigger/inbound-sync`, which nothing calls \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

## GET /{uuid}

Queues one Snapfix room status change for Clock PMS+, but only a change whose integration source is `clock`. Snapfix's own changes have an empty source, so they are refused.

* **Auth:** the Clock service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`) (clock\_py\_server @ ab0a701fdf, `app/core/security.py:7-27`). No login: `401`. A wrong login, or none set, gets HTTP `200` (see Errors).
* **Used by:** api\_php\_live\_v2's `MapRoomStatus` job, for each building with a Clock mapping, with the server's `CLOCK_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:29-33`). php-apis never calls Clock. The staging database has no Clock tables, so on staging the job skips Clock; whether any production building uses Clock is open \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

**Request**

| Name   | In   | Type   | Required | Rules                                                                                                                                                                                                                             |
| ------ | ---- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid` | path | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row whose integration source is `clock`, else "Integration source must be 'clock'" (`app/main.py:208-210`) |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully"
}
```

**Errors:**

* `401` "Not authenticated" when no login is sent.
* HTTP `200` with `status` `error`: "Invalid credentials" (a wrong login); "Basic auth not configured"; "Room status change log not found"; "Integration source must be 'clock'"; "Room mapping not found"; "Building site mapping not found"; "Room status mapping not found"; "Room status not found"; "Room status change already processed", when the room's cached Clock status is the same; "Internal server error", after a rollback (`app/main.py:185-317`).
* With `APP_DEBUG` on, errors also carry a `debug` traceback \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)].

**Side effects:** inserts a `clock_OutboundQueue` row with the building's API key, the Clock room ID and the status code, `clockSynced` `0`, and the change's creator, then writes the room's status to the Redis cache (`app/main.py:284-303`). It does not call Clock: Clock reads the row with [GET /api/v1/inbound (Clock)](#get-apiv1inbound-clock).

## GET /inbound

Comtrol polls this route for the room status messages waiting for the site. Each poll returns them once.

* **Auth:** the site's own Basic login, checked against `basicauth_username` and `basicauth_password` on a live `comtrol_BuildingSiteMapping` row. The password is compared in constant time with the value stored in plain text (comtrol\_py\_server @ 70129b5d33, `app/api/v1/endpoints/comtrol.py:22-34`).
* **Used by:** Comtrol, external. The service's API description says Comtrol polls this route (`docs/openapi-inbound-outbound.yaml:45`); it is the only way Comtrol gets Snapfix's changes. The staging copy of production has no Comtrol building mapping \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

**Request:** no body. The Basic login picks the site.

**Response** `200`:

```json
{
  "UHLL": ["1735300000100011440011175003101"]
}
```

Each string is one UHLL message, built from the stored fields: fixed fields, then a status field and a room field, each with its length (`comtrol.py:91-107`; the layout is in `app/schemas/comtrol.py`). An empty list means nothing is waiting.

**Errors:** `401` `{"detail": "UNAUTHORIZED"}` for a wrong login, and `{"detail": "Not authenticated"}` when none is sent, both with `WWW-Authenticate: Basic`; `500` `{"detail": "INTERNAL_SERVER_ERROR"}` when the read fails (`comtrol.py:115-120`).

**Side effects:** sets `comtrolSynced` to `1` on every `comtrol_OutboundQueue` row it returns, so the next poll does not return them, even when this answer is lost (`comtrol.py:109-113`).

## POST /outbound

Comtrol posts room status messages. The route queues them, and a background task applies each one to the room.

* **Auth:** the site's Basic login, as on [GET /inbound](#get-inbound).
* **Used by:** Comtrol, external. The service's API description says Comtrol posts to this route (comtrol\_py\_server @ 70129b5d33, `docs/openapi-inbound-outbound.yaml:46`).

**Request** (JSON body)

| Name   | In   | Type             | Required | Rules                                                                                                                                                                                                     |
| ------ | ---- | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UHLL` | body | array of strings | yes      | At least one message. Each must parse: at least 21 characters, status and room length fields of three digits, and data of exactly those lengths (`app/core/uhll.py:8-51`; `app/schemas/comtrol.py:30-35`) |

**Response** `200`:

```json
{
  "status": "success"
}
```

The answer means the messages were queued, not that the rooms changed.

**Errors:** `400` `{"detail": "<reason>"}` for a message that does not parse, for example "UHLL message is too short (3 chars); expected at least 21"; a bad message rejects the whole batch before anything is saved (`app/api/v1/endpoints/comtrol.py:163-171`, `:215-217`). `401` as on [GET /inbound](#get-inbound). `422` when `UHLL` is missing or empty. `500` `{"detail": "INTERNAL_SERVER_ERROR"}` (`comtrol.py:218-224`).

**Side effects:**

* Inserts one `comtrol_InboundQueue` row per message, with `snapfixSynced` `0`, and commits them (`comtrol.py:177-203`).
* A background task then finds each room by its DFID and room number in `comtrol_RoomMapping`, finds the status by the message's status code among the building's statuses, and posts it to [POST /v1/internal/rooms/{uuid}/status](#post-v1internalroomsuuidstatus) with the site's login and `integrationSource` `comtrol`. It sets `snapfixSynced` to `1` on HTTP `200` and to `-1` otherwise, and nothing retries a failed row (`app/core/background_tasks.py:14-125`). The room lookup is not limited to the site's own rooms, so a room number that two sites share can reach the wrong room, which Snapfix then refuses.

## GET /{roomStatusChangeLogUUID} (Comtrol)

Queues one Snapfix room status change as a UHLL message for the site's next poll.

* **Auth:** one Basic login for all Comtrol sites, `ROOM_STATUS_USERNAME` and `ROOM_STATUS_PASSWORD` in the service's settings, compared in constant time. When either is not set, every call gets `401` (comtrol\_py\_server @ 70129b5d33, `app/api/v1/endpoints/comtrol.py:36-53`; `app/core/config.py:19-20`). The route is left out of the service's published API description (`app/main.py:140-143`).
* **Used by:** php-apis, after an app saves a room status change, at `https://pms-integration.snapfix.com/comtrol/<uuid>`; the service serves the route at its root, so the gateway must remove `/comtrol` \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45561-45575`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `COMTROL_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:5-9`).

**Request**

| Name                      | In   | Type   | Required | Rules                                                                                                                      |
| ------------------------- | ---- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `roomStatusChangeLogUUID` | path | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Data processed and inserted successfully"
}
```

**Errors:**

* `401` `{"detail": "UNAUTHORIZED"}` for a wrong login, and `{"detail": "Not authenticated"}` when none is sent.
* HTTP `200` with `{"status": "error", "message": ...}`: "Log not found", "No valid room mapping found", "No comtrol room status found" and "No comtrol room mapping found" (`comtrol.py:241-300`).
* `500` `{"detail": "<exception text>"}` when the insert fails (`comtrol.py:368-372`).

**Side effects:** inserts a `comtrol_OutboundQueue` row with the UHLL fields for the room's new status and the site's stored login (`basicauth_base64`), with `comtrolSynced` `0`, and commits it (`comtrol.py:319-364`). Nothing is sent now: Comtrol gets the row on its next [GET /inbound](#get-inbound).

## GET /staycity/auth

Deputy's sign-in redirect. It answers the page that finishes the sign-in.

* **Auth:** none. Deputy sends the browser here after the user approves access; the redirect URI is the setting `DEPUTY_REDIRECT_URI` (deputy\_py\_server @ 6ee7e87f1a, `.env.example:6`).
* **Used by:** Deputy, external, through the user's browser. A sign-in starts only when someone opens the login URL that `GET /staycity/rosters-sync` returns, and nothing in the repos calls that route. The staging copy of production holds sign-in records with Deputy codes, so the flow has run; whether the integration is live is open \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

**Request** (query)

| Name                | In    | Type   | Required | Rules                                                                              |
| ------------------- | ----- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `code`              | query | string | no       | Deputy's authorization code. Missing: the "Missing authorization code." error page |
| `state`             | query | string | no       | The site's UUID, which `rosters-sync` put in the login URL                         |
| `error`             | query | string | no       | Deputy's error code. When set, the error page is shown                             |
| `error_description` | query | string | no       | Deputy's error text, shown on the error page                                       |

**Response** `200`: an HTML page headed "Please wait", whose script calls [GET /staycity/auth/complete](#get-staycityauthcomplete) with `code` and `state` and shows the result (`app/staycity_pages.py:124-141`).

**Errors:** `400` with an HTML page, "Authorization failed": "Deputy returned an error during sign-in." when `error` is set, or "Missing authorization code." when `code` is missing (`app/main.py:123-146`).

**Side effects:** none on the server. The values of `code` and `state` are written into the page's script without escaping, so a crafted link can run its own script on the page.

## GET /staycity/auth/complete

Finishes the Deputy sign-in: it exchanges the code, stores the Deputy tokens, and fetches the rosters.

* **Auth:** none. Any caller can send any `code` and `state` (deputy\_py\_server @ 6ee7e87f1a, `app/main.py:149-168`).
* **Used by:** deputy\_py\_server itself: the page that [GET /staycity/auth](#get-staycityauth) serves calls it from the browser (`app/staycity_pages.py:140`).

**Request** (query)

| Name    | In    | Type   | Required | Rules                                                                                                              |
| ------- | ----- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `code`  | query | string | yes      | Deputy's authorization code. Missing or empty: `422`. It is written to the auth log before any check               |
| `state` | query | string | no       | The site's UUID. Without it, the newest pending record of any site is used (`app/deputy_auth_repository.py:52-70`) |

**Response** `200`:

```json
{
  "error": false,
  "rosterCount": 12,
  "rosterLabel": "roster entries",
  "savedFilename": "20261114013900.json"
}
```

`rosterLabel` is "roster entry" for one roster and "roster entries" otherwise. The rosters are saved as a JSON file in the data folder, named by the UTC time (`app/rosters.py:20-32`).

**Errors:**

* `422` when `code` is missing or empty.
* `400` `{"error": true, "message": "No pending authorization session found.", "detail": "Call /staycity/rosters-sync before completing OAuth."}` when no pending record matches (`app/staycity_auth_flow.py:30-36`).
* `502` with `error` `true` and "Could not obtain Deputy access token." (Deputy's error text in `detail`), "Authorized, but roster fetch failed." or "Authorized, but Deputy rejected the roster request." (Deputy's answer in `detail`) (`app/staycity_auth_flow.py:45-74`; `app/main.py:161-167`).

**Side effects:**

* Appends the code, with a timestamp, to the auth log file before any check (`app/auth_log.py:5-10`; `app/staycity_auth_flow.py:28`).
* Writes the code and the callback's request headers to the `deputy_auth` record, then the Deputy token answer to `token_json` (`app/staycity_auth_flow.py:39-55`).
* Replaces the Deputy tokens in the one token store that every proxy call reads, so one site's sign-in changes the Deputy account for all (`app/staycity_auth_flow.py:56-57`; `app/deputy_client.py:83-84`).
* Calls Deputy's token endpoint and its roster API (`app/staycity_auth_flow.py:46`, `:60`), and writes the roster file.

## GET /api/v1/inbound (Guestline)

Guestline polls this route for Snapfix changes. It returns the building's queued room status changes that the outbound sync has not marked yet.

* **Auth:** the building's API key: the `x-api-key` header must equal the `webhook_apikey` of an active, live `guestline_BuildingSiteMapping` row (guestline\_py\_server @ 6aa8239243, `app/api/v1/endpoints/guestline.py:53-69`, `:91-95`).
* **Used by:** Guestline, external, if it polls: a poll leaves no trace. The service itself sends each queued row to Guestline's SOAP API in its outbound sync, and the room changes it takes in come from its own reads of Guestline, not from posts: the staging copy of production holds no row that `POST /api/v1/outbound` created \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)] (guestline\_py\_server @ 6aa8239243, `app/core/background_tasks.py:990-1060`).

**Request**

| Name        | In     | Type   | Required | Rules                                                                                            |
| ----------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `x-api-key` | header | string | yes      | The building's API key. Missing: `422`; empty: "API key is required"; unknown: "Invalid API key" |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Found 1 unsynced items",
  "data": [
    {
      "gl_roomId": "123",
      "gl_roomExtenstion": "101",
      "gl_roomStatusCode": "1",
      "gl_housekeepingStatus": "2",
      "gl_maintenanceStatus": "0"
    }
  ]
}
```

* The field name `gl_roomExtenstion` keeps the code's spelling.
* `data` holds every `guestline_OutboundQueue` row of the key that is not synced and not deleted (`guestline.py:104-127`).

**Errors:** `422` "Validation error" when the header is missing. HTTP `200` with `status` `error`: "API key is required", "Invalid API key" and "Internal server error"; a wrong key does not get a `401` (`guestline.py:129-134`).

**Side effects:** none. The route does not mark the rows; the outbound sync, which runs on a timer in this service and sends the rows to Guestline, sets `glSynced` (`app/core/background_tasks.py:1056`; `app/main.py:153`). Whether a poll should mark its rows is open \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

## GET /api/v1/{roomStatusChangeLogUUID} (Guestline)

Queues one Snapfix room status change for Guestline. Guestline reads it with its next poll.

* **Auth:** the Guestline service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`) (guestline\_py\_server @ 6aa8239243, `app/api/v1/endpoints/guestline.py:71-84`, `:195-207`). No login: `401`. A wrong login, or none set, gets HTTP `200` (see Errors).
* **Used by:** php-apis, after an app saves a room status change: it calls `https://pms-integration.snapfix.com/guestline/<uuid>`, but the service serves this route at `/api/v1/<uuid>`, so it answers only if the gateway adds that path \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45467-45481`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `GUEST_LINE_STATUS_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:11-15`).

**Request**

| Name                      | In   | Type   | Required | Rules                                                                                                                                                                                                                                    |
| ------------------------- | ---- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomStatusChangeLogUUID` | path | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. The integration source check is commented out, so a change from any source is taken (`guestline.py:217-219`) |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully"
}
```

**Errors:**

* `401` "Not authenticated" when no login is sent.
* HTTP `200` with `status` `error`: "Invalid credentials" (a wrong login); "Basic auth not configured"; "Room status change log not found"; "Room mapping not found"; "Room details not found"; "Building site mapping not found"; "Room status mapping not found"; "Room status not found"; "Room status change already processed", when the room's cached Guestline status is the same; "Internal server error", after a rollback (`guestline.py:195-376`).
* With `APP_DEBUG` on, errors also carry a `debug` traceback \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)].

**Side effects:** inserts a `guestline_OutboundQueue` row with the building's API key, the room's Guestline ID and extension, the status fields, `glSynced` `0` and the change's creator, then writes the room's status to the Redis cache (`guestline.py:340-362`).

## GET /api/v1/{roomStatusChangeLogUUID} (Hotsoft)

Queues one Snapfix room status change for the Hotsoft outbound sync. The route does not call Hotsoft itself.

* **Auth:** a Basic login that is only checked for being non-empty, so any username and password pass (hotsoft\_py\_server @ e30355215a, `app/core/security.py:8-23`; `app/main.py:205-217`). No login: `401` "Not authenticated". An empty username or password gets HTTP `200` (see Errors).
* **Used by:** php-apis, after an app saves a room status change: it calls `https://pms-integration.snapfix.com/hotsoft/<uuid>`, but the service serves this route at `/api/v1/<uuid>` \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45482-45496`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `HOTSOFT_URL`, which no repo holds (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:23-27`).

**Request**

| Name                      | In     | Type   | Required | Rules                                                                                                                                                                                             |
| ------------------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomStatusChangeLogUUID` | path   | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. The integration source check is commented out (`app/main.py:226-228`) |
| `Authorization`           | header | Basic  | yes      | Any non-empty username and password                                                                                                                                                               |

**Response** `200`. This service answers with `success` (`true` or `false`), not with `status` as the other PMS services do (`app/core/response_utils.py:5-26`):

```json
{
  "success": true,
  "message": "Room status change processed successfully",
  "data": null,
  "error": null
}
```

**Errors:**

* `401` "Not authenticated" when no login is sent.
* HTTP `200` with `success` `false`: "Invalid credentials" (an empty username or password); "Room status change log not found"; "Room mapping not found" (no live Hotsoft room mapping); "Building site mapping not found" (no active Hotsoft building at all); "Room status mapping not found" or "Room status not found" (the change's main status has no active Hotsoft mapping, or the mapped Hotsoft status is missing); "Internal server error", with the exception text in `error`, after a rollback (`app/main.py:205-338`).

**Side effects:** inserts a `hotsoft_OutboundQueue` row with the Hotsoft room ID, the status code, `hotsoftSynced` `0` and the change's creator. The row takes the `webhook_apikey` of the first active Hotsoft building, not of the room's building (`app/main.py:245-252`, `:307-323`). The row reaches Hotsoft only when the outbound sync runs. In the code only `PUT /trigger/outbound-sync` starts it, because the periodic start is commented out (`app/main.py:46-47`), yet in the staging copy of production almost every queued row is marked synced, so something outside the repos runs it.

## POST /chorum/listener/submit

Receives Jonas ARC's SOAP push events, such as room status updates and reservation changes, stores them, and applies room status pushes to Snapfix.

* **Auth:** none on the route. A payload is accepted when it decrypts with an active building's partner key (AES-256-CBC, with the key and IV derived from the building's partner token and partner code), or when it is plain gzip: the plain form is a fallback "for testing" that stays on (jonaschorum\_py\_server @ ca557086fd, `app/core/listening_service.py:57-124`). Every push loads every active building's key and tries each in turn.
* **Used by:** Jonas Chorum ARC, external, which pushes events to this URL. The repo's test scripts post to it by hand (`test_listener_prod.py:6`); they are not counted.

**Request** (SOAP)

| Name           | In                 | Type                    | Required | Rules                                                                                                                                                                                                            |
| -------------- | ------------------ | ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Content-Type` | header             | string                  | no       | Not checked; the code expects `text/xml`                                                                                                                                                                         |
| Body           | body               | SOAP 1.1 envelope (XML) | yes      | Must parse as XML, else "Invalid XML"                                                                                                                                                                            |
| `theRequest`   | body, SOAP element | string (base64)         | yes      | Read from the `http://jonaschorum.com/` namespace, or without one. Missing or empty: "Missing theRequest". Base64 of AES-256-CBC of gzip of XML, or base64 of gzip of XML; when neither decodes: "Decode failed" |

The decoded XML carries `Header/BucketType` (for example `RoomStatusUpdatedRQ`, `HousekeepingRoomStatus`, `CreateReservationRQ` or `ModifyReservationRQ`) and `Parameters/HotelCode` (`listening_service.py:238-266`).

**Response** `200`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SubmitRequestResponse xmlns="http://jonaschorum.com/">
      <SubmitRequestResult>H4sIAAAAAAAAA3NJzS9RSMvPV0gsKs3MS7XlMiIgAAAA</SubmitRequestResult>
    </SubmitRequestResponse>
  </soap:Body>
</soap:Envelope>
```

`SubmitRequestResult` is base64 of gzip of an acknowledgement XML. The acknowledgement names the response BucketType (for example `HousekeepingStatusUpdatedRS` or `CreateReservationRS`), the result (`SUCCESS` or `ERROR`) and a message, and for a reservation push carries a reservation body (`listening_service.py:127-236`). The example value is made up.

**Errors:** every answer is HTTP `200` with a SOAP envelope. An error is an acknowledgement with result `ERROR` and "Invalid XML", "Missing theRequest" or "Decode failed" (`listening_service.py:182-212`, `:794-808`). A decoded message that does not parse is acknowledged as `SUCCESS` and not stored.

**Side effects:**

* Writes each push that parses to `jonaschorum_PushEventLog`, with its event type, hotel code and the decoded XML (`listening_service.py:268-288`).
* A room status push adds a `jonaschorum_InboundQueue` row per room and, when the hotel code matches a building, posts the room's new status to [POST /v1/internal/rooms/{uuid}/status](#post-v1internalroomsuuidstatus) at once (`listening_service.py:353-418`; `app/core/internal_api.py:171-194`).
* A reservation push inserts or updates `tPri_RoomGuestStatus` and `tPri_RoomGuests`, and updates the room's guest status link and occupancy in `tPri_Room` (`listening_service.py:421-790`).

## GET /chorum/{log\_uuid}

Pushes one Snapfix room status change to Jonas Chorum at once, and records it in the outbound queue.

* **Auth:** the Jonas Chorum service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`) (jonaschorum\_py\_server @ ca557086fd, `app/core/security.py:12-40`). The service writes the first 30 characters of every request's `Authorization` header to its log (`app/main.py:44-61`).
* **Used by:** php-apis, after an app saves a room status change: it calls `https://pms-integration.snapfix.com/jonaschorum/<uuid>`, but the service serves this route at `/chorum/<uuid>` \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45546-45559`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `JONAS_CHORUM_URL`; the route's comment names Laravel as its caller (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:53-57`; jonaschorum\_py\_server @ ca557086fd, `app/api/v1/endpoints/chorum.py:165-169`).

**Request**

| Name            | In     | Type   | Required | Rules                                                                                                                                                                                |
| --------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `log_uuid`      | path   | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. A change with no room: "Room UUID is NULL in change log" |
| `Authorization` | header | Basic  | yes      | The service's login                                                                                                                                                                  |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed",
  "data": {
    "outbound_uuid": "7d2e9c1a-4b8f-4e3a-9a52-1f6c0d8b3e77",
    "room_number": "101",
    "clean_status": "Clean",
    "synced": true
  },
  "error": null
}
```

`synced` is `false` when Jonas Chorum did not accept the update; the answer is still `success` then.

**Errors:**

* `401` "Incorrect username or password"; `500` "Authentication not configured" when the service has no login set.
* HTTP `200` with `status` `error`: "Room status change log not found" (error "Not found"); "Room UUID is NULL in change log" (error "Missing data"); "Building not found for room", "Jonas Chorum building site mapping not found" and "Room mapping not found for this room" (each with error "Not found"); "Internal server error", with the exception text in `error` (`chorum.py:171-340`).

**Side effects:** inserts a `jonaschorum_OutboundQueue` row (`chorum_roomNumber`, `chorum_cleanStatus`, `chorumSynced` `0`) and commits it, then sends the update to Jonas Chorum's SOAP operation `UpdateHousekeepingStatusRQ` inside the request and sets `chorumSynced` to `1` when Jonas Chorum accepts it (`chorum.py:292-316`). When the change's main status has no Jonas Chorum mapping, the clean status sent is "Dirty" \[[ASK-156](https://github.com/snapfix/docs/blob/main/ASK.md#ask-156-should-an-unmapped-room-status-reach-jonas-chorum-as-dirty)].

## GET /{roomStatusChangeLogUUID} (Opera)

Queues one Snapfix room status change for Opera, and pushes the whole Opera outbound queue before it answers.

* **Auth:** the Opera service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`) (opera\_py\_server @ 61bc356c45, `app/core/security.py:11-40`).
* **Used by:** php-apis, after an app saves a room status change, at `https://pms-integration.snapfix.com/opera/<uuid>`. That matches this route under the service's `/opera` root path while its `API_V1_STR` is empty, the code default; with `API_V1_STR` set to `/api/v1` the route moves to `/api/v1/<uuid>` \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)] (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45497-45511`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `OPERA_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:17-21`).

**Request**

| Name                      | In     | Type   | Required | Rules                                                                                                                                                                                                             |
| ------------------------- | ------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `roomStatusChangeLogUUID` | path   | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. The integration source check is commented out (`app/api/v1/endpoints/opera.py:61-66`) |
| `Authorization`           | header | Basic  | yes      | The service's login                                                                                                                                                                                               |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully",
  "data": {
    "outbound_queue_uuid": "0f4a6e2b-9c1d-4a7e-8b3f-5d2e1c9a7b64",
    "room_uuid": "2e8d5f10-6a3b-4c9e-9f71-8b0a4d6c2e35",
    "opera_room_id": "4521",
    "housekeeping_status": "Clean",
    "housekeeping_room_status": "Vacant"
  },
  "error": null
}
```

**Errors:**

* `401` "Incorrect username or password"; `500` "Authentication not configured" when the service has no login set.
* HTTP `200` with `status` `error`: "Room status change log not found", "Building not found for room", "Building site mapping not found" and "Room mapping not found" (each with error "Not found"); "Internal server error", with the exception text in `error` (`opera.py:36-215`).

**Side effects:**

* Inserts an `opera_OutboundQueue` row with the Opera room ID, the two housekeeping status names and `operaSynced` `0`, and commits it (`opera.py:173-191`).
* Runs the outbound sync before it answers: every unsynced row of every building is sent to Opera's room status API, `operaSynced` is set to `1` for each success, and a Redis key `opera_room_status:<uuid>` is written for each (`opera.py:193-195`; `app/core/background_tasks.py:393-470`). The sync is a plain function called from an async route, so the worker waits for the whole backlog.

## GET /api/v1/inbound (Protel)

Protel polls this route for the room status changes queued for it that have not been marked.

* **Auth:** the building's API key: the `x-api-key` header must equal the `webhook_apikey` of an active, live `protel_BuildingSiteMapping` row (protel\_py\_server @ 90a79f14d1, `app/api/v1/endpoints/protel.py:37-53`). No Basic login and no token.
* **Used by:** Protel, external, the PMS this route exists for; its poll is not in the repos. The service's outbound sync also sends each row to Protel's API itself, and the staging copy of production has no Protel tables \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production), [ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

**Request**

| Name        | In     | Type   | Required | Rules                                                                                            |
| ----------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `x-api-key` | header | string | yes      | The building's API key. Missing: `422`; empty: "API key is required"; unknown: "Invalid API key" |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Found 1 unsynced items",
  "data": [
    { "protel_roomCode": "101", "protel_roomStatusCode": "2" }
  ]
}
```

**Errors:** `422` "Validation error" when the header is missing. HTTP `200` with `status` `error`: "API key is required", "Invalid API key" and "Internal server error".

**Side effects:** none. The route returns every `protel_OutboundQueue` row of the key with `protelSynced` `0`, with no limit, and marks none of them (`protel.py:60-100`). Only the outbound sync marks rows, and it runs only from `PUT /trigger/outbound-sync`, because its periodic start is commented out (`app/main.py:56-57`) \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

## POST /api/v1/outbound (Protel)

Protel posts its room status changes. The route queues them for Snapfix.

* **Auth:** the building's API key, as on [GET /api/v1/inbound (Protel)](#get-apiv1inbound-protel).
* **Used by:** Protel, external; its post is not in the repos, and the staging copy of production has no Protel tables \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production), [ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

**Request** (JSON body)

| Name                            | In     | Type   | Required | Rules                                                                               |
| ------------------------------- | ------ | ------ | -------- | ----------------------------------------------------------------------------------- |
| `x-api-key`                     | header | string | yes      | The building's API key, as above                                                    |
| `items`                         | body   | array  | yes      | One object per room change. An empty array: "Request body must contain items array" |
| `items[].protel_roomCode`       | body   | string | yes      | The Protel room code                                                                |
| `items[].protel_roomStatusCode` | body   | string | yes      | The Protel status code                                                              |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Successfully processed 1 items"
}
```

**Errors:** `422` "Validation error" when the header is missing, the body is not JSON, or an item lacks a field. HTTP `200` with `status` `error`: "Invalid API key", "API key is required", "Request body must contain items array" and "Internal server error", after a rollback.

**Side effects:** inserts one `protel_InboundQueue` row per item, with the key, `snapfixSynced` `0` and `external_system` as the creator, and commits them together (protel\_py\_server @ 90a79f14d1, `app/api/v1/endpoints/protel.py:102-156`). The rows reach Snapfix only when the inbound sync runs, which only `PUT /trigger/inbound-sync` starts.

## GET /{log\_uuid} (Protel)

Queues one Snapfix room status change for Protel. Nothing is sent to Protel here.

* **Auth:** the Protel service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`) (protel\_py\_server @ 90a79f14d1, `app/core/security.py:7-26`). No login: `401`. A wrong login, or none set, gets HTTP `200`, because the route catches the check's error (`app/main.py:578-580`, `:694-696`).
* **Used by:** api\_php\_live\_v2's `MapRoomStatus` job, for each building with a Protel mapping, with the server's `PROTEL_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:35-39`). php-apis never calls Protel. The staging database has no Protel tables, so on staging the job skips Protel; whether any production building uses it is open \[[ASK-13](https://github.com/snapfix/docs/blob/main/ASK.md#ask-13-which-services-and-scheduled-jobs-run-in-production)].

**Request**

| Name            | In     | Type   | Required | Rules                                                                                                                                                                                             |
| --------------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `log_uuid`      | path   | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row. The integration source check is commented out (`app/main.py:590-592`) |
| `Authorization` | header | Basic  | yes      | The service's login                                                                                                                                                                               |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully"
}
```

**Errors:**

* `401` "Not authenticated" when no login is sent.
* HTTP `200` with `status` `error`: "Invalid credentials" (a wrong login); "Basic auth not configured"; "Room status change log not found"; "Room mapping not found"; "Building site mapping not found"; "Room status mapping not found"; "Room status not found"; "Room status change already processed", when the room's cached Protel status is the same; "Internal server error", after a rollback (`app/main.py:567-699`).

**Side effects:** inserts a `protel_OutboundQueue` row with the Protel room code, the status code, `protelSynced` `0` and the change's creator, then writes the room's status to the Redis cache (`app/main.py:666-685`). Protel reads the row with [GET /api/v1/inbound (Protel)](#get-apiv1inbound-protel); the outbound sync runs only from `PUT /trigger/outbound-sync`.

## GET /api/v1/inbound (Stayntouch)

Stayntouch polls this route for the room status changes queued for it that have not been synced.

* **Auth:** the building's API key: the `x-api-key` header must equal the `webhook_apikey` of an active, live `stayntouch_BuildingSiteMapping` row (stayntouch\_py\_server @ 21e55b9071, `app/api/v1/endpoints/stayntouch.py:38-54`). No Basic login and no token.
* **Used by:** Stayntouch, external, if it polls: a poll leaves no trace, and its poll is not in the repos. The service itself sends queued rows to Stayntouch's API, and takes Stayntouch's changes from its webhook, not from posts \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

**Request**

| Name        | In     | Type   | Required | Rules                                                                                            |
| ----------- | ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| `x-api-key` | header | string | yes      | The building's API key. Missing: `422`; empty: "API key is required"; unknown: "Invalid API key" |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Found 1 unsynced items",
  "data": [
    {
      "stayntouch_roomId": "4501",
      "stayntouch_roomStatusCode": "2",
      "stayntouch_serviceStatusCode": "1"
    }
  ]
}
```

**Errors:** as on [GET /api/v1/inbound (Protel)](#get-apiv1inbound-protel): `422` "Validation error" when the header is missing; HTTP `200` with `status` `error` for "API key is required", "Invalid API key" and "Internal server error".

**Side effects:** none. The route returns every `stayntouch_OutboundQueue` row of the key with `stayntouchSynced` `0`, with no limit, and marks none of them (`stayntouch.py:61-102`). A row leaves the list when the outbound sync pushes it to Stayntouch, which [GET /{log\_uuid} (Stayntouch)](#get-log_uuid-stayntouch) runs on every change \[[ASK-154](https://github.com/snapfix/docs/blob/main/ASK.md#ask-154-which-vendor-systems-call-the-pms-services-poll-post-and-redirect-routes)].

## POST /webhook

Receives Stayntouch's webhook events for room status, guest and reservation changes, and applies them to Snapfix.

* **Auth:** the `snt-webhook-signature` header, the base64 HMAC-SHA256 of the raw body under the service's `STAYNTOUCH_WEBHOOK_SECRET`; a leading `sha256=` is removed first. A wrong signature is only logged, with the expected value, and the request goes on (stayntouch\_py\_server @ 21e55b9071, `app/main.py:513-545`). No token.
* **Used by:** Stayntouch, external; its code is not in the repos.

**Request** (JSON body): an event object with `event` (the event name) and `data`. The route reads `data.hotel_id`; for room events `data.room.id` and `data.status`; for guest events `data.room_id`; for reservation events the hotel ID and the confirmation number.

Events handled: room events `room_status` and `room_status_service`; guest events `checkin_completed`, `checkin_failed`, `reverse_checkin`, `pre_checkin_available`, `pre_checkin_success`, `pre_checkin_failure`, `room_assignment_succeed`, `checkedout` and `reverse_checkout`; reservation events `create_reservation`, `edit_reservation`, `cancel_reservation`, `noshow_reservation`, `reinstate` and `room_move`. Any other event gets "Event ignored" (`app/main.py:566-581`).

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status updated from webhook"
}
```

Guest and reservation events get "Room guest status updated from webhook", and other events "Event ignored"; both add `data` with `event`. A room status event always gets "Room status updated from webhook", whether or not anything changed.

**Errors:** HTTP `200` with `status` `error`: "Missing webhook signature" (no header); "Webhook secret not configured"; "Internal server error", for example for a body that is not JSON, after a rollback. Errors inside the event handlers are not returned, so the answer is still a success (`app/main.py:570-584`).

**Side effects:**

* Writes the event, the raw payload and the hotel ID to `stayntouch_webhook` before the event is checked (`app/main.py:546-562`).
* Room status events: unless the cache already holds the same status, the route reads the room from Stayntouch's API, inserts a `stayntouch_InboundQueue` row and sets the room status cache. It then sends each unsynced inbound row of the building to [POST /v1/internal/rooms/{uuid}/status](#post-v1internalroomsuuidstatus), one request per row, with a login built from the hotel ID and the building's key, and last reads the room's guests and reservations from Stayntouch and writes `tPri_RoomGuestStatus`, `tPri_RoomGuests` and `tPri_Room` (`app/main.py:586-704`; `app/core/background_tasks.py:312-426`).
* Guest events: set `tPri_Room.occupied` from Stayntouch's room record, then read the room's reservations and write the same tables.
* Reservation events: read the reservation from Stayntouch's API by confirmation number, and write the reservation and guest rows.

## GET /{log\_uuid} (Stayntouch)

Queues one Snapfix room status change for Stayntouch, after checking the room's status in Stayntouch, and pushes the outbound queue before it answers.

* **Auth:** the Stayntouch service's own Basic login (`BASIC_AUTH_USERNAME` and `BASIC_AUTH_PASSWORD`). No login: `401`. A wrong login, or none set, gets HTTP `200`, because the route catches the check's error (stayntouch\_py\_server @ 21e55b9071, `app/main.py:1305-1306`, `:1520-1526`).
* **Used by:** php-apis, after an app saves a room status change, at `https://pms-integration.snapfix.com/stayntouch/<uuid>` in `LIVE` mode and `/dev-stayntouch/<uuid>` otherwise (php-apis @ 238ca4414e, `htmlphp/api/snapfix/class/class.functions.php:45512-45529`). Also api\_php\_live\_v2's `MapRoomStatus` job, with the server's `STAYNTOUCH_URL` (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:56-79`; `config/pms.php:41-45`).

**Request**

| Name            | In     | Type   | Required | Rules                                                                                                                      |
| --------------- | ------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `log_uuid`      | path   | string | yes      | A [`tPri_Log_RoomStatusChange`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_log_roomstatuschange.md) row |
| `Authorization` | header | Basic  | yes      | The service's login                                                                                                        |

**Response** `200`:

```json
{
  "status": "success",
  "message": "Room status change processed successfully"
}
```

When Stayntouch already has the status, the message is "No status change needed for Stayntouch" and no row is queued.

**Errors:**

* `401` "Not authenticated" when no login is sent.
* HTTP `200` with `status` `error`: "Invalid credentials" (a wrong login); "Basic auth not configured"; "Room status change log not found" (see the forward below); "Room mapping not found"; "Building site mapping not found"; "Room status mapping not found"; "Auth URL or client credentials not configured for building"; "Connect URL, API version, or hotel ID not configured for building"; "Internal server error", after a rollback (`app/main.py:1294-1526`).

**Side effects:**

* When the change log is not in this database, sends the same request to `SECONDARY_STAYNTOUCH_BASE_URL` (default `http://127.0.0.1:8009`) with the caller's Basic login, and returns that answer \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)] (`app/main.py:1312-1345`; `app/core/config.py:42-46`).
* Reads the room's current status from Stayntouch's API, inserts a `stayntouch_OutboundQueue` row when the room status or the service status must change, and writes the room status cache (`app/main.py:1434-1509`).
* When the change's main status is clean or inspected, sets `tPri_Room.next_clean_ts` to `NULL` (`app/main.py:1448`).
* Pushes the outbound queue before it answers: every unsynced `stayntouch_OutboundQueue` row is sent to Stayntouch's API (`app/main.py:1515`).

## Guestline site object

One Guestline site: a Snapfix site's link to a Guestline account. Each item of [GET /guestline-parents](#get-guestline-parents) and the `data` of [POST](#post-guestline-parent) and [PUT /guestline-parent/{uuid}](#put-guestline-parentuuid) have this shape (apipy @ 0e83c85e5a, `model/gl/gl_parent.py:33`, `:222-251`).

| Field                                                                                                                        | Type           | Meaning                                                                                                                                                                                                                                     |
| ---------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent_uuid`, `parent_name`                                                                                                 | string         | The Snapfix site and its name, trimmed                                                                                                                                                                                                      |
| `fCustomerType`, `email_key`                                                                                                 | string         | The site's customer type and its email key                                                                                                                                                                                                  |
| `gl_parent_uuid`                                                                                                             | string         | The Guestline site's ID (`guestline_parent.uuid`), which the other Guestline routes take                                                                                                                                                    |
| `gl_siteid`, `gl_interfaceid`, `gl_operatorcode`                                                                             | string         | The Guestline login values. The password is never returned: the encrypted column is removed from the answer (`gl_parent.py:244-245`)                                                                                                        |
| `gl_housekeeping_gl_to_sf_mapping`                                                                                           | object         | `red`, `amber` and `green`, each a list of Guestline housekeeping codes                                                                                                                                                                     |
| `gl_roomstatus_gl_to_sf_mapping`                                                                                             | object         | `red`, `amber` and `green`, each a string; the admin app stores one of that colour's housekeeping codes \[[ASK-153](https://github.com/snapfix/docs/blob/main/ASK.md#ask-153-should-the-admin-apps-guestline-page-feed-the-guestline-sync)] |
| `parent_created_ts`, `parent_modified_ts`                                                                                    | integer        | The site's times, in ms                                                                                                                                                                                                                     |
| `gl_parent_enabled`                                                                                                          | integer        | `1` when the link is on, `0` when it is off                                                                                                                                                                                                 |
| `admin_user_uuid`, `admin_user_name`, `admin_user_email`, `admin_user_country_code`, `admin_user_mobile`, `admin_user_image` | string or null | The site's Guestline admin: ID, full name, sign-in email, country code, mobile number and photo URL. Any signed-in user can read them                                                                                                       |

```json
{
  "parent_uuid": "123",
  "parent_name": "Riverside Hotel",
  "fCustomerType": "paying_customer",
  "email_key": "riverside-hotel",
  "gl_parent_uuid": "456",
  "gl_siteid": "SITE01",
  "gl_interfaceid": "1",
  "gl_operatorcode": "OP01",
  "gl_housekeeping_gl_to_sf_mapping": { "red": ["RC"], "amber": ["RD"], "green": ["RI"] },
  "gl_roomstatus_gl_to_sf_mapping": { "red": "RC", "amber": "RD", "green": "RI" },
  "parent_created_ts": 1700000000000,
  "parent_modified_ts": 1700000000000,
  "gl_parent_enabled": 1,
  "admin_user_uuid": "200",
  "admin_user_name": "Jane Smith",
  "admin_user_image": null,
  "admin_user_email": "jane@example.com",
  "admin_user_country_code": "44",
  "admin_user_mobile": "7700900123"
}
```

The two mappings are stored as JSON text and returned decoded (`gl_parent.py:85-99`, `:236-249`).

## Guestline group object

One group of a Guestline site. Each item of [GET /guestline-parent/{gl\_parent\_uuid}/businesses](#get-guestline-parentgl_parent_uuidbusinesses) has this shape (apipy @ 0e83c85e5a, `model/gl/gl_business.py:37-50`).

| Field                                                                                                     | Type           | Meaning                                                                                                                            |
| --------------------------------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `business_uuid`, `business_name`                                                                          | string         | The Snapfix group and its name, trimmed                                                                                            |
| `gl_business_uuid`                                                                                        | string         | The Guestline group's ID (`guestline_business.uuid`)                                                                               |
| `enum_integration_type`                                                                                   | string         | The integration type stored for the group                                                                                          |
| `business_created_ts`, `business_modified_ts`                                                             | integer        | The group's times, in ms                                                                                                           |
| `gl_business_enabled`                                                                                     | integer        | `1` when the group is on, `0` when it is off                                                                                       |
| `log_json`                                                                                                | object         | The group's stored log, kept as JSON text and returned decoded (`gl_business.py:94-97`)                                            |
| `admin_user_name`, `admin_user_email`, `admin_user_country_code`, `admin_user_mobile`, `admin_user_image` | string or null | The group's Guestline admin: full name, sign-in email, country code, mobile number and photo URL. Any signed-in user can read them |

## PMS result object

The answer of the PMS services' routes. Each service has its own shape:

| Service                              | Fields                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cloudbeds, Opera, Jonas Chorum       | `status` (`success` or `error`), `message`, `data` (the route's result, or `null`), and `error` (a label such as "Not found", or the exception text; `null` on success)                                                                                                                                                                                                                     |
| Clock, Guestline, Protel, Stayntouch | `status` (`success` or `error`), `message`, `data` where the route returns one, and on errors `debug` (`error_type`, `error_message` and `traceback`) while the service's `APP_DEBUG` is on \[[ASK-155](https://github.com/snapfix/docs/blob/main/ASK.md#ask-155-which-settings-do-the-pms-services-use-in-production)] (clock\_py\_server @ ab0a701fdf, `app/core/response_utils.py:8-47`) |
| Hotsoft                              | `success` (`true` or `false`), `message`, `data` and `error` (the exception text) (hotsoft\_py\_server @ e30355215a, `app/core/response_utils.py:5-26`)                                                                                                                                                                                                                                     |
| Comtrol                              | `{"status": "success" \| "error", "message": ...}` on its room status route, `{"UHLL": [...]}` on its poll, and FastAPI's `{"detail": ...}` for login and server errors                                                                                                                                                                                                                     |

```json
{
  "status": "error",
  "message": "Room status change log not found",
  "data": null,
  "error": "Not found"
}
```

* The services catch their own errors, so most errors come back as HTTP `200` with `status` `error` (`success` `false` on Hotsoft).
* A missing Basic header gets FastAPI's `401` `{"detail": "Not authenticated"}` everywhere, and a missing `x-api-key` gets `422` "Validation error".
* A wrong Basic login gets `401` on Cloudbeds, Opera, Jonas Chorum and Comtrol, which check it before the route runs; Cloudbeds, Opera and Jonas Chorum answer `500` "Authentication not configured" when no login is set. Clock, Guestline, Hotsoft, Protel and Stayntouch check it inside the route's own error handling and answer HTTP `200`. api\_php\_live\_v2's `MapRoomStatus` job treats any `2xx` answer as a success, so it logs a refused push as sent (api\_php\_live\_v2 @ ef3c4319f6, `app/Jobs/MapRoomStatus.php:70-72`).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/engineering-reference/api/integrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
