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 Heat Map API calculates per-day operational load for a date range by counting check-ins, check-outs, and concurrent stays. Results are bucketed into intensity levels using configurable thresholds. Data can be sourced either from the connected PMS or from a manually uploaded XLSX file — useful when the PMS is not yet configured or when working with historical exports.
All endpoints require Authorization: Bearer <token>. PUT requests also require the X-CSRF-Token header.

​
GET /api/heatmap

Generates the heat map for a date range by fetching reservation data from the company’s configured PMS. Auth required: Yes | Role: any
The company must have a PMS configured and a valid API key saved. If no PMS configuration exists the endpoint returns 400 with an error message.

​
Query Parameters

​
desde
string
required
Start date in YYYY-MM-DD format (inclusive).
​
hasta
string
required
End date in YYYY-MM-DD format (inclusive). Must be equal to or later than desde.

​
Response

​
ok
boolean
required
true on success.
​
dias
array
required
One entry per calendar day in the requested range.

​
Example

curl "https://api.example.com/api/heatmap?desde=2024-07-01&hasta=2024-07-31" \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "dias": [
    {"fecha": "2024-07-01", "checkins": 4, "checkouts": 2, "estancias": 8, "total": 14, "nivel": 2},
    {"fecha": "2024-07-02", "checkins": 1, "checkouts": 3, "estancias": 9, "total": 13, "nivel": 2}
  ]
}

​
POST /api/heatmap/xlsx

Generates the heat map for a date range from one or two uploaded XLSX files (check-ins, and optionally check-outs). No PMS connection is required. Auth required: Yes | Role: any
Rate limit: 30 requests / hour
The check-in file is required. The check-out file is optional — if omitted, only check-in traffic is counted. The column positions used to read dates are configured via GET /PUT /api/heatmap/config-xlsx.

​
Request

Multipart form upload:
​
checkins
file
required
XLSX file containing check-in data. Must have a .xlsx extension and must not be empty.
​
checkouts
file
Optional XLSX file containing check-out data. Must have a .xlsx extension if provided.
​
desde
string
required
Start date in YYYY-MM-DD format.
​
hasta
string
required
End date in YYYY-MM-DD format. Must be equal to or later than desde.

​
Response

​
ok
boolean
required
true
​
dias
array
required
Same day-by-day array as the PMS endpoint.
​
warnings
array
Optional. Row-level warnings for unparseable dates or skipped rows.

​
Example

curl -X POST https://api.example.com/api/heatmap/xlsx \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -F "checkins=@checkins_julio.xlsx" \
  -F "checkouts=@checkouts_julio.xlsx" \
  -F "desde=2024-07-01" \
  -F "hasta=2024-07-31"

{
  "ok": true,
  "dias": [
    {"fecha": "2024-07-01", "checkins": 3, "checkouts": 1, "estancias": 0, "total": 4, "nivel": 1}
  ],
  "warnings": ["Fila 14: fecha de check-in no reconocida, se omitió."]
}

​
GET /api/heatmap/umbrales

Returns the current intensity threshold configuration for the company. If no custom thresholds have been set, system defaults are returned. Auth required: Yes | Role: any

​
Response

​
ok
boolean
required
true
​
umbrales
object
required
Threshold configuration.

​
Example

curl https://api.example.com/api/heatmap/umbrales \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "umbrales": {
    "nivel1": 5,
    "nivel2": 10,
    "nivel3": 20
  }
}

​
PUT /api/heatmap/umbrales

Saves intensity threshold configuration for the company. Thresholds must be strictly ascending (nivel1 < nivel2 < nivel3). Auth required: Yes | Role: admin

​
Request

​
nivel1
integer
required
Lower boundary. Integer between 1 and 9999.
​
nivel2
integer
required
Middle boundary. Must be greater than nivel1. Integer between 1 and 9999.
​
nivel3
integer
required
Upper boundary. Must be greater than nivel2. Integer between 1 and 9999.

​
Response

​
ok
boolean
required
true
​
umbrales
object
required
The saved threshold object.

​
Example

curl -X PUT https://api.example.com/api/heatmap/umbrales \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"nivel1": 5, "nivel2": 12, "nivel3": 25}'

{
  "ok": true,
  "umbrales": {"nivel1": 5, "nivel2": 12, "nivel3": 25}
}

​
GET /api/heatmap/config-xlsx

Returns the XLSX column mapping used when parsing uploaded heat map files. Column letters correspond to Excel column headers (e.g., A, B, AA). Auth required: Yes | Role: any

​
Response

​
ok
boolean
required
true
​
config
object
required
Column mapping configuration.

​
Example

curl https://api.example.com/api/heatmap/config-xlsx \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "config": {
    "col_fecha_checkin": "C",
    "col_fecha_checkout": "D"
  }
}

​
PUT /api/heatmap/config-xlsx

Saves the XLSX column mapping for the heat map parser. Only admins can change this setting. Auth required: Yes | Role: admin

​
Request

​
col_fecha_checkin
string
required
Excel column letter for the check-in date column. Must be an alphabetic Excel column reference (e.g., A, B, AA). Max 3 characters.
​
col_fecha_checkout
string | null
Excel column letter for the check-out date column. Pass null to clear. Max 3 characters.

​
Response

​
ok
boolean
required
true
​
config
object
required
The saved column mapping.

​
Example

curl -X PUT https://api.example.com/api/heatmap/config-xlsx \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"col_fecha_checkin": "C", "col_fecha_checkout": "D"}'

{
  "ok": true,
  "config": {
    "col_fecha_checkin": "C",
    "col_fecha_checkout": "D"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us