Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sdurutr436/stay-sidekick/llms.txt

Use this file to discover all available pages before exploring further.

The Operational Heat Map gives your team an instant visual summary of how many check-ins and check-outs are expected each day across a chosen date range. Rather than combing through a PMS calendar manually, the heat map collapses all reservation movement into a single colour-coded grid — so you can spot pressure points at a glance, plan staff rotations ahead of time, and avoid being caught off-guard on the busiest days of the week. Every company configures its own intensity thresholds, so the definition of “high load” matches the real scale of your operation.

​
Data sources

The heat map supports two input modes. Both produce the same output format — an array of day objects with check-in and check-out counts — and the same threshold colouring is applied by the frontend regardless of the source. When a PMS API key is configured (see Apartment Catalog → PMS configuration), the heat map queries your PMS directly and processes the reservation data in memory. 
curl "http://localhost/api/heatmap?desde=2025-06-01&hasta=2025-06-30" \
  -H "Authorization: Bearer $TOKEN"
ParameterTypeRequiredDescription
desdeYYYY-MM-DDYesStart of the date range (inclusive)
hastaYYYY-MM-DDYesEnd of the date range (inclusive)
Response (200): 
{
  "ok": true,
  "dias": [
    {
      "fecha": "2025-05-26",
      "checkins": 0,
      "checkouts": 0,
      "mesAdyacente": true
    },
    {
      "fecha": "2025-06-01",
      "checkins": 4,
      "checkouts": 2,
      "mesAdyacente": false
    },
    {
      "fecha": "2025-06-02",
      "checkins": 1,
      "checkouts": 3,
      "mesAdyacente": false
    }
  ]
}
The API returns a full calendar grid expanded to complete Monday–Sunday weeks. Days outside the requested desde/hasta range are included with mesAdyacente: true so the frontend can render a complete week grid. Colour intensity is determined client-side by comparing the sum of checkins + checkouts against your configured thresholds.
Reservation data is never stored in the database. It is fetched from the PMS, processed in memory to produce the daily counts, and discarded. This design is intentional and aligned with GDPR — Stay Sidekick never accumulates guest booking records.

​
XLSX upload (fallback)

When no PMS API integration is configured, upload a spreadsheet of reservations instead. You can provide a single file that contains both check-in and check-out columns, or supply separate files for each. 
curl -X POST http://localhost/api/heatmap/xlsx \
  -H "Authorization: Bearer $TOKEN" \
  -F "checkins=@reservas.xlsx" \
  -F "desde=2025-06-01" \
  -F "hasta=2025-06-30"
To supply a separate check-outs file: 
curl -X POST http://localhost/api/heatmap/xlsx \
  -H "Authorization: Bearer $TOKEN" \
  -F "checkins=@entradas.xlsx" \
  -F "checkouts=@salidas.xlsx" \
  -F "desde=2025-06-01" \
  -F "hasta=2025-06-30"
The checkins field is required. The checkouts field is optional — when omitted, the system reads check-out dates from the same file using the configured check-out column. The response format is identical to the PMS mode. Any rows that cannot be parsed are returned as warnings rather than blocking the whole request. This endpoint is rate-limited to 30 requests per hour.
XLSX mode is the fallback for companies that have not yet set up a PMS API integration, or for one-off analysis using an exported report. Configure which spreadsheet columns map to check-in date and check-out date in the XLSX column configuration section below.

​
Intensity thresholds

Each company defines its own thresholds that control the colour intensity applied to each day in the grid. Thresholds are stored per company (in the company’s configuracion JSONB field) and never affect other tenants. The schema requires three integer values that must satisfy nivel1 < nivel2 < nivel3. The Angular frontend compares the daily total of checkins + checkouts against these values to assign a colour tier. Read current thresholds: 
curl http://localhost/api/heatmap/umbrales \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "umbrales": {
    "nivel1": 10,
    "nivel2": 20,
    "nivel3": 30
  }
}
The default values are nivel1: 10, nivel2: 20, nivel3: 30. Update thresholds (admin only): 
curl -X PUT http://localhost/api/heatmap/umbrales \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nivel1": 3,
    "nivel2": 7,
    "nivel3": 12
  }'
FieldTypeConstraints
nivel1integer1–9999, must be less than nivel2
nivel2integer1–9999, must be greater than nivel1 and less than nivel3
nivel3integer1–9999, must be greater than nivel2
Only company administrators can modify thresholds. Requests from non-admin users will be rejected with 403 Forbidden.
Start by running the PMS heat map for a typical month, then look at the distribution of daily totals to choose thresholds that split your workload into meaningful tiers.

​
XLSX column configuration

Before using the XLSX upload mode, tell Stay Sidekick which columns in your spreadsheet contain the relevant dates. Column identifiers use Excel letter notation (A, B, C, AA, etc.). This configuration is stored once per company and reused for all subsequent uploads. Read current column configuration: 
curl http://localhost/api/heatmap/config-xlsx \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "config": {
    "col_fecha_checkin": "A",
    "col_fecha_checkout": "B"
  }
}
Update column configuration (admin only): 
curl -X PUT http://localhost/api/heatmap/config-xlsx \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "col_fecha_checkin": "C",
    "col_fecha_checkout": "D"
  }'
FieldTypeRequiredDescription
col_fecha_checkinstring (Excel column letter, max 3 chars)YesColumn containing check-in dates
col_fecha_checkoutstring (Excel column letter, max 3 chars) or nullNoColumn containing check-out dates. Set to null when check-outs are not needed or will be supplied via a separate file.
Column values must be valid Excel column letters (e.g. A, B, Z, AA). Numeric column indices are not accepted.

Build docs developers (and LLMs) love

Get started for freeTalk to us