Fandaqah PMS

Details for one hotel: address, city, contact fields.

Room cleaning jobs. open_only keeps those not yet completed. A job with no completion time yet is still open. This always returns a capped page of the most recent jobs, never the full history.

Guests currently in the hotel: checked in and not yet checked out. Based on whether the front desk has actually recorded a check-in time with no check-out time yet, rather than just comparing today's date against the planned arrival and departure -- an early departure or a guest staying past checkout would otherwise give the wrong answer.

Recent folios/invoices, most recent first. Each invoice shows the stay period it covers -- the start and end date.

Room maintenance jobs. open_only keeps those not yet completed. Includes the promised completion date where one was set, so a job whose promised date has passed but still isn't marked done is overdue.

List every hotel the calling user may query. Returns each hotel's id, name (Arabic and English), and city.

Night audit runs: what each one processed, and whether it succeeded. The nightly close is where no-shows are flagged, outstanding checkouts are processed and the occupancy snapshot get_occupancy reads is written. A failed or missing run is why yesterday's numbers can look wrong.

The PMS's own occupancy snapshot. Omit hotel_id for the whole portfolio. Returns what the PMS recorded for its most recent snapshot date, verbatim: units_count, occupied, available, cleaning, maintenance, booked, and the percentage the PMS itself computed. The snapshot date is included, because these are daily rows and the latest one may be yesterday. TWO THINGS TO KNOW BEFORE QUOTING THE PERCENTAGE. It can exceed 100%: serviced-apartment-style properties can turn over more than once a day, and the occupied count reflects stays rather than distinct rooms. That is the PMS's own arithmetic, reproduced rather than corrected, so this agrees with what a manager sees in the web app. It is NOT derived from a room's service-status flag. That flag means the room is in service, not that someone is currently in it, and conflating the two overstates occupancy. For a figure this server can define exactly rather than inherit, use get_rooms and count the ones whose state is occupied -- but be aware that is a different question from what the PMS reports here.

Daily occupancy snapshots over the last N days, oldest first. Reads the same underlying data get_occupancy uses for today, so a trend and a spot reading cannot disagree. Percentages are the PMS's own, not recomputed here. One entry per snapshot, exactly as the PMS wrote it. A day the night audit did not run is simply missing rather than filled in -- see get_night_audit when a gap appears.

Money actually taken and paid out at one of the caller's hotels. Cash movement, which is a different question from get_revenue. Revenue is what the bookings were worth; this is what moved. They will not agree and should not: a confirmed booking with no deposit yet contributes to one and not the other. 'deposit' is money in, 'withdraw' is money out. Both are reported, plus the net, all converted to and reported in SAR.

ADR, RevPAR and room-nights for a month. Omit year/month for this month. ADR (average daily rate) is room revenue divided by room-nights sold. RevPAR (revenue per available room) is room revenue divided by rooms available across the month. Each stay is counted for every night it covers, not just once, and uses the same confirmed/non-no-show filter as get_revenue so the two figures agree with each other. Rooms available is based on the hotel's current room count, treated as though it applied for the whole month even if a room was added or removed partway through -- worth knowing since that can make RevPAR look more precise than it really is.

Guests formally registered against a stay (Shomoos / Ministry of Interior). This is a narrow, often-empty record type -- most hotels don't use this specific filing feature. For "who is staying", use get_bookers instead. A national ID or passport number is never returned, same as get_bookers.

Everything about one booking: stay, room, booker, invoices, extensions. Invoices, extensions, and ratings are each returned as their own clean list rather than mixed together, so a booking with several invoices and a couple of extensions still comes back easy to read rather than as one tangled, repeated block.

Recent reservations for one of the caller's hotels, most recently booked first -- this is the order bookings were made in, not the order of their stay dates, so it is the wrong tool for "who's arriving/staying on date X": a booking made long ago for a stay today can sort far down this list. For that, use get_arrivals, get_departures, or get_in_house instead, which filter on the actual dates and status rather than on booking order. Includes cancelled bookings, with their status, so the caller can see them. Revenue figures deliberately do not -- see get_revenue.

Confirmed revenue for a month. Omit hotel_id for the whole portfolio. Reflects actual bookings only -- not subscription billing, and not raw cash movement (see get_payments for that). Cancelled and no-show bookings are excluded: that exclusion is the difference between a revenue figure and a sum of rows.

Revenue split by booking channel for a month. Omit year/month for this month. Uses the same filters as get_revenue -- confirmed, not no-show, by check-in date -- so the individual channels always add up to the same total that tool reports. Bookings with no channel on file are still included, shown as an unnamed channel, rather than being silently left out of the total.

Recent room status changes: what changed, from what, to what, and why. Raw numeric status codes are returned rather than guessed labels, since only code 1 ("in service") is confirmed against the PMS -- the others aren't reliably named yet, and a wrong guess is worse than a plain number.

Room categories and their rack rates. Rates are per day of week, because the PMS prices Friday differently from Tuesday, plus a monthly and an hourly rate where the property sells them.

Rooms/units at one of the caller's hotels, with occupancy status.

Extras sold in a month, totalled by direction. Omit year/month for this month. Amounts are in SAR. Refunds are counted as negative, so the net total is a straightforward sum, not sales minus refunds.

The hotel's sellable extras and their list prices. Prices here are plain SAR -- other financial tools in this server convert from a smaller currency subunit, but this one doesn't need to.

Stays that were extended: the old departure date and the new one.