Webhooks y REST API

HiLucy expone una REST API completa bajo el namespace hilucy/v1. Esta API alimenta tanto las aplicaciones frontend como las integraciones de terceros. Si estás construyendo integraciones personalizadas o conectando sistemas externos, esta guía cubre los grupos de endpoints principales, métodos de autenticación y patrones de webhook.

Grupos de Endpoints de la API

La API está organizada en grupos funcionales, cada uno gestionando un dominio específico:

Solicitudes de Servicio y Operaciones

El grupo de endpoints más grande maneja las operaciones diarias de la propiedad -- solicitudes de servicio, contactos, listados, reservas, clientes y gestión de inventario. Más de 30 rutas cubren operaciones CRUD para todos los datos operacionales.

Llegadas

Endpoints para el flujo de check-in del huésped: resolución de tokens, coincidencia de reservas, actualizaciones de huésped y la acción de llegada idempotente que transiciona una reserva al estado en casa.

Huéspedes de Reserva

CRUD de huéspedes dentro de una reserva, flujos de invitación y reclamación de acompañantes y endpoints de firma de términos. Estos alimentan el check-in online y los flujos de reclamación de acompañantes.

Pago y Finanzas

• Autoridad de Pago -- Configuración multi-pagador: crear setup intents, confirmar métodos de pago, revocar autoridades y inicializar folios por pagador
• Financiero -- Consultas al libro mayor, búsquedas de saldo, gestión de reglas de comisión e informes financieros

Chat

Endpoint de streaming con Server-Sent Events (SSE) que actúa como proxy de conversaciones hacia el asistente LucyAI. Usado por la interfaz de chat del portal del huésped para respuestas de IA en tiempo real.

Autenticación

Login social (Google, Apple), renovación de tokens JWT, generación de magic links y verificación de magic links. Consulta la sección de Autenticación a continuación para detalles.

Conectores y Pagos a Propietarios

Endpoints de integración unificados para gestionar conexiones de terceros, además de flujos de generación, aprobación y procesamiento de pagos para desembolsos a propietarios.

Portal WiFi

Endpoints del portal cautivo para WiFi de huéspedes: gestión de sesiones, identificación de huéspedes, autorización y seguimiento de dispositivos.

Webhooks (Entrantes)

HiLucy recibe webhooks de varios servicios externos:

• Cloudbeds -- Eventos de creación/actualización/cancelación de reservas que sincronizan reservas en HiLucy
• Stripe -- Confirmaciones de pago, disputas y eventos de pago
• Acuity Scheduling -- Reservas y cancelaciones de citas
• WhatsApp (Meta) -- Actualizaciones de estado de entrega de mensajes
• Monday.com -- Eventos de creación y cambio de estado de tareas

Cada endpoint de webhook entrante valida la firma de la solicitud antes de procesarla.

Autenticación

La API soporta múltiples modos de autenticación dependiendo del endpoint:

• JWT Bearer Token -- Método principal para solicitudes autenticadas. Obtén un token a través de los endpoints de auth (login social o magic link), luego inclúyelo como Authorization: Bearer <token> en las solicitudes siguientes.
• Token de Sesión de Llegada -- Auth basada en token para el flujo de check-in. No requiere cuenta de usuario; el token en sí otorga acceso limitado a una reserva específica.
• Sesión WordPress -- Auth estándar por cookie de WordPress para solicitudes en contexto de administrador desde el dashboard.
• Público -- Algunos endpoints (como la identificación del portal WiFi) son accesibles públicamente sin autenticación.

Patrones de Integración de Webhooks

Si estás construyendo un sistema que envía webhooks a HiLucy o consume datos de eventos de HiLucy:

• Webhooks entrantes se configuran por integración en Configuración > Integraciones. Cada integración proporciona su URL de webhook y las claves secretas requeridas.
• Idempotencia -- Los endpoints clave (como la acción de llegada) son idempotentes, lo que significa que entregas duplicadas de webhook no crearán cambios de estado duplicados.
• Validación de firma -- Todos los webhooks entrantes se verifican usando firmas HMAC o validación específica de la plataforma (ej., firmas de webhook de Stripe, tokens de verificación de Meta).

Límites de Tasa y Mejores Prácticas

• Los endpoints autenticados tienen límite de tasa por token de usuario. Evita el polling; usa webhooks para actualizaciones en tiempo real donde sea posible.
• Siempre incluye manejo de errores apropiado para respuestas 401 (token expirado), 403 (permisos insuficientes) y 429 (límite de tasa excedido).
• Para operaciones masivas, agrupa solicitudes donde la API lo soporte en lugar de hacer llamadas individuales por registro.

Consejos

• Usa el endpoint de renovación JWT para renovar tokens antes de que expiren en lugar de re-autenticarte desde cero
• Prueba las integraciones de webhook contra el entorno de desarrollo (dev.hilucy.com) antes de apuntarlas a producción
• Verifica los indicadores de estado de integración en Configuración si los eventos de webhook parecen dejar de llegar