71 Calculo Frete

Cadastro das regras usadas pelo Mentor para localizar uma tabela de frete e calcular seus componentes em documentos comerciais e de transporte.

Para que serve

O recurso 71 — Cálculo de Frete centraliza a configuração de frete da empresa. Nele são definidos:

os transportadores aos quais o cadastro se aplica;
as constantes reutilizáveis nas expressões;
uma ou mais tabelas de cálculo, delimitadas por cidade de origem, cidade de destino e/ou cliente;
as fórmulas que calculam cada componente de frete;
condições e variáveis auxiliares que permitem mudar o cálculo conforme peso, cubagem, valor, distância e outros dados do documento.

O recurso é um cadastro: ele não calcula um frete isoladamente na própria tela. Os dados gravados são consumidos por rotinas de CT-e, RPS/NFS-e, pedido, cotação, nota fiscal própria e rota de pedidos.

Estrutura do cadastro

O cadastro possui três áreas principais.

Transportadoras

Relaciona o cálculo de frete a um ou mais transportadores ativos. O botão Pesquisar permite selecionar transportadores; itens já incluídos não são adicionados novamente. O botão Remover retira as linhas selecionadas.

Essa associação é usada principalmente pelos cálculos de pedido, cotação, nota fiscal própria e rota de pedidos. Nesses fluxos, a tabela é localizada pelo transportador e, conforme o documento, também pela cidade de destino.

Constantes

Permite cadastrar pares de Descrição e Valor. A descrição se torna o nome disponível nas expressões das fórmulas, e o valor deve ser numérico.

Exemplo:

Descrição	Valor	Uso possível
`taxaMinima`	`35.00`	Garantir um valor mínimo na expressão de cálculo.
`percentualGris`	`0.003`	Aplicar um percentual sobre o valor da carga.

Use nomes sem espaços e diferentes dos nomes de variáveis nativas. Como as constantes são inseridas no mesmo conjunto de valores usado pelo avaliador de expressões, nomes repetidos podem sobrescrever valores já existentes.

Tabelas de Cálculo

Cada cálculo deve possuir ao menos uma tabela. Uma tabela contém:

Aba	Finalidade
Dados	Identificador e descrição obrigatória da tabela.
Cidades origem	Origens às quais a tabela se aplica.
Cidades destino	Destinos aos quais a tabela se aplica.
Clientes	Clientes/tomadores específicos aos quais a tabela se aplica.
Fórmulas	Condições e expressões que produzem os componentes do frete.

Uma tabela deve ter ao menos uma fórmula. Na gravação do cadastro, o sistema também impede cidades de origem, cidades de destino ou clientes duplicados dentro da mesma tabela.

Fórmulas

Cada fórmula possui:

Descrição obrigatória;
Componente de frete ao qual o resultado pertence;
Condição de aplicação obrigatória;
Cálculo obrigatório;
variáveis auxiliares opcionais, cada uma com seus próprios valores condicionais.

As condições e cálculos são expressões numéricas. Uma condição é considerada verdadeira quando seu resultado é 1. As fórmulas são avaliadas na ordem em que estão armazenadas e a primeira condição verdadeira é escolhida. Se nenhuma condição for verdadeira, o serviço web retorna valor de frete 0; em fluxos legados de CT-e/RPS o tratamento pode depender do componente e do documento.

Exemplo conceitual:

Condição: pesoTotal <= 100
Cálculo:  taxaMinima + (pesoTotal * 0.50)

Para faixas, evite sobreposição. Por exemplo, use pesoTotal <= 100 e pesoTotal > 100, em vez de duas condições que possam ser verdadeiras simultaneamente.

Como a fórmula funciona

O cálculo acontece em três etapas:

O processo que está calculando o frete fornece os valores disponíveis, como peso, cubagem, distância e valor do documento.
O sistema percorre as fórmulas da tabela na ordem cadastrada e avalia a Condição de Aplicação de cada uma. Resultado 1 significa verdadeiro; resultado 0 significa falso.
Ao encontrar a primeira condição verdadeira, o sistema avalia o campo Cálculo dessa fórmula e atribui o resultado ao componente de frete selecionado.

As expressões podem combinar números, constantes, variáveis e operadores matemáticos ou de comparação. Exemplos:

Condição sempre verdadeira: 1
Condição por peso:            pesoTotal <= 100
Condição por valor:           valorTotal > 1000
Cálculo por peso:             taxaMinima + (pesoTotal * 0.50)
Cálculo percentual:           valorTotal * percentualGris

Os botões exibidos ao lado da condição e do cálculo inserem o nome técnico correto da variável na posição do cursor. Alguns botões ficam agrupados por fluxo — RPS/NFS-e de transportes, Transportadora/CT-e ou Nota própria/terceiros — porque nem todas as variáveis existem em todos os processos.

Como cadastrar uma fórmula

Dentro de Tabelas de Cálculo, selecione ou crie a tabela desejada.
Abra a aba Fórmulas e clique em Adicionar.
Na aba Dados, informe uma descrição que identifique a regra, por exemplo Frete até 100 kg.
Selecione o Componente de Frete que receberá o resultado. Ao selecionar o componente, a descrição pode ser preenchida automaticamente quando ainda estiver vazia.
Abra a aba Fórmula.
Preencha a Condição de Aplicação. Use 1 quando a fórmula for incondicional ou informe uma comparação, como pesoTotal <= 100.
Preencha Cálculo com a expressão que retorna o valor do componente, como taxaMinima + (pesoTotal * 0.50).
Use os botões de variáveis da tela para inserir os nomes e evitar erros de digitação.
Se a fórmula precisar de valores intermediários por faixa, cadastre-os na aba Variáveis, conforme explicado a seguir.
Confirme a fórmula e depois salve o cadastro principal do cálculo de frete.

Cadastre primeiro as regras mais específicas e deixe a regra genérica por último. Por exemplo:

Ordem	Descrição	Condição	Cálculo
1	Frete leve	`pesoTotal <= 100`	`taxaMinima + (pesoTotal * 0.50)`
2	Frete pesado	`pesoTotal > 100`	`taxaMinima + (pesoTotal * 0.40)`

Variáveis auxiliares por faixa

A aba Variáveis serve para calcular um valor intermediário que será utilizado na fórmula principal. Cada variável possui uma descrição — que funciona como seu nome na expressão — e uma lista de valores possíveis. Para cada valor são informados:

uma Descrição;
uma Condição de Aplicação;
um Cálculo que produz o valor da variável.

O sistema percorre os valores da variável na ordem cadastrada e utiliza o primeiro cuja condição resultar em 1. Em seguida, disponibiliza o resultado pelo nome da variável para a condição e o cálculo da fórmula principal.

Exemplo de variável valorKg:

Ordem	Descrição	Condição	Cálculo
1	Até 100 kg	`pesoTotal <= 100`	`0.50`
2	Acima de 100 kg	`pesoTotal > 100`	`0.40`

Depois, no campo Cálculo da fórmula, pode-se usar:

taxaMinima + (pesoTotal * valorKg)

O nome da variável auxiliar deve ser único na fórmula, não deve conter espaços e não deve coincidir com uma constante ou variável nativa. Toda variável precisa ter descrição e ao menos um valor cadastrado; cada valor também exige descrição, condição e cálculo.

Variáveis nativas disponíveis

O conjunto exato depende do fluxo consumidor. Os nomes reconhecidos pelo código são:

Variável	Significado	Principais fluxos
`distancia`	Distância em quilômetros.	CT-e, RPS, pedido, cotação, NF própria e rota.
`pesoTotal`	Peso total da carga/documento.	Todos os cálculos principais.
`cubagem`	Cubagem/volume total.	CT-e e serviços comerciais.
`valorTotal`	Valor total sem a composição adicional de impostos do fluxo.	CT-e e serviços comerciais.
`valorTotalComImpostos`	Valor total com impostos.	CT-e e serviços comerciais.
`nrDiasMedios`	Prazo médio da condição de pagamento.	CT-e e serviços comerciais.
`valorPedagio`	Valor de pedágio.	CT-e; nos serviços comerciais atuais é informado como zero.
`qtdTotalItensNF`	Quantidade total dos itens.	CT-e e serviços comerciais.
`capCubagemConjTransportador`	Capacidade de cubagem do conjunto transportador.	CT-e; zero nos serviços comerciais atuais.
`capPesoConjTransportador`	Capacidade de peso do conjunto transportador.	CT-e; zero nos serviços comerciais atuais.
`nrEixosConjTransportador`	Número de eixos do conjunto transportador.	CT-e; zero nos serviços comerciais atuais.
`valorRemDest`	Valor configurado para remetente/destinatário.	CT-e e RPS.
`taxaServico`	Taxa de serviço do tomador/prestador.	RPS.
`valorFreteProgramacaoViagem`	Valor de frete da programação de viagem.	Fluxos de transporte que o forneçam.

As fórmulas do CT-e também podem receber quantidades por unidade de medida configurada. A tela monta botões dinamicamente para essas unidades.

Funções de expressão

Os avaliadores legados de CT-e/RPS registram as funções arredondar, teto e piso. Como há mais de um motor de cálculo no sistema, valide fórmulas novas no fluxo em que serão utilizadas, principalmente quando dependem de funções e não apenas de operadores aritméticos.

Como o sistema localiza a tabela

CT-e no desktop

O CT-e pesquisa a tabela nesta ordem:

cliente + cidade de origem + cidade de destino;
cliente + cidade de destino;
cliente + cidade de origem;
cidade de origem + cidade de destino, sem cliente específico;
somente cliente.

As etapas 2 a 5 só são tentadas quando a opção de faturamento de transporte Validar todos os dados da tabela está desativada ou não informada. Quando essa opção está ativa, apenas a correspondência completa da primeira etapa é aceita.

Se mais de uma tabela satisfizer a mesma combinação, o sistema gera erro informando os identificadores conflitantes. Se nenhuma for encontrada, o CT-e informa que não há tabela para origem, destino e cliente.

Observação: a associação de transportadores do cadastro não participa dessa pesquisa legada do CT-e; ela é usada pelos serviços comerciais descritos a seguir.

Pedido, cotação e nota fiscal própria

Os serviços procuram uma tabela que combine:

o transportador do documento; e
a cidade de destino do cliente/unidade de faturamento.

A consulta espera um único resultado. Portanto, não configure duas tabelas que atendam ao mesmo par transportador/destino.

Rota de pedidos

A rota procura a tabela pelo transportador. A implementação atual exige que a tabela também possua ao menos uma cidade de destino cadastrada, embora não filtre por uma cidade específica. Mais de uma tabela para o mesmo transportador pode tornar o resultado ambíguo.

RPS/NFS-e de transporte

O RPS não faz a seleção automática pela regra do CT-e. Ele utiliza a tabela vinculada ao cadastro de Tomador/Prestador RPS, lê distância e taxa de serviço desse cadastro e calcula as quantidades da carga a partir das unidades de medida da nota relacionada.

Remetente/Destinatário de frete

O cadastro de remetente/destinatário pode vincular tabelas a componentes e tipos de conjunto transportador. No cálculo do CT-e, essa configuração pode determinar a tabela usada por componente antes da avaliação da fórmula.

Onde o recurso é usado

Processo	Uso do cadastro
CT-e	Localiza a tabela por rota/cliente, escolhe fórmulas por componente e grava a tabela utilizada no CT-e.
RPS/NFS-e de transporte	Usa a tabela do tomador/prestador para calcular o valor de frete.
Pedido	Localiza por transportador e destino, calcula o frete e atualiza valor e percentual de frete.
Cotação de vendas	Localiza por transportador e destino, calcula o frete e atualiza valor e percentual.
Nota fiscal própria	Localiza por transportador e destino; o resultado pode ser rateado proporcionalmente entre os itens.
Rota de pedidos	Localiza por transportador e calcula sobre os totais agregados dos pedidos da rota.
Cliente	Permite vincular tabelas de frete para transportador, redespacho e representante.
Remetente/Destinatário	Permite escolher tabela por componente de frete e tipo de conjunto transportador.

Passo a passo recomendado

Acesse o recurso 71 — Cálculo de Frete e crie um registro.
Informe uma descrição clara e exclusiva.
Na aba Transportadoras, inclua os transportadores usados por pedidos, cotações, notas e rotas.
Na aba Constantes, cadastre somente valores comuns às fórmulas.
Em Tabelas de Cálculo, crie uma tabela e informe sua descrição.
Defina origem, destino e cliente conforme a forma de seleção do processo consumidor.
Cadastre as fórmulas da condição mais específica para a mais abrangente.
Garanta que exista uma fórmula de cobertura para todos os casos válidos, sem faixas sobrepostas.
Salve e teste com um documento representativo do fluxo que consumirá a regra.
Confira a tabela escolhida, os componentes calculados e o valor total antes de liberar a configuração.

Validações e limitações

A descrição do cálculo é obrigatória e única.
É obrigatório cadastrar ao menos uma tabela.
A descrição da tabela é obrigatória e ela deve possuir ao menos uma fórmula.
Não são permitidos cidade de origem, cidade de destino ou cliente duplicados na mesma tabela.
A descrição e o valor de cada constante são obrigatórios; o valor deve ser numérico.
Descrição, condição de aplicação e cálculo da fórmula são obrigatórios.
Variáveis auxiliares precisam de descrição e de ao menos um valor condicionado.
O cadastro não pode ser clonado.
Não há relatório disponível diretamente nesse recurso.
A tela oferece a opção Pesquisar por cliente, que lista os cálculos associados às tabelas do cliente selecionado.

Solução de problemas

Sintoma	Verificação
Tabela de frete não encontrada	Confira cliente, origem, destino e a opção Validar todos os dados da tabela no CT-e; nos fluxos comerciais, confira transportador e destino.
Existem várias tabelas que satisfazem a condição	Remova a sobreposição entre tabelas que possuem a mesma combinação de cliente/origem/destino ou transportador/destino.
Frete calculado como zero	Verifique se o cálculo está habilitado, se uma tabela foi localizada e se ao menos uma condição de fórmula resulta em `1`.
Componente não calculado no CT-e	Confira se existe fórmula para o componente e se os dados exigidos pela condição estão preenchidos no CT-e.
Erro ao avaliar expressão	Revise nomes de constantes/variáveis, operadores, parênteses e valores nulos. Teste a fórmula no mesmo processo que irá consumi-la.
Resultado diferente entre CT-e e pedido/RPS	Os fluxos usam conjuntos de variáveis e, em partes do sistema, avaliadores distintos. Evite depender de variável não fornecida pelo fluxo.
Não consegue salvar	Verifique descrição, existência de tabela e fórmula, duplicidades e se todas as constantes/variáveis estão completas.

Documento elaborado a partir da implementação vigente em setembro de 2026.