API, webhook e polling: como sistemas de logística conversam de verdade

Pergunte a qualquer fornecedor de sistema se ele integra com o seu. A resposta vem rápida: “temos API”. A frase virou selo de qualidade no mercado de logística, mas sozinha não diz quase nada.

“Ter API” pode significar uma integração de verdade, que atualiza status em segundos, ou um PDF de documentação que ninguém nunca testou. Para o gestor de transportadora, a diferença entre uma coisa e outra costuma aparecer depois do contrato assinado, quando trocar de fornecedor já é caro.

Este artigo explica, sem uma linha de código, como sistemas de logística conversam de verdade: API, polling, webhook, tempo real e lote. O objetivo é você sair de qualquer reunião de integração sabendo o que perguntar e reconhecendo resposta evasiva na hora.

API é o balcão: quem precisa do dado vai lá e pede

Uma API (interface de programação de aplicações) é o balcão de atendimento de um sistema. Outro sistema chega, se identifica e faz um pedido objetivo: “me dê o status do conhecimento 4581” ou “crie uma coleta para amanhã às 8h”. O balcão responde na hora, num formato padronizado que máquinas entendem.

O padrão mais comum hoje é a API REST, que funciona sobre a mesma infraestrutura da web. Cada tipo de informação tem um endereço próprio (o endpoint), e quem chama precisa se identificar com uma credencial, em geral um token de autenticação. Nada disso é exótico: é o mesmo mecanismo que o aplicativo do seu banco usa para falar com o servidor do banco.

API é excelente para dois movimentos: consultar dados quando você precisa deles e criar registros no outro sistema (uma ordem de coleta, um agendamento de doca, uma fatura). O ponto fraco é outro: a API não avisa nada por conta própria. Ela só responde quando alguém pergunta, e é dessa limitação que nascem os dois modelos seguintes.

Polling: ligar de meia em meia hora perguntando se chegou

Polling é usar o balcão no modo insistente. Como a API não avisa, o sistema interessado fica perguntando em intervalos fixos: a cada 30 minutos, “essa entrega já foi baixada?”. Na maioria das vezes a resposta é “ainda não”, e a pergunta se repete até o fim dos tempos.

É o equivalente digital do cliente que liga na sua operação de meia em meia hora perguntando se a carga chegou. Funciona, no sentido de que a informação uma hora aparece. Mas atrasa o dado (o evento pode acontecer um segundo depois da última consulta e vai esperar o ciclo inteiro) e sobrecarrega os dois lados com milhares de consultas que voltam vazias.

Você já viu polling mal calibrado sem saber o nome: é aquele portal de rastreamento em que o status da entrega só atualiza de hora em hora. O canhoto foi assinado às 9h04 e o embarcador só enxerga às 10h. Isso não é limitação da tecnologia, é escolha (ou preguiça) de quem montou a integração.

Webhook: aconteceu o evento, o sistema avisa na hora

O webhook inverte a lógica. Em vez de perguntar o tempo todo, o sistema interessado se inscreve para receber avisos: “quando essa entrega for baixada, me notifique neste endereço”. No instante em que o evento acontece, o sistema de origem dispara o aviso sozinho, para todos os inscritos.

É o motorista disciplinado que liga para a torre assim que termina a descarga, sem esperar ninguém cobrar. É por webhook que a entrega realizada aparece no sistema do embarcador em segundos, e não no próximo ciclo de consulta. Para eventos que importam (entrega, ocorrência, cancelamento, chegada ao cliente), webhook é o padrão de quem leva integração a sério.

Há um detalhe técnico que o gestor precisa conhecer: e se o sistema de destino estiver fora do ar na hora do aviso? Fornecedor maduro guarda o evento e tenta entregar de novo (a retentativa, com intervalos crescentes). Fornecedor amador dispara uma vez, falha em silêncio, e a informação some sem deixar rastro.

Tempo real e lote convivem: o lugar do EDI

Nem toda troca de dados precisa ser instantânea. O EDI clássico da logística brasileira, com arquivos NOTFIS, OCOREN e CONEMB, é integração em lote: os documentos acumulam e são transmitidos em blocos, em horários combinados. Esse mundo tem regras próprias, que detalhamos no guia sobre EDI logístico.

Lote resolve bem o que é volume e conciliação: o faturamento do dia, o espelho de conhecimentos emitidos, a prestação de contas semanal. Tempo real resolve o que é decisão: a ocorrência na rota, a entrega baixada, o veículo parado há 40 minutos. Os dois convivem na mesma operação, e muitos embarcadores grandes ainda exigem EDI como condição de contrato, como mostramos no artigo sobre integração com embarcador.

O erro, portanto, não é usar lote. O erro é usar lote para o que precisava de evento: descobrir às 18h, no arquivo do dia, uma ocorrência que aconteceu às 10h e que às 10h30 ainda tinha solução.

O que isso muda no negócio, não na TI

Integração parece assunto de tecnologia até você medir onde o dinheiro vaza sem ela. Três efeitos práticos de uma conversa bem feita entre sistemas:

• Cliente que enxerga sem ligar. Com eventos chegando em segundos ao portal do cliente, o embarcador consulta sozinho e o seu time para de gastar metade do dia respondendo “onde está minha carga”.
• Fatura que bate sozinha. Quando comprovante de entrega e ocorrência fluem por integração, a conciliação entre o que foi transportado e o que foi faturado deixa de ser mutirão de fim de mês e vira rotina silenciosa.
• Torre que reage em vez de descobrir. Uma torre de controle alimentada por evento age sobre o atraso enquanto ele ainda é contornável, não no relatório da manhã seguinte.

Nada disso exige que você saiba programar. Exige que os sistemas envolvidos, do TMS ao WMS do seu cliente, falem entre si pelo mecanismo certo para cada tipo de informação.

Como cobrar o fornecedor com propriedade

O vocabulário mínimo para a reunião de integração

Você não precisa dominar o jargão inteiro dos desenvolvedores. Cinco termos cobrem 90% de qualquer reunião de integração, e usá-los com naturalidade muda o tom da conversa com o fornecedor:

• Endpoint. O endereço de cada recurso da API. “Qual endpoint retorna as ocorrências?” é pergunta legítima de gestor, não de programador.
• Autenticação por token. A credencial que identifica quem está chamando. Deve ser individual, revogável e nunca circular em planilha por e-mail.
• Ambiente de homologação. Uma cópia do sistema para testar a integração sem sujar dado real. Integrar direto em produção é assumir risco de graça.
• Limite de requisições. Quantas chamadas por minuto a API aceita. Importa para calibrar polling e para saber se a integração aguenta o seu volume.
• Documentação pública. O manual da API acessível sem precisar pedir por e-mail. Se a documentação é segredo, a integração ainda é promessa.

As perguntas que separam fornecedor maduro de amador

Na próxima reunião, quatro perguntas resolvem a triagem. Primeira: a API é documentada e aberta, ou “sob demanda”? “Sob demanda” quase sempre significa que cada integração vira projeto cobrado à parte, com prazo elástico e dependência eterna do fornecedor.

Segunda: tem webhook ou só consulta? Se a resposta for “você pode consultar o endpoint quantas vezes quiser”, o fornecedor está vendendo polling e transferindo para você o custo do atraso. Terceira: o que acontece quando o destino está fora do ar? A palavra que você quer ouvir é retentativa, com detalhes de quantas tentativas e em que intervalos.

Quarta: tem ambiente de homologação? Sem ambiente de teste, todo erro de integração acontece com dado real, na sua operação, com o seu cliente assistindo.

O sinal de alerta definitivo: quando a “integração” oferecida é uma planilha trocada por e-mail. Isso não é integração, é digitação terceirizada com etapas extras, e quebra no primeiro dia de férias de quem envia o arquivo.

Integração boa é invisível

Ninguém elogia a integração que funciona. O status aparece, a fatura bate, a torre reage, e ninguém pensa no mecanismo, do mesmo jeito que ninguém pensa na rede elétrica ao acender a luz. Você só percebe a integração quando ela falta: no telefone que não para, na planilha atrasada, no cliente que descobre o problema antes de você.

Por isso a pergunta certa para qualquer fornecedor não é “vocês têm API?”, e sim “me mostre a documentação, o webhook e o ambiente de teste”. Quem tem, mostra em cinco minutos. Quem enrola, já respondeu.

A Growth Log é um TMS construído para conversar com o resto da sua operação: o status que o seu cliente vê atualiza no ritmo do evento, não no ritmo da consulta. Agende uma demonstração e veja na prática o que muda quando os sistemas falam entre si de verdade.