Integrações

No Painel Cobli, a área de integrações pode reunir três frentes principais: Aplicativos, Chaves de API e Webhooks. Cada uma atende um tipo de necessidade diferente, desde conectores prontos até automações em tempo real.

Veja o fluxo completo

O vídeo abaixo mostra o caminho recomendado para localizar a área, aplicar o recorte principal e revisar o resultado com segurança.

Pré-requisitos

• Ter permissão para acessar a área administrativa de integrações
• Saber qual sistema externo será conectado
• Definir se a necessidade é consultar dados, automatizar processos ou receber eventos em tempo real
• Combinar com a pessoa ou equipe que mantém o sistema externo antes de alterar chaves, URLs ou webhooks em uso

Passo a passo

Como criar uma chave de API

A criação de uma chave de API acontece dentro de um painel lateral, em etapas simples. Após gerar a chave, ela não poderá ser visualizada novamente — copie imediatamente antes de fechar.

1. Acesse Chaves de API: no menu lateral, na seção Configurações, clique em Integrações e depois em Chaves de API.
2. Abra o formulário: clique em Nova chave para abrir o painel lateral de criação.
3. Defina um nome: insira um nome descritivo para identificar qual sistema vai usar essa chave (máximo 30 caracteres). Use algo como Integração ERP ou Relatório BI para facilitar a identificação depois.
4. Gere a chave: clique em Gerar chave para criar o código.
5. Copie e salve imediatamente: clique em Copiar chave e guarde o código em local seguro — um gerenciador de senhas ou a configuração do sistema que vai usá-la. Após fechar este painel, o código não poderá ser visualizado novamente.
6. Conclua: clique em Concluir para finalizar.

Como identificar uma chave inválida

Na tabela de chaves de API, uma chave revogada por desativação do usuário criador aparece com o selo vermelho Chave inválida ao lado do nome. Passe o cursor sobre o selo para ver a explicação: a chave foi invalidada porque o usuário que a criou foi desativado da frota.

Na coluna Criado por, o texto Usuário desativado aparece abaixo do e-mail, reforçando qual conta causou a revogação.

Quando uma integração parar de funcionar, comece por essa verificação: se a chave estiver marcada como inválida, gere uma nova com um usuário ativo — de preferência um usuário dedicado a integrações — e atualize o sistema externo.

Como criar um webhook

A criação de um webhook acontece em etapas, sempre nesta ordem. Você só avança para a próxima quando a etapa atual estiver preenchida corretamente:

1. Cadastrar informações: nome, URL, chave e eventos que vão acionar o envio.
2. Intervalos: ajuste da frequência de envio por tipo de evento (opcional).
3. Cabeçalhos: cabeçalhos personalizados (opcional).
4. Teste: o Painel Cobli envia uma requisição de teste para a URL configurada e exibe o resultado antes de concluir.

Campos importantes em Webhooks

Ao criar ou editar um webhook, confira estes pontos antes de concluir:

• Nome (obrigatório): use um nome que indique o sistema de destino ou o processo atendido. Permite até 90 caracteres.
• Payload URL (obrigatório): precisa ser uma URL segura, com protocolo https, pronta para receber requisições da Cobli.
• Chave pública (obrigatória): usada para apoiar a validação de autenticidade da mensagem.
• Eventos (obrigatório): selecione pelo menos um evento para acionar o envio. A tela separa os eventos por seções, como Telemetria e Câmera. As seções e os eventos disponíveis podem variar conforme os recursos contratados pela sua frota.
• Cabeçalhos personalizados (opcional): use apenas quando o sistema de destino exigir um cabeçalho específico.
• Intervalos de envio (opcional): controle a frequência de disparos por tipo de evento, para evitar excesso de notificações.

Intervalos de envio por tipo de evento

Na etapa Intervalos, cada tipo de evento selecionado pode manter o intervalo padrão ou ser personalizado. Ao personalizar, há dois modos:

• Intervalo mínimo: envia no máximo uma notificação a cada intervalo definido. O tempo mínimo é de 10 segundos.
• Acúmulo mínimo: envia somente quando houver um número mínimo de ocorrências dentro do intervalo. A quantidade mínima de ocorrências é 2.

Teste do webhook

Valide a URL antes de depender do envio em produção. Na última etapa da criação, o Painel Cobli envia uma requisição de teste para o endereço configurado e exibe o resultado imediatamente.

Erros comuns no teste de webhook

Se o teste falhar, o painel exibe uma mensagem com o código de erro retornado pelo servidor de destino. Use a tabela abaixo para identificar a causa e o que fazer:

Quando usar cada opção

• Use Aplicativos quando quiser uma integração mais guiada, com menos configuração técnica
• Use Chaves de API quando sua empresa precisa consultar ou enviar dados por integração própria
• Use Webhooks quando o sistema externo precisa ser avisado automaticamente sobre eventos, como entrada ou saída de Local de Interesse

Dicas

Veja também