Existem situações em que é necessário calcular uma estimativa do valor do frete e/ou do prazo de entrega de produtos a partir de outros sistemas.
Por exemplo, um sistema de loja virtual (e-commerce) pode precisar do valor do frete para exibir para o cliente no momento do pedido. Ou um vendedor utilizando um sistema de vendas pode precisar visualizar os valores de frete / transportadoras disponíveis ao registrar o pedido do cliente.
Nestas situações, a solução ideal é que esses sistemas externos acessem diretamente o Gestor Logístico através da API do sistema. Através dela, esses sistemas podem enviar os dados dos produtos e a origem/destino do frete, e recebem de volta os valores calculados pelas tabelas de cada transportadora que atende à região de destino informada, bem como o prazo estimado para a entrega.
Observe que o cálculo é feito de acordo com as tabelas / contratos de transportadoras cadastradas no sistema, e apenas para aquelas que "atendem" os parâmetros informados. Por exemplo, as transportadoras que não transportam para o destino informado não serão listadas nos resultados.
Obs: Para algumas transportadoras, como os Correios e a Braspress, o sistema também tem a opção de realizar o cálculo através de integração on-line com a transportadora, ao invés de utilizar a tabela cadastrada no sistema. Para configurar o sistema dessa forma, entre em contato com nosso time de suporte.
Como fazer
O serviço de simulação de fretes pode ser acessado através de um POST para o endpoint /simulacoes/avulsa, passando no corpo da requisição os parâmetros necessários para o cálculo.
Você pode informar filtros na requisição, de forma a limitar o resultado a ser obtido e dessa forma otimizar a performance do processo. Por exemplo, você pode informar o modal, o tipo da operação, e/ou a transportadora a serem utilizados para os cálculos.
O resultado será uma lista dos possíveis cenários para a operação, sendo que cada um dos cenários refere-se a uma transportadora/modal/tipo de operação e vai conter o valor do frete e o prazo estimado para o respectivo cenário.
A requisição
Cada requisição refere-se a uma única transação de transporte, ou seja, deve conter uma única origem e um único destino, mas pode conter uma única nota fiscal (ou pedido), ou uma carga contendo várias notas fiscais a serem movimentadas nesse trecho. Os dados da nota ou pedido devem ser passados totalizados.
POST /simulacoes/avulsa
{
"localOrigem": {
"tipo": 2,
"endereco": {
"pessoa": {
"nome": "ABCD",
"cpfCnpj": {
"tipoPessoa": 2,
"numero": 12345678000123
}
},
"logradouro": "RUA UM DOIS TRES",
"localidade": {
"nome": "MARINGA",
"uf": {
"sigla": "PR"
}
},
"cep": 88301001
}
},
"localDestino": {
"tipo": 3,
"localidade": {
"nome": "JACAREI",
"uf": {
"sigla": "SP"
}
},
"cep": 12308020
},
"qtdVolumes": 101,
"volume": 0.47322,
"peso": 101,
"valorMercadoria": 3019,
"compraOuVenda": 1,
"retornarApenasNPrimeiras": 3
}
Trecho da operação (origem / destino do frete)
O trecho deve ser informado através dos objetos localOrigem e localDestino. Esses objetos contém um atributo tipo que identifica as possíveis formas de se identificar um local para o sistema. Os demais atributos dependem do tipo informado.
Obs: Os locais de origem e destino não precisam necessariamente ser do mesmo tipo, você pode escolher o que for mais conveniente. Porém, o conteúdo deve estar alinhado com os valores que tiverem sido cadastrados nas tabelas de frete.
Os valores e formatos possíveis para os objetos localOrigem e localDestino são:
2 -> Representa um ENDEREÇO
É a forma mais precisa de se indicar um local de origem ou destino, e deve ser a preferida caso possível. O sistema vai pesquisar, entre as tabelas de frete cadastradas, a condição mais adequada para o endereço informado.
{
"tipo": 2,
"endereco": {
"pessoa": {
"nome": "NOME DO REMETENTE OU DESTINATÁRIO",
"cpfCnpj": {
"tipoPessoa": 1 PARA CPF, 2 PARA CNPJ,
"numero": NÚMERO DO CPF OU CNPJ
}
},
"logradouro": "NOME DA RUA, AVENIDA, ALAMEDA, ETC",
"localidade": {
"nome": "NOME DA CIDADE",
"uf": {
"sigla": "SIGLA DO ESTADO, COM 2 LETRAS"
}
},
"cep": CEP DO ENDEREÇO
}
}3 -> Representa uma CIDADE
É uma forma um pouco mais genérica para indicar o trecho, mas geralmente é suficiente para um cálculo preciso. Porém, caso existam nas tabelas de frete particularidades para endereços ou CEPs específicos, elas não serão consideradas na pesquisa por cidade.
{
"Tipo": 3,
"Localidade": {
"nome": "NOME DA CIDADE",
"uf": {
"sigla": "SIGLA DO ESTADO, COM 2 LETRAS"
}
}
}4 -> Representa um ESTADO (UF)
É uma forma bem mais genérica, e deve ser utilizada com um pouco mais de critério, apenas para as situações onde sabe-se que as tabelas foram cadastradas de forma compatível. É mais comumente utilizada para designar a origem, quando não existe diferença no valor do frete para as várias cidades do estado de origem.
{
"Tipo": 4,
"uf": {
"sigla": "SIGLA DO ESTADO, COM 2 LETRAS"
}
}6 -> Representa um CEP
Algumas tabelas de frete são baseadas exclusivamente no CEP do destino, como a maioria das tabelas dos correios e algumas da Braspress, por exemplo.
Também é possível associar no sistema as faixas de CEP de cada cidade.
Nesses casos, a informação do CEP de origem/destino é suficiente para o cálculo do frete/simulação.
{
"tipo": 6,
"cep": 12308020
}
Informações sobre os produtos a serem transportados
Os parâmetros abaixo informam as características principais dos produtos a serem transportados, e são as principais variáveis (além da origem/destino) para o cálculo do frete.
Os dados que não forem referenciados nas tabelas são opcionais.
"qtdVolumes": <quantidade total de volumes a serem transportados>,
"volume": <volume dos produtos, em metros cúbicos>,
"peso": <peso total dos produtos, em kgs>,
"valorMercadoria": <valor total dos produtos>
Parâmetros adicionais para a simulação
compraOuVenda: Deve sempre ser informado com o valor fixo = 1.
retornarApenasNPrimeiras: Parâmetro opcional para restringir a quantidade de cotações / cenários a serem retornados para o sistema chamador.
destinatario: Opcional. Algumas transportadoras cobram taxas adicionais para entrega em alguns destinatários (supermercados, por exemplo, onde as entregas são sujeitas a restrições de horários ou filas para recebimento). Nesses casos é importante que o destinatário final seja informado para que essas situações sejam levadas em consideração.
"compraOuVenda": 1,
"retornarApenasNPrimeiras": <Quantidade de cotações a retornar>,
"destinatario": {
"cpfCnpj": {
"tipoPessoa": <1=Pessoa física, 2=Pessoa Jurídica>,
"numero": <CPF ou CNPJ do destinatário>
}
}
Filtros complementares
Os filtros abaixo são opcionais, mas podem ser informados para restringir os resultados e dessa forma otimizar a performance dos cálculos
"modal": {
"nome": "<Nome do modal a ser considerado>"
},
"operacao": {
"nome": "<Nome da operação a ser considerada>"
},
"transportadora": {
"pessoa": {
"id": 12345
}
}
Os resultados
Como já foi dito acima, o resultado da simulação que será retornado pelo sistema é uma lista dos possíveis cenários para a operação.
Cada um dos cenários refere-se a uma transportadora/modal/tipo de operação, e vai conter o valor do frete e o prazo estimado para o respectivo cenário.
{
"cotacaoId": <ID da simulação>,
"qtdResultados": <Quantidade de resultados retornados>,
"cenarios": [
{
"cenarioSimulacaoId": 1,
"compraOuVenda": 1,
"transportadora": <Dados da transportadora>,
"modal": <Dados do modal de transporte (aéreo, rodoviário, etc>,
"operacao": <Dados da operação (lotação, fracionada, expressa, etc>,
"valor": <Valor total do frete por esta transportadora>,
"percValorMercadorias": <Percentual do valor do frete sobre o valor dos produtos>,
"descricaoPrazo": "<Prazo estimado para entrega>",
"tempoParaCalculo": <Tempo gasto para o cálculo, em milissegundos>,
},
{
... <Demais resultados> ...
}
]
}
Veja também: