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 Apartment Catalog is the master inventory that powers every other Stay Sidekick module. The Heat Map, Late Check-in Notifications, and Contact Sync tools all cross-reference this catalog to match reservation data against your real property list. Keeping it accurate and up-to-date is the single most important step before using any other feature. Each company in the platform maintains its own isolated catalog — data from one tenant is never visible to another.
What the catalog stores
Each apartment record holds the following fields, drawn directly from the Apartamento model:
| Field | Description |
|---|
nombre | Human-readable property name (required, up to 200 characters) |
id_pms | The property’s unique identifier inside your PMS (e.g. Smoobu property ID). Null for manually-created entries. |
id_externo | Internal typology or classification code. Multiple apartments can share the same id_externo if they belong to the same property type. |
direccion | Full street address (optional, up to 300 characters) |
ciudad | City (optional, up to 100 characters) |
pms_origen | How the record was created: smoobu, manual, or xlsx |
activo | Whether the apartment is active. Soft-deleted apartments remain in the database with activo = false. |
created_at / updated_at | UTC timestamps managed automatically |
Per-company uniqueness is enforced at the database level: the combination of empresa_id + id_pms must be unique (partial index, only when id_pms is not null). This prevents duplicate PMS properties from being imported more than once.
Adding apartments
There are three ways to add apartments to your catalog. Use whichever fits your workflow — all three methods perform an upsert internally, so running them more than once is always safe.
Manual creation
Smoobu sync
XLSX import
Use this when you want to add a single apartment by hand. Send a POST request with a JSON body containing at least the nombre field.curl -X POST http://localhost/api/apartamentos \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nombre": "Apartamento Sol 3B",
"id_externo": "SOL-3B",
"direccion": "Calle Mayor 10, 3º B",
"ciudad": "Madrid"
}'
{
"ok": true,
"apartamento": {
"id": "a1b2c3d4-...",
"nombre": "Apartamento Sol 3B",
"id_externo": "SOL-3B",
"id_pms": null,
"direccion": "Calle Mayor 10, 3º B",
"ciudad": "Madrid",
"pms_origen": "manual",
"activo": true
}
}
If your company has a Smoobu API key configured (see PMS configuration below), you can pull all your properties from Smoobu in a single request. The API performs a full upsert — new apartments are created, existing ones are updated, and no records are deleted.curl -X POST http://localhost/api/apartamentos/sincronizacion/smoobu \
-H "Authorization: Bearer $TOKEN"
{
"ok": true,
"resultado": {
"creados": 12,
"actualizados": 3,
"sin_cambios": 7
}
}
This endpoint is rate-limited to 10 requests per hour per company to stay within Smoobu’s API quotas. Subsequent sync attempts within the same hour will receive a 429 Too Many Requests response.
Use XLSX import when you do not have a live PMS API connection, or when you want to bulk-load apartments from a spreadsheet. Upload a .xlsx file using multipart form data.curl -X POST http://localhost/api/apartamentos/importacion \
-H "Authorization: Bearer $TOKEN" \
-F "file=@apartments.xlsx"
{
"ok": true,
"resultado": {
"creados": 8,
"actualizados": 2,
"errores": 1
},
"warnings": [
"Fila 4: el nombre está vacío, se omitió."
]
}
- Only
.xlsx files are accepted. .csv and .xls files are rejected with a 400 error.
- The maximum file size is governed by the server’s
MAX_CONTENT_LENGTH setting (default 10 MB).
- Rows with validation errors are skipped and reported as
warnings; valid rows are still imported.
This endpoint is rate-limited to 20 requests per hour. XLSX preview
Before committing an import, you can preview exactly which rows will be created or updated without writing anything to the database. This is useful for catching formatting issues before they affect your live catalog.
curl -X POST http://localhost/api/apartamentos/importacion/preview \
-H "Authorization: Bearer $TOKEN" \
-F "file=@apartments.xlsx"
{
"ok": true,
"preview": [
{
"fila": 2,
"nombre": "Apartamento Mar A1",
"id_externo": "MAR-A1",
"accion": "crear"
},
{
"fila": 3,
"nombre": "Apartamento Sol 3B",
"id_externo": "SOL-3B",
"accion": "actualizar"
}
]
}
PMS configuration
The Smoobu sync (and the PMS-based data feeds used by Heat Map and Late Check-ins) requires your company’s PMS API key to be stored first. The key is encrypted at rest using Fernet symmetric encryption before being written to the database — it is never returned in plain text.
Read current PMS config (key is masked):
curl http://localhost/api/apartamentos/pms \
-H "Authorization: Bearer $TOKEN"
{
"ok": true,
"config": {
"proveedor": "smoobu",
"endpoint": null,
"api_key_masked": "sk-l...****...xQ9z"
}
}
curl -X PUT http://localhost/api/apartamentos/pms \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"proveedor": "smoobu",
"api_key": "YOUR_SMOOBU_API_KEY"
}'
proveedor values: smoobu, beds24, hostaway, cloudbeds.
Remove the PMS config:
curl -X DELETE http://localhost/api/apartamentos/pms \
-H "Authorization: Bearer $TOKEN"
Listing and updating apartments
List all active apartments for your company:
curl http://localhost/api/apartamentos \
-H "Authorization: Bearer $TOKEN"
curl http://localhost/api/apartamentos/<id> \
-H "Authorization: Bearer $TOKEN"
curl -X PUT http://localhost/api/apartamentos/<id> \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nombre": "Apartamento Sol 3B (renovado)",
"ciudad": "Barcelona"
}'
nombre, direccion, and ciudad can be updated. Omitting a field leaves it unchanged.
Soft delete
Deleting an apartment marks it as inactive (activo = false) rather than removing the row. All historical data referencing the apartment is preserved, and the apartment disappears from the active catalog list.
curl -X DELETE http://localhost/api/apartamentos/<id> \
-H "Authorization: Bearer $TOKEN"
