Referencia de la API

URL base y formato de respuesta

Cada ruta se sirve bajo el prefijo /api. En local la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que ambos frontends leen de NEXT_PUBLIC_API_BASE_URL (Variables de entorno). Las fotos se sirven fuera del prefijo, en /media/….

Las rutas del sitio web son públicas; las del panel necesitan el token bearer de un administrador, y la mayoría también un permiso. Los cuerpos de las peticiones son JSON, salvo las subidas de archivos. Cada respuesta llega en el mismo sobre:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es una frase breve que rellenan algunas escrituras, en el idioma de la petición, y está vacío en los demás casos. Los precios son números decimales en la moneda de la propiedad.

La comprobación de estado no necesita token:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

Cuando no se puede leer la base de datos, sigue respondiendo 200, con "status":"degraded" y "database":"down". La comprobación de estado de la imagen de Docker lee ese campo.

Errores

Un fallo mantiene el envoltorio, con success: false y el estado HTTP:

{
  "success": false,
  "data": null,
  "message": "…",
  "errors": { "email": ["…"] }
}

• message es una frase en el idioma de la petición.
• errors aparece en un fallo de validación, con los problemas por campo, indexados por la ruta que envió el cliente (como title.en). Un campo desconocido en un cuerpo se rechaza.
• Una ruta protegida sin token, o con uno caducado, responde 401; un token sin el permiso responde 403.
• Una petición que supera un límite responde 429.

Listas y paginación

{ "data": [ ], "page": 1, "limit": 12, "total": 15, "totalPages": 2 }

• Las propiedades, consultas y visitas se paginan con page y page_size: 12 por página por defecto en el sitio web (como máximo 24), 10 en el panel (como máximo 50). Las listas del panel también devuelven sus recuentos por estado.
• Los administradores, roles y ajustes se paginan con page y page_count.
• Salvo que la ruta tenga su propio orden, las filas llegan con la actualizada más recientemente primero, con el id como desempate, así que la paginación es estable.
• Los filtros de propiedades del sitio web se validan: un valor desconocido se rechaza con 400 en lugar de ignorarse, mientras que una clave que la API no lee se ignora, así que un enlace compartido con parámetros extra sigue funcionando.

Idioma

Envía Accept-Language: ar para mensajes en árabe; cualquier otro valor responde en inglés. Las propiedades y los barrios llevan ambos idiomas como { "en": "…", "ar": "…" } diga lo que diga la cabecera, y el cliente elige uno.

Inicio de sesión

1. 01

   Iniciar sesión como administrador

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@velra.example","password":"Admin@123"}'

   data.access_token es el token, con token_type Bearer y el administrador con sus roles y permisos. El token dura JWT_EXPIRATION, 7d por defecto, y expires_in informa de ese valor tal como está escrito. GET /api/auth/me devuelve al administrador con sesión iniciada con sus roles y permisos.
2. 02

   Llama a una ruta protegida

   TerminalCopiar

   curl http://localhost:8000/api/leads -H "Authorization: Bearer YOUR_TOKEN"

• Un correo desconocido y una contraseña incorrecta responden ambos 401 con el mismo mensaje.
• Diez inicios de sesión fallidos desde una misma dirección en 15 minutos responden 429 hasta que el fallo más antiguo cumple 15 minutos (RATE_LIMIT_LOGIN). Los inicios de sesión correctos no cuentan.
• No hay ruta de registro ni de cierre de sesión: las cuentas vienen de la carga inicial o de Gestión de administradores, y un cliente cierra la sesión olvidando su token.

Permisos

Las rutas del panel comprueban un permiso llamado <area>.<action>. Un administrador tiene todos los permisos de todos sus roles, y una ruta que nombra varios acepta cualquiera de ellos. Los 31 permisos y los dos roles de la carga inicial se listan en Administradores, roles y permisos.

Propiedades en el sitio web

Barrios y ajustes de la agencia

El formulario de contacto y las solicitudes de visita

• Un client_token repetido devuelve el recibo del primer envío en lugar de guardar un segundo.
• Un campo company rellenado se trata como un bot: la respuesta es igual y no se guarda nada.
• Una visita debe empezar con al menos una hora de antelación, en hora de Asia/Dubai; antes responde 400 con preferred_time_too_soon en preferred_at.
• Cada dirección puede enviar cinco de cada en diez minutos; la siguiente responde 429.

Gestionar propiedades

Consultas y visitas

Barrios y ajustes

Administradores y roles

Notificaciones y subidas

Una subida no tiene permiso propio: en qué se convierte el archivo lo comprueba la ruta que lo guarda. Las notificaciones se conservan 30 días.

Límites por dirección

Una petición que supera un límite responde 429. Las cuentas están en la memoria de la API, así que un reinicio las borra. Detrás de un proxy inverso, define TRUST_PROXY para que cada visitante se cuente en su propia dirección.

El asistente de IA y sus conversaciones

Estudio de amueblado

Servidor MCP

Actualizaciones en directo por WebSocket

Ruta del modo demostración