Portal do Transportador — Cotação Documentação da API v1

Manual de integração da API de cotação

Integre seu sistema (ERP, TMS, e-commerce ou planilha) ao Portal do Transportador e receba, em JSON, os valores e prazos de frete aéreo para qualquer CEP do Brasil, em tempo real.

REST + JSON UTF-8 Autenticação por token GET e POST Aéreo API + Aéreo Próprio Origem padrão: NED01

1Início rápido

1
Crie seu tokenCadastre a empresa em POST /v1/cadastro (ou no portal) e receba o token na hora.
2
Teste a conexãoChame GET /v1/status com o token para confirmar o acesso.
3
Peça a cotaçãoEnvie CEPs, volumes e valor da carga para /v1/cotacao.
4
Use o resultadoCada modelo vem separado em modelos; todos juntos em servicos[], do menor para o maior valor.

Teste agora pelo navegador

Troque SEU_TOKEN pelo token recebido e cole o endereço abaixo na barra do navegador:

https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao?token=SEU_TOKEN&cep_origem=74853010&cep_destino=01310100&valor_carga=1500&tipo_entrega=domicilio&altura=20&largura=20&comprimento=20&peso=1&quantidade=1

2Endereço e formato

ItemValor
URL basehttps://www.mapcloud.com.br/globalstar/azul/api.php
Versãov1 (faz parte do caminho: /v1/...)
FormatoJSON, codificação UTF-8 (Content-Type: application/json)
ProtocoloHTTPS
CORSLiberado (Access-Control-Allow-Origin: *), mas recomendamos chamar pelo seu servidor para não expor o token
DatasISO 8601 com fuso de Brasília, ex.: 2026-10-07T15:22:47-03:00
ValoresEm reais (BRL), número com ponto decimal, ex.: 181.4
Endereço alternativoSe o seu servidor ou proxy não aceitar caminhos depois do .php, use o parâmetro r: api.php?r=v1/cotacao funciona exatamente como api.php/v1/cotacao.

3Autenticação

As chamadas de cotação e status precisam do token. Para obtê-lo, crie a conta em POST /v1/cadastro (ou pelo portal). O token pode ser enviado de quatro formas (use apenas uma):

FormaExemploRecomendado para
Cabeçalho X-API-KeyX-API-Key: SEU_TOKENProdução (preferencial)
Cabeçalho AuthorizationAuthorization: Bearer SEU_TOKENProdução
Campo no JSON{"token": "SEU_TOKEN", ...}Sistemas que não permitem cabeçalhos
Parâmetro na URL?token=SEU_TOKENSomente testes no navegador
Proteja seu tokenToken na URL fica gravado no histórico do navegador e em logs de servidores. Em produção, envie sempre pelo cabeçalho e nunca coloque o token em código JavaScript que roda no navegador do seu cliente.

4Criar conta e token

POST/v1/cadastrosem token

Cria a conta da empresa com os mesmos dados do formulário de cadastro do portal (incluindo usuário e senha) e devolve o token pronto para cotar. Aceita JSON ou formulário (application/x-www-form-urlencoded). Somente POST: a senha nunca deve ir na URL.

CampoTipoDescrição
cnpjtextoobrigatórioCNPJ da empresa (14 números; pontuação é ignorada). Os dígitos verificadores são conferidos. Um cadastro por CNPJ.
razao_socialtextoobrigatório*Razão social. *Se não for enviada, buscamos pelo CNPJ na consulta pública (também completa fantasia, cidade, UF, CEP e telefone que faltarem).
nome_fantasiatextoopcionalNome fantasia.
cidadetextoopcionalCidade da empresa.
uftextoopcionalUF com 2 letras (ex.: GO).
ceptextoopcionalCEP com 8 números.
responsaveltextoobrigatórioNome do responsável pela integração.
telefonetextoopcionalTelefone de contato.
emailtextoobrigatórioE-mail válido. Também pode ser usado como login.
usuariotextoobrigatórioLogin de 4 a 80 caracteres (letras minúsculas, números, ponto, hífen, @). Único.
senhatextoobrigatórioMínimo de 8 caracteres. Guardada criptografada.
senha2textoopcionalConfirmação. Se enviada, precisa ser igual à senha.
curl -X POST "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cadastro" \
  -H "Content-Type: application/json" \
  -d '{
    "cnpj": "12.345.678/0001-95",
    "razao_social": "Loja Exemplo LTDA",
    "nome_fantasia": "Loja Exemplo",
    "cidade": "Goiânia",
    "uf": "GO",
    "cep": "74853-010",
    "responsavel": "João da Silva",
    "telefone": "(62) 99999-0000",
    "email": "ti@lojaexemplo.com.br",
    "usuario": "loja.integracao",
    "senha": "SenhaForte2026"
  }'

Resposta 201:

{
  "sucesso": true,
  "token": "ptk_c876fed75487555a0f733ae07542c5559b29c606",
  "token_prefixo": "ptk_c876fed7",
  "aviso": "Guarde o token agora: por segurança ele não é exibido novamente. Envie-o no cabeçalho X-API-Key.",
  "cliente": {
    "id": 8, "cnpj": "12345678000195", "razao_social": "Loja Exemplo LTDA", "nome_fantasia": "Loja Exemplo",
    "cidade": "Goiânia", "uf": "GO", "responsavel": "João da Silva", "email": "ti@lojaexemplo.com.br",
    "telefone": "62999990000", "usuario": "loja.integracao", "criado_em": "2026-10-07 15:52:24",
    "chave_prefixo": "ptk_c876fed7", "chave_gerada_em": "2026-10-07 15:52:24"
  },
  "endpoints": {
    "cotacao": "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao",
    "cotacao_alternativo": "https://www.mapcloud.com.br/globalstar/azul/api.php?r=v1/cotacao",
    "status": "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/status",
    "novo_token": "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/token"
  },
  "limite_minuto": 60,
  "unidade_origem": "NED01"
}
HTTPQuando
201Conta criada; o token vem no campo token.
405Chamada sem POST.
409Usuário ou CNPJ já cadastrados (use /v1/token para gerar um novo token).
422Campos inválidos ou faltando (veja erros[].campo).
429Mais de 10 cadastros/pedidos de token por hora do mesmo endereço IP.
O token aparece uma única vezGuardamos apenas uma assinatura dele. Se perder, gere outro em /v1/token ou no portal.

5Gerar novo token

POST/v1/tokensem token

Para quem já tem conta: envie usuário (ou e-mail) e senha e receba um token novo. O token anterior deixa de funcionar na hora. A resposta tem o mesmo formato do cadastro.

curl -X POST "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/token" \
  -H "Content-Type: application/json" \
  -d '{"usuario": "loja.integracao", "senha": "SenhaForte2026"}'

Respostas: 200 token gerado · 401 usuário ou senha incorretos · 403 conta desativada · 429 muitas tentativas.

6Testar conexão

GET/v1/status

Confirma que o token é válido. Não gera cotação.

curl -H "X-API-Key: SEU_TOKEN" \
  https://www.mapcloud.com.br/globalstar/azul/api.php/v1/status
{
  "sucesso": true,
  "versao": "v1",
  "cliente": "Integração (token fixo)",
  "cnpj": null,
  "data": "2026-10-07T15:22:47-03:00"
}

7Cotar frete

POST/v1/cotacao

Envie o pedido de cotação no corpo da requisição, em JSON:

POST /globalstar/azul/api.php/v1/cotacao HTTP/1.1
Host: www.mapcloud.com.br
X-API-Key: SEU_TOKEN
Content-Type: application/json

{
  "cep_origem": "74853010",
  "cep_destino": "01310100",
  "valor_carga": 1500.00,
  "tipo_entrega": "domicilio",
  "coleta": false,
  "tomador_cnpj": "12345678000199",
  "volumes": [
    { "altura": 20, "largura": 20, "comprimento": 20, "peso": 1, "quantidade": 2 },
    { "altura": 40, "largura": 30, "comprimento": 50, "peso": 8.5 }
  ]
}

Para um único volume, os campos do volume também podem ir direto na raiz do JSON, sem a lista volumes:

{ "cep_origem": "74853010", "cep_destino": "01310100", "valor_carga": 1500,
  "altura": 20, "largura": 20, "comprimento": 20, "peso": 1 }

8Parâmetros da cotação

CampoTipoDescrição
cep_origemtextoobrigatórioCEP de onde a carga sai, 8 números. Pontos e traço são ignorados (74853-010 também vale).
cep_destinotextoobrigatórioCEP de entrega, 8 números.
volumeslistaobrigatórioUm ou mais volumes (ver tabela abaixo). Máximo de 100 volumes somando as quantidades.
valor_carganúmeroopcionalValor da mercadoria (nota fiscal) em reais. Usado no seguro (ad-valorem) e GRIS. Padrão: 0. Recomendado sempre informar.
tipo_entregatextoopcionaldomicilio (entrega no endereço, padrão) ou balcao (retirada pelo destinatário na unidade; também aceita retirada ou aeroporto).
coletabooleanoopcionaltrue para incluir coleta no endereço do remetente. Padrão: false.
tomador_cnpjtextoopcionalCNPJ (14) ou CPF (11) de quem paga o frete. Fica registrado na cotação.
nfe_chavetextoopcionalChave da NF-e (44 números), para vincular a cotação à nota.
fontetextoopcionalModelo de cotação: ambas (padrão – os dois), api (Cotação Aéreo API) ou tabela (Cotação Aéreo Próprio). Ver modelos.

Campos de cada volume

CampoTipoDescrição
pesonúmeroobrigatórioPeso de uma unidade, em kg. Maior que zero.
alturanúmeroopcionalEm centímetros. Necessário para calcular o peso cubado.
larguranúmeroopcionalEm centímetros.
comprimentonúmeroopcionalEm centímetros.
quantidadeinteiroopcionalQuantos volumes iguais a este. Padrão: 1.
NúmerosAceitamos 1.5, "1,5" e "1.234,56". Prefira número JSON com ponto decimal.

9Cotação via URL (GET)

GET/v1/cotacao?token=...&cep_origem=...&cep_destino=...&peso=...

Os mesmos parâmetros podem ir na URL. Ideal para testes rápidos ou para sistemas que só fazem GET. A resposta é idêntica à do POST.

  • Um volume: altura, largura, comprimento, peso e quantidade direto na URL.
  • Vários volumes: parâmetro volumes com a lista em JSON, ex.: volumes=[{"altura":20,"largura":20,"comprimento":20,"peso":1,"quantidade":2}] (codificado na URL).
  • coleta: use 1, true ou sim.
https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao?token=SEU_TOKEN&cep_origem=74853010&cep_destino=01310100&valor_carga=1500&tipo_entrega=domicilio&altura=20&largura=20&comprimento=20&peso=1&quantidade=1&fonte=ambas

10Modelos de cotação

A API cota por dois modelos diferentes. Por padrão (fonte=ambas) os dois são calculados e devolvidos juntos, cada um no seu bloco dentro de modelos:

ModeloChave na respostafonteComo é calculado
Cotação Aéreo APImodelos.aereo_apiapiConsulta online a tarifa da companhia aérea no momento do pedido. Traz prazo_dias e a composição informada pela companhia (frete, ad valorem, taxas).
Cotação Aéreo Própriomodelos.aereo_propriotabelaCalculada pelas tabelas de frete próprias contratadas: frete peso pela faixa do peso taxado + ad-valorem/GRIS + entrega domiciliar (quando aplicável). Considera a unidade de origem NED01.

Escolha com o parâmetro fonte:

  • ambas (padrão): os dois modelos.
  • api (ou aereo_api): só Cotação Aéreo API.
  • tabela (ou proprio / aereo_proprio): só Cotação Aéreo Próprio.

Cada bloco em modelos traz:

CampoDescrição
nome"Cotação Aéreo API" ou "Cotação Aéreo Próprio".
fonteapi ou tabela.
descricaoComo o valor foi obtido.
sucessofalse se aquele modelo não conseguiu cotar (o outro continua valendo).
cotacao_idNúmero da cotação daquele modelo.
menor_valorMenor valor do modelo.
servicos[]Serviços do modelo, do mais barato para o mais caro.
indisponiveis[]Serviços do modelo que não atendem o trecho.
erros[]Mensagens quando o modelo falhou.
Os dois de uma vez, com segurançaSe um dos modelos falhar (ex.: companhia sem resposta), a cotação continua com 200 e o outro modelo; o bloco que falhou vem com sucesso: false e o motivo em erros.

11Resposta

Em caso de sucesso, a API devolve 200 com a lista de serviços disponíveis, já ordenada do menor para o maior valor:

{
  "sucesso": true,
  "cotacao_id": 32,
  "data": "2026-10-07T15:22:47-03:00",
  "origem":  { "cep": "74853010", "cidade": "Goiânia", "uf": "GO" },
  "destino": { "cep": "01310100", "cidade": "São Paulo", "uf": "SP" },
  "unidade_origem": "NED01",
  "tipo_entrega": "domicilio",
  "coleta": false,
  "valor_carga": 1500,
  "peso_real": 1,
  "peso_cubado": 1.333,
  "peso_taxado": 1.333,
  "volumes": 1,
  "tomador_cnpj": null,
  "fonte": "ambas",
  "menor_valor": 29.41,
  "modelos": {
    "aereo_proprio": {
      "nome": "Cotação Aéreo Próprio",
      "fonte": "tabela",
      "descricao": "Calculada pelas tabelas de frete próprias contratadas (frete peso, ad-valorem/GRIS e entrega).",
      "sucesso": true,
      "cotacao_id": 31,
      "menor_valor": 29.41,
      "servicos": [
        {
          "modal": "Aéreo", "servico": "E-commerce", "codigo": "ECOMM", "valor": 29.41, "moeda": "BRL",
          "prazo_dias": null, "unidade_origem": "NED01", "unidade_destino": null,
          "fonte": "tabela", "fonte_nome": "Cotação Aéreo Próprio",
          "composicao": [ { "item": "Frete peso", "valor": 23.41 }, { "item": "Ad-valorem + GRIS", "valor": 6 } ],
          "observacoes": [ "Tarifa já inclui entrega domiciliar; emissão e capatazia inclusas." ]
        }
      ],
      "indisponiveis": [],
      "erros": []
    },
    "aereo_api": {
      "nome": "Cotação Aéreo API",
      "fonte": "api",
      "descricao": "Tarifa consultada online na companhia aérea no momento da cotação.",
      "sucesso": true,
      "cotacao_id": 32,
      "menor_valor": 95.1,
      "servicos": [ /* Expresso 95,10 e Frete Padrão 181,40 – mesmo formato abaixo */ ],
      "indisponiveis": [],
      "erros": []
    }
  },
  "servicos": [ /* todos os serviços dos dois modelos, do menor para o maior valor */
    {
      "modal": "Aéreo",
      "servico": "Expresso",
      "codigo": "EXP",
      "valor": 95.1,
      "moeda": "BRL",
      "prazo_dias": 1,
      "unidade_origem": "NED01",
      "unidade_destino": null,
      "fonte": "api",
      "fonte_nome": "Cotação Aéreo API",
      "composicao": [ { "item": "Frete", "valor": 95.1 } ],
      "observacoes": []
    },
    {
      "modal": "Aéreo",
      "servico": "Frete Padrão",
      "codigo": "STD",
      "valor": 181.4,
      "moeda": "BRL",
      "prazo_dias": 3,
      "unidade_origem": "NED01",
      "unidade_destino": null,
      "fonte": "api",
      "fonte_nome": "Cotação Aéreo API",
      "composicao": [
        { "item": "Valor Frete", "valor": 174.2 },
        { "item": "Valor Ad Valorem", "valor": 4 },
        { "item": "Taxa Coleta", "valor": 3.2 }
      ],
      "observacoes": []
    }
  ],
  "indisponiveis": [],
  "avisos": []
}

Valores ilustrativos.

Campos principais

CampoDescrição
sucessotrue quando a cotação foi feita.
cotacao_idNúmero da cotação no Portal (do modelo Aéreo API quando houver). Cada modelo tem o seu em modelos.*.cotacao_id.
origem / destinoCEP, cidade e UF identificados.
unidade_origemUnidade de embarque usada no cálculo (padrão NED01).
peso_realSoma dos pesos informados (kg).
peso_cubadoPeso calculado pelas medidas (kg). Ver regras de cálculo.
peso_taxadoO maior entre o real e o cubado. É o peso cobrado.
volumesTotal de volumes considerados (soma das quantidades).
fonteModelo(s) pedido(s): ambas, api ou tabela.
menor_valorValor do serviço mais barato entre todos os modelos, ou null se nenhum estiver disponível.
modelosResultado separado por modelo: aereo_api e/ou aereo_proprio. Ver modelos de cotação.
servicos[]Todos os serviços disponíveis (dos dois modelos), do mais barato para o mais caro.
indisponiveis[]Serviços que não atendem o trecho, com servico, fonte e motivo.
avisos[]Mensagens informativas (ex.: uma das fontes não respondeu quando fonte=ambas).

Cada item de servicos[]

CampoDescrição
modalModal de transporte (Aéreo).
servicoNome comercial: E-commerce, Expresso ou Frete Padrão.
codigoCódigo interno do serviço (ex.: ECOMM, EXP, STD). Use-o para identificar o serviço na sua integração.
valorValor total do frete em reais.
moedaSempre BRL.
prazo_diasPrazo estimado em dias úteis, quando informado (null quando não houver).
unidade_destinoUnidade de destino escolhida, quando conhecida.
fonte / fonte_nomeapi = Cotação Aéreo API · tabela = Cotação Aéreo Próprio.
composicao[]Detalhamento do valor (frete peso, ad-valorem, GRIS, taxas…).
observacoes[]Observações sobre o serviço.

12Erros e códigos HTTP

Quando algo dá errado, sucesso vem false e a lista erros diz o que corrigir. O campo campo indica qual parâmetro causou o problema (ou null).

{
  "sucesso": false,
  "erros": [
    { "campo": "cep_origem", "mensagem": "Informe o CEP de origem com 8 números." },
    { "campo": "volumes[0].peso", "mensagem": "Informe o peso (kg) do volume." }
  ]
}
HTTPSignificadoO que fazer
200Cotação feita.Use servicos[].
401Token ausente, inválido ou revogado.Confira o token e a forma de envio.
404Rota não encontrada.Confira o caminho (/v1/cotacao) ou use ?r=v1/cotacao.
405Método não aceito (GET sem parâmetros).Use POST com JSON, ou GET com os parâmetros na URL.
409Cadastro: usuário ou CNPJ já existe.Use /v1/token com usuário e senha.
422Dados inválidos (CEP, peso, tipo de entrega…).Corrija os campos indicados em erros. Não repita sem corrigir.
429Limite de requisições por minuto atingido.Aguarde alguns segundos e tente de novo.
502Não foi possível cotar o trecho no momento (CEP não encontrado, companhia sem resposta…).Leia a mensagem; tente novamente mais tarde ou com fonte=tabela.
503Serviço temporariamente indisponível.Tente novamente em alguns minutos.

Mensagens mais comuns

MensagemCausa
Envie sua chave no cabeçalho X-API-Key.Nenhum token foi enviado.
Chave inválida ou revogada.Token digitado errado ou desativado.
Informe o CEP de origem/destino com 8 números.CEP incompleto.
CEP de destino inválido ou não encontrado.CEP inexistente nos Correios.
Envie ao menos um volume com peso.Faltou volumes (ou peso).
Use "domicilio" ou "balcao".tipo_entrega com valor desconhecido.
Máximo de 100 volumes por cotação.Soma das quantidades acima de 100.

13Exemplos de código

curl -X POST "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao" \
  -H "X-API-Key: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cep_origem": "74853010",
    "cep_destino": "01310100",
    "valor_carga": 1500,
    "tipo_entrega": "domicilio",
    "volumes": [{"altura":20,"largura":20,"comprimento":20,"peso":1,"quantidade":1}]
  }'
<?php
$token = 'SEU_TOKEN';
$pedido = [
    'cep_origem'   => '74853010',
    'cep_destino'  => '01310100',
    'valor_carga'  => 1500,
    'tipo_entrega' => 'domicilio',
    'volumes'      => [
        ['altura' => 20, 'largura' => 20, 'comprimento' => 20, 'peso' => 1, 'quantidade' => 1],
    ],
];

$ch = curl_init('https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 40,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $token, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($pedido),
]);
$resposta = json_decode(curl_exec($ch), true);
$http     = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (!empty($resposta['sucesso'])) {
    foreach ($resposta['servicos'] as $s) {
        echo $s['servico'] . ': R$ ' . number_format($s['valor'], 2, ',', '.') . "\n";
    }
} else {
    foreach ($resposta['erros'] ?? [] as $e) { echo "Erro ($http): " . $e['mensagem'] . "\n"; }
}
// Node.js 18+ (fetch nativo). Rode no servidor, nunca no navegador do cliente.
const resp = await fetch('https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.PORTAL_TOKEN, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    cep_origem: '74853010',
    cep_destino: '01310100',
    valor_carga: 1500,
    tipo_entrega: 'domicilio',
    volumes: [{ altura: 20, largura: 20, comprimento: 20, peso: 1, quantidade: 1 }]
  })
});
const dados = await resp.json();
if (dados.sucesso) {
  dados.servicos.forEach(s => console.log(s.servico, s.valor, s.prazo_dias));
} else {
  console.error(resp.status, dados.erros);
}
import requests

resp = requests.post(
    "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao",
    headers={"X-API-Key": "SEU_TOKEN"},
    json={
        "cep_origem": "74853010",
        "cep_destino": "01310100",
        "valor_carga": 1500,
        "tipo_entrega": "domicilio",
        "volumes": [{"altura": 20, "largura": 20, "comprimento": 20, "peso": 1, "quantidade": 1}],
    },
    timeout=40,
)
dados = resp.json()
if dados.get("sucesso"):
    for s in dados["servicos"]:
        print(s["servico"], s["valor"], s["prazo_dias"])
else:
    print(resp.status_code, dados.get("erros"))
using System.Net.Http;
using System.Text;

var http = new HttpClient { Timeout = TimeSpan.FromSeconds(40) };
http.DefaultRequestHeaders.Add("X-API-Key", "SEU_TOKEN");

var json = @"{
  ""cep_origem"": ""74853010"",
  ""cep_destino"": ""01310100"",
  ""valor_carga"": 1500,
  ""tipo_entrega"": ""domicilio"",
  ""volumes"": [{""altura"":20,""largura"":20,""comprimento"":20,""peso"":1,""quantidade"":1}]
}";

var resp = await http.PostAsync(
    "https://www.mapcloud.com.br/globalstar/azul/api.php/v1/cotacao",
    new StringContent(json, Encoding.UTF8, "application/json"));
Console.WriteLine((int)resp.StatusCode);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

14Regras de cálculo

Peso cubado e peso taxado

No transporte aéreo, cobra-se pelo maior valor entre o peso real e o peso cubado (espaço ocupado no avião):

peso_cubado (kg) = altura (cm) × largura (cm) × comprimento (cm) ÷ 6.000   // por volume
peso_taxado      = maior entre peso_real total e peso_cubado total

Exemplo: caixa de 20 × 20 × 20 cm com 1 kg → cubado = 8.000 ÷ 6.000 = 1,333 kg. Peso taxado: 1,333 kg.

Sem medidas?Se altura, largura ou comprimento não forem enviados, a cotação usa apenas o peso real. O valor pode mudar na hora do embarque, quando a carga for medida, então envie sempre as medidas.

Unidade de origem

Todas as cotações pela API partem da unidade NED01. O cep_origem continua obrigatório: ele identifica o remetente e é usado em coleta e documentação.

Entrega e coleta

  • domicilio: entregue no endereço do CEP de destino (inclui a taxa de entrega quando aplicável).
  • balcao: o destinatário retira na unidade de destino. Costuma ser mais barato.
  • coleta: quando true, inclui a taxa de coleta no endereço do remetente.

Seguro (ad-valorem) e GRIS

Calculados sobre valor_carga. Informe o valor real da nota fiscal; carga sem valor declarado pode ficar sem cobertura.

Validade

A cotação reflete as tarifas do momento da consulta. Valores e prazos são confirmados na emissão do conhecimento (AWB).

15Limites

LimiteValor
Cotações por minuto, por token60 (acima disso, HTTP 429)
Cadastros e pedidos de token (/v1/cadastro, /v1/token)10 por hora por endereço IP
Volumes por cotação100 (somando as quantidades)
Tempo de respostaNormalmente de 1 a 10 segundos. Configure timeout de pelo menos 40 segundos.

16Boas práticas

  • Chame pelo servidor. Seu site ou app chama o seu backend, que chama a API com o token. Assim o token nunca aparece para o público.
  • Envie medidas e valor da carga. Sem eles a cotação fica imprecisa.
  • Use o codigo do serviço para identificar a opção escolhida. O nome exibido pode mudar.
  • Guarde o cotacao_id junto ao pedido. Ele facilita o atendimento.
  • Trate os erros pelo código HTTP: 422 = corrigir os dados; 429, 502 e 503 = tentar de novo depois (com espera crescente: 2 s, 4 s, 8 s…).
  • Cache curto: no carrinho de compras, reaproveite a mesma cotação por alguns minutos para os mesmos CEPs e volumes.
  • Mantenha-se em UTF-8 e trate os campos novos que possam surgir na resposta sem quebrar a integração.

17Dúvidas frequentes

Qual a diferença entre Aéreo API e Aéreo Próprio?

O Aéreo API (fonte=api) consulta a tarifa online da companhia aérea no momento; o Aéreo Próprio (fonte=tabela) usa as tabelas de frete contratadas. Por padrão você recebe os dois em modelos, e pode escolher qual oferecer ao seu cliente.

Perdi o token. E agora?

Chame POST /v1/token com usuário e senha (ou use o portal) para gerar outro. O antigo para de funcionar.

Por que um serviço não aparece?

Ele pode não atender o trecho ou o peso. Veja a lista indisponiveis, que traz o motivo.

Posso testar sem programar?

Sim. Use a cotação via URL no navegador, ou ferramentas como Postman e Insomnia.

A cotação gera algum envio?

Não. A cotação apenas calcula valores. A emissão do embarque é feita pelo Portal do Transportador.

Recebi 401 mesmo com o token certo.

Verifique espaços antes ou depois do token e se o cabeçalho está escrito exatamente X-API-Key. Alguns servidores removem o cabeçalho Authorization; nesse caso use X-API-Key.