API e webhooks: integre o Ovigin ao seu sistema

Com a API você lê e escreve dados do Ovigin no seu sistema (ERP, gestão da associação). Com webhooks, o Ovigin avisa o seu sistema na hora em que algo acontece.

Onde está a documentação técnica

• Na própria tela Integrações, as seções "Como chamar a API", "O que o webhook envia" e "Conferindo a assinatura" trazem exemplos prontos para copiar.
• A lista de rotas e o formato das respostas seguem as mesmas rotas /v1 que o app e o site usam.
• O estado do serviço fica em Status dos sistemas.

Chaves de API

1. Em Integrações > Chaves de API, toque em Criar chave.
2. Dê um nome, escolha os escopos (só o que o seu sistema precisa) e a validade.
3. Copie a chave agora: ela só aparece uma vez. Tem o formato ov_live_<prefixo>_<segredo>.

Para revogar, use Revogar: quem usa a chave deixa de acessar na hora.

Escopos

Chamar a API

curl https://api.ovigin.com/v1/vehicles \
  -H "Authorization: Bearer ov_live_..."

As respostas vêm em JSON, com datas em ISO 8601. Erros trazem um código e uma mensagem. Rotas ligadas à pessoa (perfil, notificações) não aceitam chave de API.

Webhooks

1. Em Integrações > Webhooks, informe o endereço (URL) do seu sistema.
2. Escolha quais eventos receber ou todos.
3. Copie o segredo mostrado na criação: ele serve para conferir a assinatura.
4. Use Testar para enviar um evento de teste e veja o histórico de entregas.

O que o webhook envia

Um POST com JSON em snake_case:

{
  "id": "evt_8f3a1c",
  "event": "vehicle.exited_area",
  "tenant_id": "ten_42b7e0",
  "vehicle_id": "veh_91d2aa",
  "area_id": "area_5c01fe",
  "timestamp": "2026-09-29T12:30:00-03:00",
  "data": {
    "priority": "important",
    "title": "Fora da área",
    "message": "Veículo 038 saiu da área operacional."
  }
}

Os eventos incluem entrada e saída de área, movimento, ignição, excesso de velocidade, viagens, rastreador conectado ou sem sinal, bateria baixa, alimentação cortada, SOS e o ciclo das ocorrências (aberta, escalada, encerrada).

Conferir a assinatura

Todo aviso traz o cabeçalho X-Ovigin-Signature: t=<unix>,v1=<HMAC-SHA256 em hexadecimal>. O HMAC é calculado com o seu segredo sobre <t>.<corpo exato>. Recuse avisos com t mais antigo que 5 minutos (proteção contra reenvio).

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (age > 300) return false;
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Entrega e reenvio

Responda com 2xx rapidamente. Se o seu servidor falhar, o Ovigin tenta de novo, com espera crescente, até 8 vezes. Cada tentativa fica no histórico de entregas.

Enviar posições de aparelhos de terceiros

Quem tem uma plataforma de rastreamento própria pode mandar as posições para o Ovigin:

1. Crie uma chave com o escopo gateway:write.
2. Cadastre o aparelho com o modelo Integração de parceiro e um identificador externo.
3. Faça POST https://api.ovigin.com/gateway/v1/positions com Authorization: Bearer <chave> e o corpo { "positions": [ ... ] }. Cada leitura traz o identifier, a hora (at) e lat/lng. Aceita até 500 leituras por chamada.

Para aparelhos GT06 (como o J16), veja Configurar o J16 por SMS; para celulares, o endpoint OsmAnd (/gateway/osmand) é configurado pelo Traccar Client.