Configurações - Logs da API e Webhooks

O que é

A página Logs de Requisições mostra o histórico das chamadas que chegaram na API REST v1 da sua empresa e o resultado de cada entrega de webhook disparada pelo Viagilize. Cada linha registra data e hora, token usado, método HTTP, endpoint chamado, código de status e tempo de resposta em milissegundos, permitindo identificar rapidamente integrações instáveis, parceiros consumindo demais ou tokens vazados.

O usuário chega aqui quando precisa investigar um caso técnico: um parceiro reclamou que o webhook não chegou, um ERP está recebendo 401 ou 403, a equipe quer saber qual token disparou determinada ação ou medir o impacto de uma nova integração nas últimas horas. A página é o complemento de auditoria da configuração feita em Configurações > API, e por padrão mostra apenas as últimas 24 horas para manter a tabela leve.

Como usar

1. Vá em Configurações > API no sidebar.
2. Abra a aba Logs e clique em Requisições para o histórico de chamadas recebidas, ou acesse direto pela URL /admin/configuracoes/api/logs/requests.
3. Ajuste os filtros do formulário no topo:
   • Token - restringe a uma chave específica. Útil para isolar o tráfego de um parceiro.
   • Status - Sucesso (faixa 200-299), Erro Cliente (400-499, normalmente autenticação ou payload inválido) ou Erro Servidor (500+, falha interna).
   • Método - filtra por verbo HTTP: GET, POST, PUT ou DELETE.
   • Período - 24 horas (padrão), 48 horas, 7 dias ou 30 dias. Janelas maiores podem demorar mais para carregar.
4. Clique em Filtrar. A tabela recarrega com paginação de 50 registros por página.
5. Leia a tabela:
   • Data/Hora vem no formato dd/mm HH:MM:SS.
   • Método ganha badge colorido (GET verde, POST azul, PUT âmbar, DELETE vermelho).
   • Endpoint é truncado em 50 caracteres para manter a linha legível.
   • Status colore o código (verde 2xx, âmbar 4xx, vermelho 5xx).
   • Tempo é exibido em milissegundos, útil para identificar endpoints lentos.

Casos especiais

Logs de webhooks (entregas saindo do Viagilize)

A rota /admin/configuracoes/api/logs/webhooks retorna a lista de entregas em formato JSON e é consumida internamente pela aba Logs > Webhooks dentro de /admin/configuracoes/api. Cada registro traz o evento disparado (ex.: reserva.criada), o payload enviado, o response_code que o destino devolveu, o status (success, failed ou pending), o número de attempts (tentativas com retry automático) e a error_message quando a entrega falhou. Para investigar por que um sistema externo não recebeu a notificação, abra a aba Webhooks na página principal de API e filtre pelo webhook específico.

Estatísticas agregadas para painel

A rota /admin/configuracoes/api/stats devolve em JSON os contadores agregados das últimas N horas: total de requisições, contagem por status, taxa de sucesso, ranking dos 10 endpoints mais chamados (com tempo médio), agrupamento por token (com last_used) e série horária para gráfico. É usada pelos cards e gráficos da aba Logs dentro de /admin/configuracoes/api, mas pode ser consultada direto via ?hours=168 quando quiser exportar números brutos.

Auditar uma chave específica

Quando suspeitar de uso indevido de um token, selecione-o no filtro Token, expanda o Período para 30 dias e marque Status como Sucesso. A combinação revela todos os endpoints acessados, em que horário e a partir de qual padrão de uso. Se algo parecer fora do esperado, volte para Configurações > API e use Revogar (desativar) ou Regenerar Token na linha correspondente.

Tabela vazia com período curto

Se a mensagem Nenhum log encontrado para o período selecionado aparecer, expanda o filtro Período para 7 dias ou 30 dias antes de concluir que a integração está parada - pode ser apenas baixa frequência de chamadas.

Retenção de 30 dias

Os métodos ApiRequestLog::cleanOldLogs() e ApiWebhookLog::cleanOldLogs() removem registros com mais de 30 dias. Por isso o filtro Período termina nesse limite e logs antigos não ficam disponíveis para consulta retroativa - exporte ou copie o que precisar enquanto ainda estiver dentro da janela.

Erros comuns e como resolver

• "Nenhum log encontrado para o período selecionado" - Causa: nenhuma requisição combina com os filtros aplicados. Solução: amplie o Período para 7 ou 30 dias, limpe o filtro Token e revise se o sistema externo realmente está chamando a URL Base correta (https://{dominio-do-tenant}/api/v1).
• Muitas linhas com badge âmbar 4xx - Causa: payload inválido, token revogado ou sem escopo necessário. Solução: filtre por Status = Erro Cliente, abra a documentação da API para o endpoint listado e confira os escopos do token em Configurações > API > Tokens de Acesso.
• Muitas linhas com badge vermelho 5xx - Causa: falha interna do Viagilize ou timeout downstream. Solução: anote data, hora e endpoint, e acione o suporte para investigação. Não há ação corretiva possível pelo painel.
• Webhook com status = failed e attempts > 1 - Causa: o destino devolveu erro ou ficou indisponível nas tentativas de retry. Solução: vá em Configurações > API > Webhooks, confira a URL cadastrada, valide o certificado HTTPS e use Testar Webhook após corrigir o destino.
• token aparece como N/A em uma linha - Causa: o token foi excluído permanentemente após a requisição ter sido registrada. Solução: o histórico fica preservado mas sem rótulo; prefira Revogar (desativar) em vez de excluir tokens que ainda precisem ser auditados.

Onde encontrar

• URL: /admin/configuracoes/api/logs/requests
• Caminho no menu: Configurações > API > aba Logs
• Permissão necessária: ver as configurações
• Módulo necessário: nenhum

Veja também

• API e Webhooks