Profile and Integrations API — User and Company Settings

The Profile API gives authenticated users access to their own account details and exposes company-level integration settings. Reading is available to all roles; writing integration settings is restricted to admin. Password changes apply only to the currently authenticated user and require knowledge of the existing password.

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

GET /api/perfil

Returns the profile data of the currently authenticated user: email, role, and company information. Auth required: Yes | Role: any

Response

boolean

required

true

data

object

required

User profile object.

Show Profile fields

string

User UUID.

string

User’s email address.

rol

string

User’s role: admin or operativo.

empresa_id

string

UUID of the user’s company.

empresa_nombre

string

Display name of the company.

Example

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

{
  "ok": true,
  "data": {
    "id": "11111111-0000-4000-a000-000000000001",
    "email": "admin@miempresa.com",
    "rol": "admin",
    "empresa_id": "aaaaaaaa-0000-4000-a000-000000000001",
    "empresa_nombre": "Apartamentos Sol"
  }
}

PUT /api/perfil/password

Changes the password for the currently authenticated user. Requires the current password for verification. Auth required: Yes | Role: any

Request

password_actual

string

required

The user’s current password.

password_nuevo

string

required

The new password to set. Must meet the application’s minimum strength requirements.

Response

200 OK — {"ok": true} 422 Unprocessable Entity — current password is incorrect or new password does not meet strength requirements.

Example

curl -X PUT https://api.example.com/api/perfil/password \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"password_actual": "oldPass123!", "password_nuevo": "newSecurePass456!"}'

GET /api/perfil/integraciones

Returns the integration status for the authenticated user’s company — PMS connectivity, AI configuration, and whether each service is currently active. Auth required: Yes | Role: any

Response

boolean

required

true

data

object

required

Integration status summary.

Show Integration fields

pms

object | null

PMS configuration summary (proveedor, endpoint) or null if not set.

object | null

AI configuration summary (proveedor, modelo, configurado) or null if not set.

Example

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

{
  "ok": true,
  "data": {
    "pms": {"proveedor": "smoobu", "endpoint": null},
    "ia": {"proveedor": "openai", "modelo": "gpt-4o", "configurado": true}
  }
}

PUT /api/perfil/integraciones/pms

Creates or replaces the PMS integration for the company. The API key is encrypted at rest and never returned in read endpoints. Auth required: Yes | Role: admin

Request

proveedor

string

required

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

api_key

string

required

API key for the PMS. Stored encrypted.

endpoint

string

Optional custom base URL for self-hosted or white-labelled PMS instances.

Response

200 OK — {"ok": true} 422 Unprocessable Entity — validation errors.

Example

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

PUT /api/perfil/integraciones/ia

Configures a BYOK (Bring Your Own Key) AI integration for the company. Once set, AI endpoints use this key instead of the platform’s shared quota. Auth required: Yes | Role: admin

Request

proveedor

string

required

AI provider (e.g., openai).

api_key

string

required

API key for the AI provider. Stored encrypted.

modelo

string

required

Model identifier to use (e.g., gpt-4o, gpt-3.5-turbo).

Response

200 OK — {"ok": true} 422 Unprocessable Entity — validation errors.

Example

curl -X PUT https://api.example.com/api/perfil/integraciones/ia \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"proveedor": "openai", "api_key": "sk-openai-xyz789", "modelo": "gpt-4o"}'

DELETE /api/perfil/integraciones/pms

Removes the PMS integration for the company. After deletion, PMS-dependent features (heat map, contact sync, apartment sync) will be unavailable until a new integration is saved. Auth required: Yes | Role: admin

Response

200 OK — {"ok": true}

Example

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

DELETE /api/perfil/integraciones/ia

Removes the BYOK AI integration for the company. After deletion, AI endpoints revert to the platform’s shared quota. Auth required: Yes | Role: admin

Response

200 OK — {"ok": true}

Example

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

GET /api/perfil/xlsx-apartamentos

Returns the XLSX column mapping used when importing apartments from a spreadsheet. Column letters correspond to Excel column headers (e.g., A, B). Auth required: Yes | Role: any

Response

boolean

required

true

config

object | null

required

Column mapping, or null if not yet configured.

Show Config fields

col_nombre

string

Column letter for the apartment name.

col_id_externo

string | null

Column letter for the external PMS ID, or null.

col_direccion

string | null

Column letter for the address, or null.

col_ciudad

string | null

Column letter for the city, or null.

Example

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

{
  "ok": true,
  "config": {
    "col_nombre": "B",
    "col_id_externo": "A",
    "col_direccion": "C",
    "col_ciudad": "D"
  }
}

PUT /api/perfil/xlsx-apartamentos

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

Request

col_nombre

string

required

Excel column letter for apartment names.

col_id_externo

string | null

Excel column letter for the external PMS ID, or null to skip.

col_direccion

string | null

Excel column letter for the address, or null to skip.

col_ciudad

string | null

Excel column letter for the city, or null to skip.

Response

200 OK — {"ok": true}

Example

curl -X PUT https://api.example.com/api/perfil/xlsx-apartamentos \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{"col_nombre": "B", "col_id_externo": "A", "col_direccion": "C", "col_ciudad": "D"}'

GET /api/perfil/notificaciones-tardio-config

Returns the company’s late check-in notification configuration: the cut-off hour and any XLSX column mappings used by the notification parser. Auth required: Yes | Role: any

Response

boolean

required

true

config

object

required

Late notification configuration.

Show Config fields

hora_corte

string

Time in HH:MM format (24h). Arrivals after this time are flagged as late. Default: "20:00".

col_apartamento

string | null

Excel column letter for the apartment identifier.

col_hora_llegada

string | null

Excel column letter for the expected arrival time.

col_nombre_huesped

string | null

Excel column letter for the guest name.

Example

curl https://api.example.com/api/perfil/notificaciones-tardio-config \
  -H "Authorization: Bearer $TOKEN"

{
  "ok": true,
  "config": {
    "hora_corte": "20:00",
    "col_apartamento": "B",
    "col_hora_llegada": "E",
    "col_nombre_huesped": "C"
  }
}

PUT /api/perfil/notificaciones-tardio-config

Saves the late check-in notification configuration for the company. Controls when a check-in is considered “late” and which XLSX columns contain the relevant data. Auth required: Yes | Role: admin

Request

hora_corte

string

required

Cut-off time in HH:MM (24h) format. Arrivals after this time are flagged. Example: "20:00".

col_apartamento

string | null

Excel column letter for the apartment column in the check-in XLSX.

col_hora_llegada

string | null

Excel column letter for the arrival time column.

col_nombre_huesped

string | null

Excel column letter for the guest name column.

Response

200 OK — {"ok": true} 422 Unprocessable Entity — validation errors (e.g., invalid time format).

Example

curl -X PUT https://api.example.com/api/perfil/notificaciones-tardio-config \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "hora_corte": "21:00",
    "col_apartamento": "B",
    "col_hora_llegada": "E",
    "col_nombre_huesped": "C"
  }'

Overview

Endpoints

Documentation Index

​GET /api/perfil

​Response

​Example

​PUT /api/perfil/password

​Request

​Response

​Example

​GET /api/perfil/integraciones

​Response

​Example

​PUT /api/perfil/integraciones/pms

​Request

​Response

​Example

​PUT /api/perfil/integraciones/ia

​Request

​Response

​Example

​DELETE /api/perfil/integraciones/pms

​Response

​Example

​DELETE /api/perfil/integraciones/ia

​Response

​Example

​GET /api/perfil/xlsx-apartamentos

​Response

​Example

​PUT /api/perfil/xlsx-apartamentos

​Request

​Response

​Example

​GET /api/perfil/notificaciones-tardio-config

​Response

​Example

​PUT /api/perfil/notificaciones-tardio-config

​Request

​Response

​Example

Build docs developers (and LLMs) love

GET /api/perfil

Response

Example

PUT /api/perfil/password

Request

Response

Example

GET /api/perfil/integraciones

Response

Example

PUT /api/perfil/integraciones/pms

Request

Response

Example

PUT /api/perfil/integraciones/ia

Request

Response

Example

DELETE /api/perfil/integraciones/pms

Response

Example

DELETE /api/perfil/integraciones/ia

Response

Example

GET /api/perfil/xlsx-apartamentos

Response

Example

PUT /api/perfil/xlsx-apartamentos

Request

Response

Example

GET /api/perfil/notificaciones-tardio-config

Response

Example

PUT /api/perfil/notificaciones-tardio-config

Request

Response

Example