apaleo

apaleo

This connector works with the apaleo cloud property management system (https://api.apaleo.com): properties, unit groups and units (rooms), rate plans and rates, availability and offers, bookings, reservations and guests, groups and blocks, folios, payments and invoices, maintenance and housekeeping, and performance reports. It can create bookings, change reservations, assign rooms, check guests in and out, set room conditions and create maintenance windows.

Setup (5 minutes)

1. In apaleo open Apps > Connected apps > Add a custom app (or on apaleo.dev register an OAuth simple client, client credentials). Give it the permissions the team needs, for example properties.read, unitgroups.read, units.read, rateplans.read, rates.read, services.read, companies.read, availability.read, offers.read, reservations.read, reservations.create, reservations.manage, reservations.assign-unit, groups.read, blocks.read, folios.read, payments.read, invoices.read, maintenances.read, maintenances.create, operations.change-room-state and reports.read. Leave out the write permissions for a read-only connector.
2. Copy the client id and the client secret (shown once) into APALEO_CLIENT_ID and APALEO_CLIENT_SECRET. The connector gets a token from https://identity.apaleo.com/connect/token with the client credentials grant and renews it every hour.
3. Run apaleo_list_properties to check the connection.

Workflow

• Set-up data: apaleo_list_properties, apaleo_get_property, apaleo_list_unit_groups, apaleo_get_unit_group, apaleo_list_units, apaleo_get_unit, apaleo_list_rate_plans, apaleo_get_rate_plan, apaleo_list_rates, apaleo_list_services, apaleo_list_cancellation_policies, apaleo_list_companies.
• Free rooms and prices: apaleo_get_unit_group_availability (rooms left per room type and night), apaleo_get_unit_availability (free rooms for a stay), apaleo_get_offers (bookable rate plans with prices for one stay).
• New booking: apaleo_get_offers, then apaleo_create_booking with the offer's ratePlanId and one timeSlice per night. Change it with apaleo_update_booking.
• Find a guest or stay: apaleo_list_reservations with text_search (name, email, reservation id), apaleo_get_reservation, apaleo_list_bookings, apaleo_get_booking, apaleo_list_reservation_services. Counts: apaleo_count_reservations. Guests are part of reservations (primaryGuest, additionalGuests) and bookings (booker); change them with apaleo_update_reservation.
• Front desk: today's arrivals are apaleo_list_reservations with date_filter: Arrival, from and to = today and status: Confirmed; assign a room with apaleo_assign_unit (automatic) or apaleo_list_available_units_for_reservation and apaleo_assign_specific_unit, remove it with apaleo_unassign_units; then apaleo_check_in_reservation (undo with apaleo_revert_check_in). Departures: date_filter: Departure, check the folio, then apaleo_check_out_reservation. Change dates or rate with apaleo_amend_reservation.
• Groups: apaleo_list_groups, apaleo_get_group, apaleo_list_blocks.
• Billing: apaleo_list_folios (with reservation_ids), apaleo_get_folio, apaleo_list_folio_payments, apaleo_list_invoices, apaleo_get_invoice.
• Housekeeping and maintenance: apaleo_list_units with condition, apaleo_set_unit_conditions, apaleo_list_maintenances, apaleo_create_maintenance.
• Reports: apaleo_get_property_performance_report (occupancy, ADR, RevPAR), apaleo_get_revenues_report, apaleo_get_arrivals_report.

Switched off at install: apaleo_cancel_reservation and apaleo_set_reservation_no_show; they cannot be undone, so an admin switches them on when the team needs them.

Reading the answers

• Ids are readable codes: a property MUC, a unit group MUC-DBL, a unit MUC-101, a rate plan MUC-FLEX-DBL, a booking ABCDEF, its reservations ABCDEF-1, ABCDEF-2, a folio ABCDEF-1-1.
• Money is {"amount": 120.0, "currency": "EUR"} in major units. Reservation balance is negative when the guest still owes money.
• Dates are YYYY-MM-DD; times are ISO 8601 with the property's UTC offset. A night belongs to the business day it starts on; to is included for availability and performance, excluded for the revenues report.
• Reservation status: Confirmed, InHouse, CheckedOut, Canceled, NoShow. Unit condition: Clean, CleanToBeInspected, Dirty.

Filters: list filters that take several values are comma-separated without spaces (status: Confirmed,InHouse). expand adds embedded objects (expand: booker,assignedUnits).

Paging: lists take page_number (from 1) and page_size (up to 500) and return count with the total. A page past the end answers 204 No Content, which means there is nothing more.

Changes with JSON Patch: apaleo_update_booking and apaleo_update_reservation take a list of operations such as [{"op": "replace", "path": "/comment", "value": "Late arrival"}].

Errors: 401 means the client id or secret is wrong or the token expired; 403 a missing permission on the custom app; 404 an unknown id; 422 a business rule (for example check-in before the arrival day, no unit assigned, a sold-out offer) with the reason in messages; 429 the rate limit.