Integração do Wialon com ERP: arquitetura e armadilhas

A maioria dos projetos de Wialon para ERP fracassa por motivos pouco óbvios: contratos de dados frouxos, propriedade indefinida e nenhuma rotina de conciliação. Este guia resume uma arquitetura que se sustenta sob carga operacional diária.

Comece pelos eventos de negócio, não pelos endpoints

O erro mais comum numa integração do Wialon com um ERP é abrir a documentação da Remote API e construir para fora a partir do catálogo de endpoints. O time inventaria cada chamada disponível — core/search_items, unit/get_messages, report/exec_report — e começa a extrair dados antes de alguém definir a que pergunta de negócio esses dados respondem. O resultado é um pipeline que sincroniza milhares de mensagens cruas por hora e ninguém na operação sabe o que fazer com elas.

O desenho por eventos inverte a ordem. Começa-se nomeando os eventos de negócio que importam: viagem concluída, geocerca cruzada, limite de marcha lenta ultrapassado, anomalia no nível de combustível, turno do motorista iniciado. Cada evento tem um consumidor claro no ERP — a atualização do status de uma ordem de transporte, um gatilho de folha de pagamento, uma ordem de serviço de manutenção. Só depois de nomear os eventos e mapeá-los para a ação que provocam é que se escolhem as chamadas da API do Wialon e os tipos de mensagem necessários para detectá-los.

Essa abordagem elimina uma classe inteira de desperdício. Em vez de puxar cada mensagem de cada unidade e filtrar depois, você assina os tipos de notificação específicos ou consulta os intervalos de mensagens específicos que produzem os eventos definidos. A camada de extração encolhe, a lógica de transformação fica explícita e o ERP recebe registros que ele de fato consegue processar. Quando alguém perguntar “por que o ERP não atualizou a viagem 4821?”, você consegue rastrear da definição do evento de negócio até a chamada exata e a janela de mensagens.

Defina a propriedade de cada campo antes de programar

Toda superfície de integração entre Wialon e ERP tem campos compartilhados: placa do veículo, atribuição de motorista, leitura de odômetro, capacidade do tanque. Quando os dois sistemas podem escrever no mesmo atributo, a divergência não é um risco: é uma certeza. Poucas semanas depois de entrar em produção você vai encontrar veículos com odômetros diferentes em cada sistema, motoristas atribuídos no Wialon e não no ERP, e capacidades de tanque que se separaram depois de uma edição manual de um lado.

A correção é uma matriz de propriedade de campos feita antes de qualquer linha de código. Para cada atributo compartilhado, um sistema é o mestre e o outro é o consumidor. Os metadados do veículo (chassi, placa, categoria) normalmente pertencem ao ERP, porque é lá que vivem compras e conformidade. Os campos de telemetria ao vivo (posição GPS, leituras de sensores, motorista atual por iButton) pertencem ao Wialon, porque é lá que o hardware entra. O odômetro é mais delicado: o Wialon o calcula do GPS ou do barramento CAN, mas o ERP pode ter um “último odômetro verificado” vindo de uma inspeção de manutenção. É preciso uma regra de precedência: use o valor do Wialon na operação diária, mas permita que o ERP o sobrescreva durante um evento de manutenção verificado.

Eventos que chegam atrasados criam um segundo problema de propriedade. Se um veículo conclui uma viagem às 23:50 mas a mensagem só chega ao pipeline à 01:15 do dia seguinte, de que data é essa viagem? Se o ERP fecha o lote diário à meia-noite, a viagem é contada duas vezes ou se perde por completo. Defina a precedência dos carimbos de tempo de forma explícita: o event_time do Wialon é que vale, o ingestion_time é metadado. Construa o sync para o ERP de modo que ele possa reabrir ou corrigir períodos anteriores quando chegarem eventos atrasados, em vez de descartá-los em silêncio.

• Monte uma planilha compartilhada mapeando cada campo ao seu sistema proprietário, à sua frequência de atualização e à sua regra de resolução de conflito.
• Estabeleça uma política de “vence quem escreve por último, com trilha de auditoria” para os campos que realmente precisam de atualização nos dois sentidos.
• Defina um período de tolerância para eventos atrasados — tipicamente de 4 a 6 horas — depois do qual a conciliação é manual.
• Rode consultas semanais de detecção de divergência que comparem os campos-chave entre os sistemas e sinalizem as diferenças para revisão.

Desenhe a camada de contrato de dados

Payloads JSON fracamente tipados passando da extração do Wialon para a ingestão do ERP são uma bomba-relógio. A primeira versão funciona bem porque quem escreveu o produtor escreveu também o consumidor. Seis meses depois alguém adiciona um campo, troca uma unidade de medida de litros para galões, ou renomeia “driver_id” para “operator_id”. O consumidor quebra às 2 da manhã e ninguém sabe por quê até o turno da manhã notar que faltam dados.

Um contrato de dados é uma definição de esquema versionada que produtor e consumidor aceitam. Ele especifica nomes de campos, tipos, unidades, se admite nulo e quais faixas de valores são válidas. Para um evento de viagem concluída, o contrato poderia definir trip_id como string obrigatória, distance_km como float obrigatório com duas casas decimais, e driver_code como string opcional que precisa obedecer a um formato definido. Qualquer payload que viole o contrato é rejeitado na ingestão, não absorvido em silêncio.

Versione o contrato de forma explícita. A versão 1.0 traz a distância em quilômetros; a 1.1 adiciona fuel_consumed_liters como campo opcional; a 2.0 transforma driver_code de opcional em obrigatório. Cada consumidor declara qual versão do contrato ele suporta. Quando sai uma mudança que quebra, rode as duas versões em paralelo durante uma janela de migração. Isso evita as falhas em cascata que assolam integrações onde “só adicionamos um campo e quebrou tudo”.

Novas tentativas e conciliação como recursos de primeira classe

Integrações em produção falham com frequência. Timeouts de rede, expiração do token de sessão do Wialon no meio de um lote, travas no banco do ERP durante o fechamento do mês, registros malformados de um rastreador recém-cadastrado: isso é condição normal de operação, não caso extremo. Se o seu pipeline trata qualquer falha como fatal e para, você vai ter buracos de dados na primeira semana.

Toda operação de escrita precisa ser idempotente. Use uma chave de deduplicação derivada do evento de negócio — por exemplo, a combinação de unit_id, tipo de evento e carimbo de tempo truncado no segundo. Quando uma nova tentativa entrega o mesmo evento duas vezes, o consumidor faz upsert em vez de insert. A cláusula ON CONFLICT do PostgreSQL resolve isso direto. Sem idempotência, as novas tentativas criam registros duplicados que inflam contagens de viagens, totais de combustível e todo relatório que vem depois.

As novas tentativas precisam de estrutura: backoff exponencial com jitter, começando em 1 segundo, dobrando para 2, 4, 8, e com teto em 60 segundos. O jitter — um deslocamento aleatório de até 30% do atraso — evita a estampida quando vários workers tentam de novo ao mesmo tempo depois de uma queda compartilhada. Passado um número configurável de tentativas (normalmente 5), mande o registro que falhou para uma fila de mensagens mortas e inspecione à mão, em vez de tentar para sempre.

A conciliação noturna é a rede que pega tudo o que as novas tentativas não pegaram. Rode uma consulta que cruze o log de extração com a tabela de destino do ERP pela chave de deduplicação. Todo registro presente no log e ausente no ERP é um buraco. Todo registro presente nos dois mas com valores diferentes é uma divergência. Publique esse relatório num canal compartilhado toda manhã. Se a quantidade de buracos passar do seu limite — nós usamos 0,1% do volume diário — dispare um alerta antes de o time de operações começar o turno.

Cuide do ciclo de vida da autenticação

A Remote API do Wialon usa tokens de sessão (o parâmetro “sid”) obtidos pelo endpoint token/login. Cada sessão tem um timeout de inatividade — tipicamente 5 minutos no Wialon Hosting, configurável no Wialon Local. Se o seu pipeline demora mais que isso para processar um lote sem fazer nenhuma chamada, a sessão expira em silêncio. A requisição seguinte devolve o código de erro 1 (sessão inválida) e, se o seu código não trata esse caso especificamente, ele registra um genérico “a requisição falhou” e segue em frente, deixando um buraco nos dados.

O erro de autenticação mais comum é fixar um único token de vida longa compartilhado por todos os workers. Quando esse token é revogado — porque um administrador o regenerou, ou porque o limite de tokens por usuário do Wialon foi atingido — todos os workers falham ao mesmo tempo. Em vez disso, implemente um pool de tokens: cada worker obtém a sua própria sessão via token/login usando um token de API compartilhado, administra o ciclo de vida dessa sessão e a renova antes do timeout de inatividade. Um heartbeat de fundo (chamando avl_evts a cada 60 segundos) mantém a sessão viva durante as pausas longas de processamento.

Em implantações multi-inquilino, em que você integra com várias contas Wialon, isole as credenciais por inquilino num gerenciador de segredos. Nunca guarde tokens da API do Wialon em variáveis de ambiente nem em arquivos de configuração versionados. Rotacione os tokens trimestralmente e a cada incidente de segurança. Registre todo evento de autenticação — login, renovação, expiração, falha — numa tabela de auditoria dedicada, para diagnosticar “por que o sync parou às 3 da manhã?” sem adivinhar.

Planeje a evolução do esquema

Os dois lados da integração vão mudar o esquema com o tempo. O Wialon adiciona propriedades de unidade, muda nomes de colunas de relatórios entre versões ou aposenta campos de mensagem. O time do ERP adiciona colunas, muda relações de chave estrangeira ou migra para um módulo novo. Se a sua integração é um mapeamento ponto a ponto rígido, cada mudança de qualquer um dos lados obriga a uma implantação sincronizada — e implantações sincronizadas entre times que liberam em calendários diferentes são ficção.

Construa camadas de transformação versionadas entre a extração crua do Wialon e o payload pronto para o ERP. Cada versão de transformação é uma função pura: dada a versão de esquema de entrada X, produza a versão de saída Y. Quando o Wialon muda a saída dele, você adiciona um adaptador de entrada novo sem tocar no anterior. Quando o ERP muda o que exige na entrada, você adiciona um adaptador de saída. O registro de transformações mapeia cada par de versões à função correta. As versões antigas continuam disponíveis para reprocessamento e depuração.

Use feature flags para liberar mudanças de esquema aos poucos. Leve a transformação nova para produção mas ative-a só para um subconjunto de veículos ou para uma única unidade de negócio. Compare as saídas antiga e nova durante 48 horas. Se a nova produz resultados idênticos nos campos compartilhados e preenche bem os campos novos, promova para 100%. Se diverge, você pegou um bug antes que ele atingisse a frota inteira. Assim some a ansiedade da “migração de uma vez só” que faz times adiarem por meses uma atualização necessária.

Checklist de prontidão operacional

Uma integração que funciona em desenvolvimento mas não tem estrutura operacional vai falhar em produção dentro do primeiro mês. Antes de entrar no ar, monte um painel de monitoramento que mostre quatro coisas de relance: o atraso do sync (tempo entre o evento no Wialon e a chegada do registro no ERP), a taxa de erro por categoria (autenticação, validação, transformação, rede), a vazão de registros (eventos por minuto, com tendência em 24 horas) e a quantidade de buracos de conciliação (atualizada toda noite).

Defina regras de alerta com limites que digam alguma coisa. Atraso de sync acima de 15 minutos: aviso; acima de 60 minutos: chamada crítica. Taxa de erro acima de 1% do volume horário: investigação. Buracos de conciliação acima de 0,1%: revisão antes do turno. Evite a fadiga de alertas ajustando os limites nas duas primeiras semanas de produção — comece conservador e aperte à medida que conhecer a linha de base.

Escreva runbooks para os três modos de falha mais comuns: expiração de sessão do Wialon (verificar o estado do token, forçar reautenticação, conferir o backfill), trava no banco do ERP (identificar a consulta que bloqueia, esperar ou escalar para o DBA, retomar o sync) e desencontro de esquema (identificar o campo que mudou, implantar a transformação atualizada, reprocessar o lote que falhou). Cada runbook precisa poder ser executado por um engenheiro de plantão que não construiu a integração. Se depende do desenvolvedor original para consertar, não é runbook: é conhecimento tribal, e vai falhar justamente quando essa pessoa estiver de férias.

• Atribua o plantão do pipeline de integração de forma explícita — ele não deveria cair no time de plataforma por padrão sem que ninguém tenha combinado.
• Faça um simulado antes de entrar no ar: provoque expiração de token, partição de rede e mudança de esquema para verificar que alertas, novas tentativas e runbooks funcionam.
• Mantenha um registro de incidentes com causa raiz, resolução e ação preventiva para cada queda de mais de 30 minutos.

As armadilhas acima são sobretudo acordos, não código: o que cada campo significa, de quem ele é e de quanto em quanto tempo ele muda. A gente trabalha isso como primeira fase de um projeto — veja serviços de integração do Wialon.