Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven 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 leen ambos frontends en NEXT_PUBLIC_API_BASE_URL (Variables de entorno). Las fotografías 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 corta que rellenan algunas escrituras, en el idioma de la petición, y está vacía en los demás casos. Los precios son dólares estadounidenses enteros, y las fechas son días de calendario de la empresa escritos YYYY-MM-DD.

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 conserva el envoltorio, con success: false y el estado HTTP. message es una frase en el idioma de la petición, code la clave sin traducir que hay detrás, y un rechazo que nombra algo añade en details los valores que hay detrás de su frase:

{
  "success": false,
  "data": null,
  "message": "Booking B0021 already holds some of these nights.",
  "code": "dates_taken",
  "details": { "held_by": "booking", "reference": "B0021" }
}

Un cuerpo que rechaza la validación lleva code: "validation_failed" y errors, con la clave de cada campo por su nombre completo:

{
  "success": false,
  "data": null,
  "message": "guest_email must be an email",
  "errors": { "guest_email": ["guest_email must be an email"] },
  "code": "validation_failed"
}

• Ramifica según code, nunca según la frase, que cambia con el idioma. Los rechazos de reservas y de disponibilidad llevan códigos como dates_taken, min_nights, capacity, cancellation_window_passed, awaiting_payment y payment_method_unavailable, y un límite rate_limited.
• errors aparece en un fallo de validación, con los problemas bajo el nombre del campo tal como lo escribió la petición (check_in, guest_email). 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.
• Las noches ya retenidas responden 409, un paso de reserva desde el estado equivocado 422, y una petición por encima de un límite 429.

Listas y paginación

{ "data": [ ], "page": 1, "page_size": 6, "total": 12, "total_pages": 2 }

• Los alojamientos, las reservas, las consultas y las reseñas se paginan con page y page_size: 6 alojamientos por página en el sitio web (24 como máximo), 20 en el panel (50 como máximo), 10 reservas y 20 consultas (50 como máximo cada una), 8 reseñas. Las listas del panel también devuelven counts por estado.
• Los administradores, los roles y los ajustes se paginan con page y page_count (los ajustes también aceptan page_size), 10 por defecto y 100 como máximo, y responden { data, page, limit, total, totalPages }.
• Los filtros de alojamientos 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 los mensajes en árabe; cualquier otro valor responde en inglés. Los alojamientos, los destinos y las preguntas de la página de inicio llevan ambos idiomas como { "en": "…", "ar": "…" } sea cual sea 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@hollina.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/bookings/manage -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.
• Los huéspedes no tienen cuentas. Las rutas de reserva de un huésped aceptan el access_token de la reserva como ?token=, o el correo electrónico con el que se hizo como ?email=; un par incorrecto responde 404.

Permisos

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

Alojamientos en el sitio web

Destinos, preguntas y ajustes de la empresa

Reservas

• Un client_token repetido devuelve el recibo de la primera reserva en lugar de hacer una segunda, y un campo company relleno se trata como un bot: la respuesta parece la misma, y no se guarda nada.
• Un payment_method que GET /api/payments/methods no lista (PayPal con solo Stripe configurado, tarjeta con solo PayPal, pago a la llegada con su ajuste desactivado) responde 422 con payment_method_unavailable, antes de que se escriba nada.
• Las noches se comprueban cuando se escribe la reserva: las noches retenidas responden 409 con dates_taken, y el mínimo de un alojamiento, su capacidad o un check-in pasado 422 con el motivo.
• Un método alojado responde pending con un redirect_url a Stripe o PayPal; la reserva solo la confirma el webhook del procesador o la captura de PayPal.

Preguntas al anfitrión

• Un client_token repetido devuelve el primer envío en lugar de guardar un segundo, y un campo company relleno se trata como un bot.
• Cada dirección puede enviar cinco reservas, cinco preguntas y cinco reseñas en diez minutos; la siguiente responde 429.

Gestión de alojamientos

El calendario y las fechas bloqueadas

Reservas, consultas y reseñas

Destinos, preguntas 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

Servidor MCP

Actualizaciones en directo por WebSocket

Rutas del modo demostración