Configurações - API e Webhooks

O que é

A página API e Integrações concentra tudo o que um sistema externo precisa para conversar com o Viagilize da sua empresa: tokens de acesso à API REST v1, webhooks que notificam o sistema parceiro quando eventos importantes acontecem, logs de requisições e entregas, e os links para a documentação interativa e collections do Postman.

O usuário normalmente chega aqui quando o time técnico (ou um parceiro como ERP, CRM, plataforma de automação ou integrador) pede uma chave de API ou um endpoint de callback para receber confirmações de reserva, pagamentos e check-in em tempo real. Os quatro cards do topo mostram quantos tokens e webhooks estão ativos, o total de requisições nas últimas 24 horas e a taxa de sucesso, ajudando a diagnosticar rapidamente se uma integração está saudável.

Como usar

1. Vá em Configurações > API no sidebar (URL /admin/configuracoes/api).
2. Use a barra de abas Tokens de Acesso, Webhooks, Logs e Documentação para alternar entre as áreas. A aba selecionada fica salva no navegador (localStorage) para a próxima visita.

Criar um token de API

1. Na aba Tokens de Acesso, clique em Novo Token (botão azul no canto superior direito do cartão).
2. Preencha o modal Novo Token de API:
   • Nome do Token - descrição interna para identificar a integração (ex.: "Integração ERP"). Obrigatório.
   • Data de Expiração - opcional. Em branco significa token sem validade.
   • Permissões - escolha um ou mais escopos. Eles são agrupados por recurso: Excursões, Clientes, Passageiros, Reservas (Orders), Financeiro, Guias, Transportes, Veículos, Check-in e Webhooks. Cada recurso oferece variações read, write e em alguns casos delete. Use o toggle Marcar/Desmarcar Todos no topo para acelerar.
3. Clique em Criar Token. O modal Token Criado com Sucesso! aparece com o valor em texto puro - este é o único momento em que o token completo fica visível. Copie pelo botão de prancheta e guarde em local seguro antes de clicar em Entendi, Fechar.
4. Para usar o token, envie o header Authorization: Bearer SEU_TOKEN nas chamadas para a URL Base mostrada no rodapé azul da aba (https://{dominio-do-tenant}/api/v1).

Criar um webhook

1. Na aba Webhooks, clique em Novo Webhook (canto superior direito do cartão).
2. Preencha o modal:
   • Nome - rótulo interno (ex.: "Notificações ERP"). Obrigatório.
   • URL de Destino - endpoint HTTPS do sistema externo que receberá o POST. Obrigatório.
   • Eventos para Notificar - marque ao menos um. Eventos disponíveis hoje: reserva.criada, reserva.confirmada, reserva.cancelada, reserva.expirada, pagamento.criado, pagamento.confirmado, pagamento.estornado, checkin.realizado, checkout.realizado, excursao.publicada, excursao.cancelada, cliente.criado e contrato.assinado.
3. Clique em Criar Webhook. O secret é gerado automaticamente (prefixo whsec_) e fica armazenado no card do webhook, mostrado parcialmente; use o botão de prancheta para copiar o valor completo.
4. Cada disparo chega no seu endpoint com o header X-Viagilize-Signature contendo um HMAC SHA256 do corpo. Valide com hash_hmac('sha256', $payload, $secret) antes de aceitar o evento.

Acompanhar tokens e webhooks ativos

Cada token mostra status (Ativo, Expirado ou Revogado), data de criação, último uso e até 6 escopos com badge "+N mais" quando houver. Para webhooks, o card lista a URL, último disparo e os primeiros 4 eventos inscritos; se houver 5 ou mais falhas consecutivas, um badge vermelho N falhas consecutivas alerta para problemas no destino.

Consultar Logs

1. Abra a aba Logs.
2. Escolha a sub-aba Requisições (chamadas vindas da API) ou Webhooks (entregas saindo do Viagilize).
3. Aplique os filtros do formulário: Token, Status (Sucesso, Erro Cliente, Erro Servidor), Método (GET/POST/PUT/DELETE) e Período (24 horas, 48 horas, 7 dias ou 30 dias). Clique em Filtrar.

Documentação e collections

A aba Documentação traz o botão Abrir Documentação para o portal interativo (api.viagilize.com.br), além de downloads diretos da Postman Collection (viagilize-postman.json) e da especificação OpenAPI / Swagger (viagilize-openapi.json).

Casos especiais

Regenerar um token sem perder o cadastro

Use o ícone de seta circular na linha do token (tooltip "Regenerar Token"). O sistema confirma com o aviso "O token atual deixará de funcionar" - após confirmar, um novo valor é exibido uma única vez no modal Token Criado com Sucesso!. O ID e o nome são preservados, apenas a chave muda. Útil quando o segredo vazou ou quando há troca de fornecedor.

Revogar versus excluir token

Há duas operações destrutivas distintas:

• Revogar (desativar) (ícone de proibido) mantém o token visível para histórico mas desativado - não autentica mais nenhuma requisição.
• Excluir permanentemente (ícone de lixeira) remove o registro do banco. Use apenas se nunca mais precisar consultar o histórico daquele token.

Tokens revogados aparecem com badge cinza Revogado e perdem os botões de Regenerar/Revogar, restando só Excluir.

Testar um webhook antes de colocar em produção

Clique no ícone de avião de papel na linha do webhook (tooltip "Testar Webhook"). O Viagilize envia um POST de teste para a URL cadastrada e exibe o toast "Webhook de teste enviado! Verifique os logs.". O resultado aparece em Logs > Webhooks.

Regenerar o secret de um webhook

Use o ícone de seta circular ao lado de Editar (tooltip "Regenerar Secret"). A confirmação avisa que será preciso atualizar a validação HMAC no sistema de destino antes do próximo disparo.

Token sem expiração

Deixar Data de Expiração em branco mantém o token válido por tempo indeterminado. Recomenda-se definir expiração para integrações de terceiros e rotacionar periodicamente.

Erros comuns e como resolver

• "Selecione pelo menos uma permissão" - Causa: o formulário de token foi enviado sem nenhum escopo marcado. Solução: marque ao menos um escopo (ex.: excursoes:read) ou use Marcar/Desmarcar Todos.
• "Selecione pelo menos um evento" - Causa: o formulário de webhook foi enviado sem nenhum evento marcado. Solução: marque ao menos um evento como reserva.criada antes de salvar.
• Badge vermelho "N falhas consecutivas" no card do webhook - Causa: o endpoint de destino retornou erro nas últimas N entregas. Solução: confirme se a URL está acessível em HTTPS, verifique os logs de Logs > Webhooks e use Testar Webhook após corrigir.
• Token aparece como "Expirado" - Causa: a data informada em Data de Expiração foi alcançada. Solução: edite o token e ajuste a data, ou crie um novo token e atualize o sistema externo.
• "Erro ao processar requisição" no toast - Causa: falha de rede ou erro inesperado no servidor. Solução: recarregue a página e tente novamente; se persistir, consulte os logs do sistema.

Onde encontrar

• URL: /admin/configuracoes/api
• Caminho no menu: Configurações > API
• Permissão necessária: ver as configurações para acessar a página, editar as configurações para criar, editar, regenerar, revogar, excluir e testar
• Módulo necessário: nenhum

Veja também

• Integrações de marketing (Google Analytics e Facebook Pixel)
• Domínio personalizado