Apartments API — CRUD, Smoobu Sync, and XLSX Import

The Apartments API is the backbone of Stay Sidekick’s property catalog. Every record is scoped to the authenticated user’s company (empresa_id is read from the JWT — never passed as a parameter). Deletions are soft: the record is marked inactive but never removed from the database. The PMS configuration stores encrypted credentials and is returned without exposing the API key.

All endpoints require Authorization: Bearer <token>. POST, PUT, and DELETE requests also require the X-CSRF-Token header.

GET /api/apartamentos

Returns all active apartments that belong to the authenticated user’s company. Auth required: Yes | Role: any

Response

boolean

required

true on success.

apartamentos

array

required

Array of apartment objects.

Show Apartment object

string

UUID of the apartment.

id_externo

string | null

External PMS identifier.

nombre

string

Display name.

direccion

string | null

Street address.

ciudad

string | null

City.

activo

boolean

Whether the apartment is active.

Example

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

{
  "ok": true,
  "apartamentos": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "id_externo": "smoobu-1234",
      "nombre": "Apartamento Sol",
      "direccion": "Calle Mayor 10",
      "ciudad": "Madrid",
      "activo": true
    }
  ]
}

GET /api/apartamentos/<id>

Returns the full detail of a single apartment. Returns 404 if the apartment does not exist or belongs to a different company. Auth required: Yes | Role: any

Path Parameters

string

required

UUID of the apartment.

Response

boolean

required

true on success.

apartamento

object

required

Full apartment object (same shape as the list endpoint).

Example

curl https://api.example.com/api/apartamentos/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "apartamento": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "id_externo": "smoobu-1234",
    "nombre": "Apartamento Sol",
    "direccion": "Calle Mayor 10",
    "ciudad": "Madrid",
    "activo": true
  }
}

POST /api/apartamentos

Creates a new apartment manually. HTML is stripped from all string fields before persisting. Auth required: Yes | Role: any

Request

nombre

string

required

Display name. 1–200 characters.

id_externo

string

Optional external PMS identifier. Max 100 characters.

direccion

string

Street address. Max 300 characters.

ciudad

string

City name. Max 100 characters.

Response

201 Created

boolean

required

true

apartamento

object

required

The newly created apartment object.

Example

curl -X POST https://api.example.com/api/apartamentos \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Apartamento Luna", "ciudad": "Barcelona"}'

{
  "ok": true,
  "apartamento": {
    "id": "7f1c2e3d-0000-4000-a000-000000000001",
    "id_externo": null,
    "nombre": "Apartamento Luna",
    "direccion": null,
    "ciudad": "Barcelona",
    "activo": true
  }
}

PUT /api/apartamentos/<id>

Updates one or more fields of an existing apartment. Only the fields supplied in the body are changed — omitted fields are left untouched. Auth required: Yes | Role: any

Path Parameters

string

required

UUID of the apartment to update.

Request

nombre

string

New display name. 1–200 characters.

direccion

string | null

New street address. Max 300 characters. Pass null to clear.

ciudad

string | null

New city. Max 100 characters. Pass null to clear.

id_externo cannot be updated through this endpoint. Use the Smoobu sync or XLSX import to manage PMS identifiers.

Response

boolean

required

true

apartamento

object

required

The updated apartment object.

Example

curl -X PUT https://api.example.com/api/apartamentos/7f1c2e3d-0000-4000-a000-000000000001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"direccion": "Avda. Diagonal 99"}'

DELETE /api/apartamentos/<id>

Soft-deletes an apartment by marking it as inactive. The record remains in the database and can be recovered at the database level if needed. Auth required: Yes | Role: any

Path Parameters

string

required

UUID of the apartment to deactivate.

Response

200 OK — {"ok": true} 404 Not Found — apartment not found or belongs to another company.

Example

curl -X DELETE https://api.example.com/api/apartamentos/7f1c2e3d-0000-4000-a000-000000000001 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

POST /api/apartamentos/sincronizacion/smoobu

Pulls all properties from the Smoobu API and upserts them into the local catalog. Existing apartments matched by id_externo are updated; new ones are created. Auth required: Yes | Role: any
Rate limit: 10 requests / hour

The company must have a valid Smoobu PMS configuration saved (see PUT /api/apartamentos/pms). If no configuration exists or the API key is invalid, the endpoint returns 400.

Response

boolean

required

true

resultado

object

required

Sync summary.

Show resultado fields

creados

integer

Number of new apartments created.

actualizados

integer

Number of existing apartments updated.

total

integer

Total properties returned by Smoobu.

Example

curl -X POST https://api.example.com/api/apartamentos/sincronizacion/smoobu \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

{
  "ok": true,
  "resultado": {
    "creados": 3,
    "actualizados": 12,
    "total": 15
  }
}

POST /api/apartamentos/importacion

Imports apartments from an uploaded .xlsx file. Rows matched by id_externo or nombre are upserted; new rows are created. Row-level errors are returned as warnings and do not abort the import. Auth required: Yes | Role: any
Rate limit: 20 requests / hour

Request

Multipart form upload:

file

required

The .xlsx file to import. Must have a .xlsx extension. Maximum size is controlled by the MAX_CONTENT_LENGTH server setting (default 10 MB).

Response

boolean

required

true even when some rows had warnings.

resultado

object

required

Import summary (creados, actualizados, total).

warnings

array

Optional. List of per-row warning strings when individual rows were skipped.

Example

curl -X POST https://api.example.com/api/apartamentos/importacion \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -F "file=@apartamentos.xlsx"

{
  "ok": true,
  "resultado": {"creados": 5, "actualizados": 2, "total": 7},
  "warnings": ["Fila 3: nombre vacío, se omitió."]
}

POST /api/apartamentos/importacion/preview

Parses an .xlsx file and returns a preview of the rows that would be created or updated — nothing is written to the database. Use this before a real import to validate the file. Auth required: Yes | Role: any
Rate limit: 30 requests / hour

Request

file

required

The .xlsx file to preview. Must have a .xlsx extension.

Response

boolean

required

true

preview

array

required

List of parsed apartment rows that would be upserted.

Example

curl -X POST https://api.example.com/api/apartamentos/importacion/preview \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -F "file=@apartamentos.xlsx"

GET /api/apartamentos/pms

Reads the active PMS configuration for the company. The api_key is never returned — only metadata is exposed. Auth required: Yes | Role: any

Response

boolean

required

true

config

object | null

required

null if no PMS is configured.

Show config fields

proveedor

string

PMS provider slug: smoobu, beds24, hostaway, or cloudbeds.

endpoint

string | null

Custom endpoint override, if set.

Example

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

{
  "ok": true,
  "config": {
    "proveedor": "smoobu",
    "endpoint": null
  }
}

PUT /api/apartamentos/pms

Creates or replaces the PMS configuration for the company (upsert). The api_key is encrypted at rest. Auth required: Yes | Role: any

Request

proveedor

string

required

PMS provider. One of: smoobu, beds24, hostaway, cloudbeds.

api_key

string

required

API key for the PMS. 1–500 characters. Stored encrypted — never returned.

endpoint

string

Optional custom base URL for self-hosted PMS instances. Max 500 characters.

Response

boolean

required

true

config

object

required

Saved configuration (without api_key).

Example

curl -X PUT https://api.example.com/api/apartamentos/pms \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"proveedor": "smoobu", "api_key": "sk-live-abc123"}'

DELETE /api/apartamentos/pms

Removes the PMS configuration for the company. Subsequent sync attempts will fail until a new configuration is saved. Auth required: Yes | Role: any

Response

200 OK — {"ok": true} 404 Not Found — no PMS configuration exists.

Example

curl -X DELETE https://api.example.com/api/apartamentos/pms \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>"

Overview

Endpoints

Documentation Index

​GET /api/apartamentos

​Response

​Example

​GET /api/apartamentos/<id>

​Path Parameters

​Response

​Example

​POST /api/apartamentos

​Request

​Response

​Example

​PUT /api/apartamentos/<id>

​Path Parameters

​Request

​Response

​Example

​DELETE /api/apartamentos/<id>

​Path Parameters

​Response

​Example

​POST /api/apartamentos/sincronizacion/smoobu

​Response

​Example

​POST /api/apartamentos/importacion

​Request

​Response

​Example

​POST /api/apartamentos/importacion/preview

​Request

​Response

​Example

​GET /api/apartamentos/pms

​Response

​Example

​PUT /api/apartamentos/pms

​Request

​Response

​Example

​DELETE /api/apartamentos/pms

​Response

​Example

Build docs developers (and LLMs) love

GET /api/apartamentos

Response

Example

GET /api/apartamentos/<id>

Path Parameters

Response

Example

POST /api/apartamentos

Request

Response

Example

PUT /api/apartamentos/<id>

Path Parameters

Request

Response

Example

DELETE /api/apartamentos/<id>

Path Parameters

Response

Example

POST /api/apartamentos/sincronizacion/smoobu

Response

Example

POST /api/apartamentos/importacion

Request

Response

Example

POST /api/apartamentos/importacion/preview

Request

Response

Example

GET /api/apartamentos/pms

Response

Example

PUT /api/apartamentos/pms

Request

Response

Example

DELETE /api/apartamentos/pms

Response

Example