Integração com APIs de transportadoras: cotação, etiquetas, rastreamento e conciliação de frete

Por que integrar com as transportadoras

Enquanto o volume é pequeno, consultar o portal de cada transportadora resolve. Quando a operação cresce, o processo manual vira gargalo: a equipe copia códigos de rastreio, interpreta mensagens diferentes para a mesma situação, digita pesos e medidas para cotar frete e só descobre um atraso quando o cliente reclama.

A integração muda a lógica do trabalho. O sistema passa a buscar valores, prazos e eventos diretamente nas fontes logísticas, grava tudo em uma base única e mostra para a equipe apenas o que exige ação: entrega parada, prazo vencido, ocorrência, divergência de cobrança.

• Cotação de frete em segundos no checkout, no portal B2B ou na proposta comercial.
• Etiquetas geradas a partir do pedido, sem redigitação de endereço.
• Rastreamento centralizado, com o mesmo status para todas as transportadoras.
• Alertas de exceção antes que o cliente precise perguntar.
• Conferência automática entre frete cotado, CT-e recebido e fatura cobrada.

O que normalmente se integra

Uma integração logística completa cobre o ciclo inteiro da entrega. Nem toda empresa precisa de tudo no primeiro momento, mas vale desenhar a arquitetura já pensando nas etapas seguintes.

Etapa	O que o sistema faz	Canais mais comuns
Cotação	Envia origem, destino, peso, dimensões e valor; recebe preço, prazo e serviço	API REST, webservice SOAP, tabela de frete
Pré-postagem e coleta	Registra o envio, solicita coleta e recebe o código de rastreio	API REST, portal, arquivo NOTFIS
Etiqueta	Gera a etiqueta de volume para impressão	PDF, PNG ou ZPL para impressoras térmicas
Rastreamento	Consulta ou recebe eventos de transporte e entrega	API de rastreio, webhook, arquivo OCOREN
Documento fiscal do frete	Recebe o CT-e emitido contra o CNPJ do tomador	Distribuição de DF-e, XML enviado pela transportadora
Cobrança	Confere fatura, conhecimentos e valores cobrados	DOCCOB, CONEMB, fatura em PDF ou XML

API, webservice e EDI: os canais mais comuns

Cada transportadora expõe seus serviços de um jeito. As mais estruturadas oferecem APIs REST com JSON e autenticação por token. Outras ainda trabalham com webservices SOAP, que continuam funcionando bem quando são encapsulados por uma camada mais simples dentro do sistema.

No transporte de cargas fracionadas também é muito comum o EDI, troca de arquivos em layouts padronizados pelo mercado, normalmente via SFTP. Os mais usados são:

Arquivo	Para que serve
NOTFIS	Envio dos dados das notas fiscais que serão transportadas
OCOREN	Retorno das ocorrências de transporte e entrega
CONEMB	Informações dos conhecimentos de transporte embarcados
DOCCOB	Documento de cobrança com os conhecimentos faturados

Os Correios, por exemplo, oferecem para clientes com contrato um conjunto de APIs no portal CWS (Correios Web Services), com serviços de token, CEP, preço, prazo, rastro e pré-postagem, além de ambiente de homologação para testes. O acesso depende do contrato ativo e do cadastro de credenciais de API.

Arquitetura: um conector por transportadora

O desenho que melhor sobrevive ao uso real separa duas camadas. Na base, um conector por transportadora conhece autenticação, campos obrigatórios, limites e particularidades daquele parceiro. Acima dele, um modelo único de cotação, envio e evento que o ERP, o e-commerce e o atendimento consomem.

1. O sistema identifica o que precisa ser feito: cotar, registrar envio, atualizar rastreio ou conferir cobrança.
2. Uma fila distribui o trabalho para o conector da transportadora correta.
3. O conector chama a API ou lê o arquivo, com tempo limite e retentativa controlada.
4. A resposta é normalizada para o modelo único, sem descartar o retorno original.
5. O status interno é atualizado e o evento fica registrado em log.
6. Regras de exceção disparam alertas para a equipe ou mensagens para o cliente.

Com essa separação, incluir uma nova transportadora significa escrever um novo conector, e não reescrever o módulo inteiro. Um evento de rastreio normalizado pode ficar assim:

{
  "pedido": "874521",
  "nfe_chave": "43260912345678000190550010000123451000123456",
  "transportadora": "transportadora-a",
  "codigo_rastreio": "AB123456789BR",
  "status": "saiu_para_entrega",
  "evento_original": "Objeto saiu para entrega ao destinatário",
  "local": "Porto Alegre/RS",
  "ocorrido_em": "2026-10-07T08:42:00-03:00"
}

Cotação de frete: do pedido à melhor opção

A cotação recebe origem, destino, peso, dimensões, quantidade de volumes e valor da mercadoria, consulta as transportadoras habilitadas para aquele envio e devolve as opções em um formato comparável. Cada transportadora pode aplicar regras próprias de cubagem, taxas regionais, restrições de produto e componentes adicionais, por isso a cotação via API costuma ficar mais próxima do valor efetivamente cobrado do que uma tabela estática.

Algumas decisões fazem diferença no resultado:

• Consultas em paralelo com tempo limite: uma transportadora lenta não pode travar o checkout.
• Falha isolada: se uma API cair, as outras opções continuam aparecendo.
• Regra de escolha explícita: menor preço, menor prazo, transportadora preferencial, cobertura regional ou histórico de desempenho.
• Fallback documentado: tabela interna apenas quando fizer sentido e sinalizada como tal.
• Registro da cotação: valor retornado, valor exibido ao cliente e regra aplicada.

Etiquetas e pré-postagem sem redigitação

Depois da escolha do frete, o sistema registra o envio na transportadora, recebe o código de rastreio e gera a etiqueta do volume. O cuidado mais importante aqui é a idempotência: se a requisição for reenviada por uma falha de rede, o sistema precisa reconhecer o envio que já existe em vez de gerar uma segunda etiqueta e uma segunda cobrança.

Muitas transportadoras e impressoras térmicas trabalham com ZPL, a linguagem das impressoras Zebra. Vale validar o layout antes de mandar para a expedição: dimensões, código de barras, QR Code e campos obrigatórios. Para isso eu mantenho o db ZPL, que renderiza etiquetas ZPL em PNG, PDF e outros formatos direto no navegador ou por API.

O código de rastreio deve ficar vinculado ao pedido, à nota fiscal (pela chave de acesso) e ao volume. Esse vínculo é o que permite responder ao cliente e conferir a cobrança depois.

Rastreamento com status padronizado

Cada transportadora descreve a mesma situação com palavras diferentes. O sistema precisa traduzir esses retornos para um conjunto pequeno de status internos, sem jogar fora o texto original, que continua sendo a evidência quando surge uma divergência.

Retorno da transportadora	Status interno
“Objeto postado”, “Coletado”, “Recebido na origem”	postado
“Em transferência”, “Em trânsito para a unidade”	em_transito
“Saiu para entrega”, “Em rota de entrega”	saiu_para_entrega
“Entregue”, “Entrega realizada”	entregue
“Destinatário ausente”, “Endereço insuficiente”	ocorrencia
“Devolvido ao remetente”	devolvido

Para manter os dados atualizados há dois caminhos: consulta periódica (o sistema pergunta de tempos em tempos) e webhook ou arquivo de retorno (a transportadora avisa quando algo muda). O ideal é usar o que cada parceiro oferece e ajustar a frequência de consulta pela fase da entrega: quem já saiu para entrega precisa ser verificado mais vezes do que quem acabou de ser postado.

O ganho real aparece nas exceções: entrega sem movimentação há dias, prazo prometido vencido, tentativa sem sucesso, endereço incorreto ou comprovante disponível. Essas situações devem gerar alerta para a equipe e, quando fizer sentido, mensagem automática para o cliente por e-mail ou WhatsApp.

CT-e e conciliação do frete

O ciclo só fecha quando o financeiro confere o que foi cobrado. A transportadora emite o CT-e contra o CNPJ do tomador do serviço, e esse documento pode ser obtido automaticamente pela distribuição de documentos fiscais eletrônicos, sem esperar o envio por e-mail.

Com o CT-e, a fatura e a cotação registradas, o sistema compara três valores: o que foi cotado, o que consta no CT-e e o que foi faturado. As divergências mais comuns aparecem em peso cubado, taxas adicionais de entrega, reentregas e devoluções.

Escrevi em detalhe sobre essa central de documentos no artigo Módulo DF-e: gestão de NF-e, CT-e e NFS-e, e é o mesmo princípio do db Cloud DF-e, aplicativo que busca os XMLs emitidos contra o CNPJ da empresa.

Cuidados técnicos que evitam dor de cabeça

• Credenciais por contrato e por filial, guardadas fora do código e com troca controlada.
• Homologação antes da produção, principalmente para pré-postagem, que gera custo real.
• Limites de requisição respeitados, com fila e espera entre tentativas.
• Retentativa só para erro temporário: erro de regra (CEP inválido, peso acima do limite) precisa voltar para a equipe.
• Payload original guardado quando permitido, para auditoria e suporte.
• Monitoramento por transportadora: taxa de erro, tempo de resposta e mudanças de contrato.
• Dados pessoais de destinatários tratados conforme a LGPD, com acesso restrito.
• Diferença entre “API fora do ar” e “sem movimento”: falha de consulta não pode virar status de entrega.

Indicadores que a integração libera

Com cotações, envios, eventos e cobranças na mesma base, a logística passa a ser medida em vez de estimada:

• percentual de entregas no prazo, por transportadora e por região;
• custo de frete por pedido e sobre a receita;
• diferença média entre frete cotado e frete faturado;
• tempo até a primeira movimentação e tempo por etapa;
• taxa de ocorrências e de sucesso na primeira tentativa de entrega.

Esses números ajudam a negociar contratos, revisar prazos comerciais e escolher a melhor transportadora para cada rota.

Por onde começar

1. Liste as transportadoras ativas e o canal técnico de cada uma: API, webservice, EDI ou apenas portal.
2. Comece pela etapa que mais consome tempo hoje, geralmente rastreamento ou cotação.
3. Defina o modelo único de cotação, envio e evento antes de escrever o primeiro conector.
4. Homologue com volume real e compare com a operação manual por alguns dias.
5. Crie o painel de exceções, que é onde a equipe vai trabalhar no dia a dia.
6. Feche o ciclo com a conciliação entre cotação, CT-e e fatura.

Perguntas frequentes

Toda transportadora tem API?

Não. Muitas transportadoras de carga fracionada trabalham com EDI (NOTFIS, OCOREN, CONEMB e DOCCOB) e algumas só oferecem portal. Um conector bem feito pode ler arquivos de retorno com o mesmo resultado para o restante do sistema.

Vale a pena usar uma plataforma intermediária de fretes?

Pode valer para começar rápido, principalmente no e-commerce. Em operações maiores, ou com contratos próprios negociados, a integração direta dá mais controle sobre regras, custos e dados. Também é possível combinar os dois modelos.

É melhor consultar o rastreio periodicamente ou receber webhook?

Webhook ou arquivo de retorno é mais eficiente quando a transportadora oferece. Quando não oferece, a consulta periódica funciona bem com frequência ajustada pela fase da entrega e respeitando os limites da API.

Como evitar etiqueta e cobrança duplicadas?

Com idempotência: cada envio tem um identificador único, e o sistema verifica se ele já foi registrado antes de chamar a transportadora de novo. Os retornos ficam gravados para que um reenvio recupere a etiqueta existente.

Preciso trocar meu ERP para integrar as transportadoras?

Não. A integração costuma ser uma camada ao lado do ERP, lendo pedidos e notas pela API, banco de dados ou arquivos que ele já oferece e devolvendo rastreio e custos para os lugares certos.