Webhooks e REST API

O HiLucy expõe uma REST API abrangente sob o namespace hilucy/v1. Esta API alimenta tanto os aplicativos frontend quanto as integrações de terceiros. Se você está construindo integrações personalizadas ou conectando sistemas externos, este guia cobre os principais grupos de endpoints, métodos de autenticação e padrões de webhook.

Grupos de Endpoints da API

A API é organizada em grupos funcionais, cada um lidando com um domínio específico:

Solicitações de Serviço e Operações

O maior grupo de endpoints lida com operações diárias da propriedade -- solicitações de serviço, contatos, listagens, reservas, clientes e gerenciamento de inventário. Mais de 30 rotas cobrem operações CRUD para todos os dados operacionais.

Chegadas

Endpoints para o fluxo de check-in do hóspede: resolução de tokens, correspondência de reservas, atualizações de hóspede e a ação de chegada idempotente que transita uma reserva para o status hospedado.

Hóspedes da Reserva

CRUD de hóspedes dentro de uma reserva, fluxos de convite e reivindicação de acompanhantes e endpoints de assinatura de termos. Esses alimentam o check-in online e os fluxos de reivindicação de acompanhantes.

Pagamento e Financeiro

• Autoridade de Pagamento -- Configuração multi-pagador: criar setup intents, confirmar métodos de pagamento, revogar autoridades e inicializar fólios por pagador
• Financeiro -- Consultas ao livro-razão, buscas de saldo, gerenciamento de regras de comissão e relatórios financeiros

Chat

Endpoint de streaming com Server-Sent Events (SSE) que atua como proxy de conversas para o assistente LucyAI. Usado pela interface de chat do portal do hóspede para respostas de IA em tempo real.

Autenticação

Login social (Google, Apple), renovação de tokens JWT, geração de magic links e verificação de magic links. Consulte a seção de Autenticação abaixo para detalhes.

Conectores e Pagamentos

Endpoints de integração unificados para gerenciar conexões de terceiros, além de fluxos de geração, aprovação e processamento de pagamentos para desembolsos a proprietários.

Portal WiFi

Endpoints do portal cativo para WiFi de hóspedes: gerenciamento de sessões, identificação de hóspedes, autorização e rastreamento de dispositivos.

Webhooks (Entrada)

O HiLucy recebe webhooks de vários serviços externos:

• Cloudbeds -- Eventos de criação/atualização/cancelamento de reservas que sincronizam reservas no HiLucy
• Stripe -- Confirmações de pagamento, disputas e eventos de pagamento
• Acuity Scheduling -- Reservas e cancelamentos de agendamentos
• WhatsApp (Meta) -- Atualizações de status de entrega de mensagens
• Monday.com -- Eventos de criação e mudança de status de tarefas

Cada endpoint de webhook de entrada valida a assinatura da solicitação antes de processar.

Autenticação

A API suporta múltiplos modos de autenticação dependendo do endpoint:

• JWT Bearer Token -- Método principal para solicitações autenticadas. Obtenha um token pelos endpoints de auth (login social ou magic link), depois inclua como Authorization: Bearer <token> nas solicitações seguintes.
• Token de Sessão de Chegada -- Auth baseada em token para o fluxo de check-in. Não requer conta de usuário; o token em si concede acesso limitado a uma reserva específica.
• Sessão WordPress -- Auth padrão por cookie WordPress para solicitações em contexto de administrador do dashboard.
• Público -- Alguns endpoints (como identificação do portal WiFi) são acessíveis publicamente sem autenticação.

Padrões de Integração de Webhooks

Se você está construindo um sistema que envia webhooks para o HiLucy ou consome dados de eventos do HiLucy:

• Webhooks de entrada são configurados por integração em Configurações > Integrações. Cada integração fornece sua URL de webhook e quaisquer chaves secretas necessárias.
• Idempotência -- Endpoints-chave (como a ação de chegada) são idempotentes, significando que entregas duplicadas de webhook não criarão mudanças de estado duplicadas.
• Validação de assinatura -- Todos os webhooks de entrada são verificados usando assinaturas HMAC ou validação específica da plataforma (ex.: assinaturas de webhook do Stripe, tokens de verificação da Meta).

Limites de Taxa e Melhores Práticas

• Endpoints autenticados têm limite de taxa por token de usuário. Evite polling; use webhooks para atualizações em tempo real sempre que possível.
• Sempre inclua tratamento de erros adequado para respostas 401 (token expirado), 403 (permissões insuficientes) e 429 (limite de taxa excedido).
• Para operações em massa, agrupe solicitações onde a API suportar em vez de fazer chamadas individuais por registro.

Dicas

• Use o endpoint de renovação JWT para renovar tokens antes que expirem em vez de reautenticar do zero
• Teste integrações de webhook contra o ambiente de desenvolvimento (dev.hilucy.com) antes de apontá-las para produção
• Verifique os indicadores de status de integração em Configurações se os eventos de webhook parecerem parar de chegar