Integrar transportadora ao ERP via API: como fazer

Integrar uma transportadora ao ERP via API significa conectar os dois sistemas por troca automática de dados: o ERP envia pedidos, recebe cotações, gera documentos fiscais e consulta status de entrega sem intervenção manual. O caminho envolve autenticação, mapeamento de campos, testes em sandbox e homologação em produção. A complexidade varia com o ERP, o volume de envios e a maturidade da API da transportadora.

Resposta em detalhe

O que é uma API de transportadora e o que ela expõe

Uma API de transportadora é um conjunto de endpoints que permite que sistemas externos disparem ações ou consultem dados sem acessar o painel da transportadora manualmente. Os endpoints mais comuns cobrem:

• Cotação: calcula frete por origem, destino, peso e medidas.
• Coleta: agenda o recolhimento de volume.
• Emissão de conhecimento (CT-e ou equivalente): gera o documento de transporte.
• Rastreamento: retorna eventos do ciclo de vida da entrega.
• Prazo de entrega: informa o transit time estimado para um CEP de destino.

Plataformas como a Kargu oferecem uma API única que orquestra múltiplos modais, o que elimina a necessidade de manter integrações separadas para cada transportadora da malha. Para operações interestaduais, isso reduz o trabalho de TI de forma relevante.

Como a integração funciona na prática

O fluxo padrão tem três momentos distintos. Primeiro, o ERP chama o endpoint de cotação ao criar um pedido e recebe as opções de frete disponíveis com prazo e custo. Segundo, ao confirmar o pedido, o ERP dispara a solicitação de coleta e recebe o número do conhecimento. Terceiro, em intervalos programados (polling) ou por webhooks enviados pela transportadora, o ERP atualiza o status do pedido até a confirmação de entrega.

A escolha entre polling e webhook afeta a latência das atualizações. Webhooks entregam eventos em tempo real assim que a transportadora registra uma ocorrência; polling exige que o ERP pergunte periodicamente, o que pode gerar atraso. Para operações com SLA apertado, webhooks são preferíveis. Você pode ver como o rastreamento em tempo real funciona nesse modelo em rastreamento via API de transportadora em tempo real.

Quais ERPs suportam integração nativa com transportadoras

ERPs de maior adoção no mercado brasileiro (SAP, TOTVS, Oracle, Bling, Tiny, entre outros) oferecem módulos de TMS embutidos ou suportam integrações via REST ou SOAP. A maioria dos ERPs mais modernos usa REST com autenticação OAuth 2.0 ou API Key. ERPs mais antigos podem exigir uma camada intermediária, um middleware ou iPaaS, para traduzir chamadas entre formatos incompatíveis.

WMS integrados ao ERP seguem a mesma lógica: o gatilho de expedição no WMS pode disparar automaticamente a cotação e a reserva de coleta na transportadora, sem que o operador de armazém precise acessar outro sistema.

---

Como aplicar na prática

1. Mapeie os processos que serão automatizados. Defina quais etapas hoje são manuais: cotação, emissão de CT-e, agendamento de coleta, atualização de status. Cada uma vira um endpoint na integração.

2. Solicite à transportadora a documentação da API. Verifique se há sandbox para testes, quais formatos são aceitos (JSON, XML), qual o esquema de autenticação e se existem limites de requisição por minuto.

3. Avalie se seu ERP conecta diretamente ou precisa de middleware. ERPs com módulo TMS nativo costumam ter conectores prontos ou documentação de parceiro. ERPs legados geralmente precisam de uma ferramenta de integração intermediária.

4. Mapeie os campos obrigatórios. Origem, destino (CEP), peso bruto, peso cubado, valor declarado e natureza da carga são campos quase universais. Campos opcionais como instrução de entrega ou horário de coleta variam por transportadora.

5. Teste em sandbox com pedidos reais. Simule pedidos com os pesos, origens e destinos mais comuns da sua operação. Verifique se os prazos e valores retornados batem com o que a transportadora oferece no painel manual.

6. Defina tratamento de erros e fallback. O que acontece se a API estiver fora do ar ou retornar erro? O pedido deve ficar em fila, o operador deve ser notificado ou há uma transportadora de backup?

7. Homologue em produção com volume controlado. Comece com uma rota ou filial. Acompanhe por algumas semanas antes de expandir para toda a operação.

8. Monitore SLA após a entrada em produção. Compare o transit time prometido pela API com o realizado. Divergências frequentes indicam problema no mapeamento de zonas ou na qualidade dos dados enviados.

---

O que pesa na decisão

Maturidade da API da transportadora. APIs bem documentadas, com sandbox, versionamento e suporte técnico dedicado reduzem o tempo de desenvolvimento. Uma API mal documentada pode dobrar o esforço da integração, mesmo quando os endpoints existem. Antes de escolher uma transportadora, peça a documentação técnica e avalie a qualidade do material.

Volume de envios e custo de desenvolvimento. Para operações com poucos despachos mensais, o custo de desenvolvimento e manutenção da integração pode superar o benefício operacional. Para operações com alto volume interestadual, a automação elimina erros de digitação, reduz o tempo de expedição e melhora a acurácia do prazo informado ao cliente. Como escolher transportadora para diferentes volumes traz critérios práticos para esse corte.

Cobertura geográfica exposta pela API. Uma transportadora pode atender 500 cidades manualmente, mas sua API pode ter cobertura menor se os dados de prazo e tabela não estiverem totalmente carregados no sistema. Confirme se a API devolve cotação para todos os CEPs que você precisa atender, não apenas para as principais capitais.

Gestão de múltiplas transportadoras. Quem usa mais de uma transportadora precisa decidir: integração individual com cada uma, ou uma plataforma que centralize todas via API única. A segunda opção reduz o número de contratos técnicos a manter e simplifica o processo de troca de transportadora sem refazer a integração no ERP.

Consistência entre a tabela negociada e o que a API retorna. É comum que a tabela comercial acordada com a transportadora não esteja carregada corretamente na API, gerando cotações divergentes do esperado. Antes de ir a produção, valide uma amostra de CEPs comparando o retorno da API com o valor negociado manualmente.

---

Perguntas frequentes

A integração via API elimina a necessidade de emitir CT-e manualmente?

Sim, quando a API oferece o endpoint de emissão de documento de transporte. O ERP dispara a emissão e recebe o número do CT-e em resposta, sem acesso ao sistema da transportadora. Mas é preciso confirmar se a transportadora disponibiliza esse endpoint e se há homologação com a SEFAZ pelo caminho.

Quanto tempo leva para integrar uma transportadora ao ERP?

Depende da maturidade da API, do ERP e da complexidade dos processos. Integrações simples, com API bem documentada e ERP moderno, podem ser concluídas em dias. Integrações que envolvem middleware, campos customizados ou ERPs legados costumam levar semanas. Testes e homologação em produção geralmente são a etapa mais demorada.

É possível integrar mais de uma transportadora ao mesmo tempo no ERP?

Sim. O padrão é criar um módulo de cotação múltipla que chama os endpoints de cada transportadora em paralelo e apresenta as opções ao operador, ou seleciona automaticamente a melhor por regra de negócio. Plataformas logísticas como a Kargu centralizam essa lógica em uma API única, o que reduz o número de integrações a manter.

O que acontece com o rastreamento quando a entrega passa por mais de um modal?

Em operações multimodais, o rastreamento consolidado depende de a transportadora (ou plataforma) expor eventos de todos os elos da cadeia em um único endpoint. Sem isso, o ERP recebe eventos fragmentados e o time de atendimento precisa cruzar sistemas para responder ao cliente. Ao avaliar a integração, pergunte se a API retorna eventos de toda a cadeia ou apenas do trecho principal. Veja mais sobre isso em logística multimodal: o que é e como reduz custos.

Perguntas frequentes