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.
1Início rápido
POST /v1/cadastro (ou no portal) e receba o token na hora.GET /v1/status com o token para confirmar o acesso./v1/cotacao.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
| Item | Valor |
|---|---|
| URL base | https://www.mapcloud.com.br/globalstar/azul/api.php |
| Versão | v1 (faz parte do caminho: /v1/...) |
| Formato | JSON, codificação UTF-8 (Content-Type: application/json) |
| Protocolo | HTTPS |
| CORS | Liberado (Access-Control-Allow-Origin: *), mas recomendamos chamar pelo seu servidor para não expor o token |
| Datas | ISO 8601 com fuso de Brasília, ex.: 2026-10-07T15:22:47-03:00 |
| Valores | Em reais (BRL), número com ponto decimal, ex.: 181.4 |
.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):
| Forma | Exemplo | Recomendado para |
|---|---|---|
Cabeçalho X-API-Key | X-API-Key: SEU_TOKEN | Produção (preferencial) |
Cabeçalho Authorization | Authorization: Bearer SEU_TOKEN | Produção |
| Campo no JSON | {"token": "SEU_TOKEN", ...} | Sistemas que não permitem cabeçalhos |
| Parâmetro na URL | ?token=SEU_TOKEN | Somente testes no navegador |
4Criar conta e 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.
| Campo | Tipo | Descrição | |
|---|---|---|---|
cnpj | texto | obrigatório | CNPJ da empresa (14 números; pontuação é ignorada). Os dígitos verificadores são conferidos. Um cadastro por CNPJ. |
razao_social | texto | obrigató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_fantasia | texto | opcional | Nome fantasia. |
cidade | texto | opcional | Cidade da empresa. |
uf | texto | opcional | UF com 2 letras (ex.: GO). |
cep | texto | opcional | CEP com 8 números. |
responsavel | texto | obrigatório | Nome do responsável pela integração. |
telefone | texto | opcional | Telefone de contato. |
email | texto | obrigatório | E-mail válido. Também pode ser usado como login. |
usuario | texto | obrigatório | Login de 4 a 80 caracteres (letras minúsculas, números, ponto, hífen, @). Único. |
senha | texto | obrigatório | Mínimo de 8 caracteres. Guardada criptografada. |
senha2 | texto | opcional | Confirmaçã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"
}| HTTP | Quando |
|---|---|
| 201 | Conta criada; o token vem no campo token. |
| 405 | Chamada sem POST. |
| 409 | Usuário ou CNPJ já cadastrados (use /v1/token para gerar um novo token). |
| 422 | Campos inválidos ou faltando (veja erros[].campo). |
| 429 | Mais de 10 cadastros/pedidos de token por hora do mesmo endereço IP. |
/v1/token ou no portal.5Gerar novo 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
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
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
| Campo | Tipo | Descrição | |
|---|---|---|---|
cep_origem | texto | obrigatório | CEP de onde a carga sai, 8 números. Pontos e traço são ignorados (74853-010 também vale). |
cep_destino | texto | obrigatório | CEP de entrega, 8 números. |
volumes | lista | obrigatório | Um ou mais volumes (ver tabela abaixo). Máximo de 100 volumes somando as quantidades. |
valor_carga | número | opcional | Valor da mercadoria (nota fiscal) em reais. Usado no seguro (ad-valorem) e GRIS. Padrão: 0. Recomendado sempre informar. |
tipo_entrega | texto | opcional | domicilio (entrega no endereço, padrão) ou balcao (retirada pelo destinatário na unidade; também aceita retirada ou aeroporto). |
coleta | booleano | opcional | true para incluir coleta no endereço do remetente. Padrão: false. |
tomador_cnpj | texto | opcional | CNPJ (14) ou CPF (11) de quem paga o frete. Fica registrado na cotação. |
nfe_chave | texto | opcional | Chave da NF-e (44 números), para vincular a cotação à nota. |
fonte | texto | opcional | Modelo 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
| Campo | Tipo | Descrição | |
|---|---|---|---|
peso | número | obrigatório | Peso de uma unidade, em kg. Maior que zero. |
altura | número | opcional | Em centímetros. Necessário para calcular o peso cubado. |
largura | número | opcional | Em centímetros. |
comprimento | número | opcional | Em centímetros. |
quantidade | inteiro | opcional | Quantos volumes iguais a este. Padrão: 1. |
1.5, "1,5" e "1.234,56". Prefira número JSON com ponto decimal.9Cotação via URL (GET)
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,pesoequantidadedireto na URL. - Vários volumes: parâmetro
volumescom a lista em JSON, ex.:volumes=[{"altura":20,"largura":20,"comprimento":20,"peso":1,"quantidade":2}](codificado na URL). coleta: use1,trueousim.
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:
| Modelo | Chave na resposta | fonte | Como é calculado |
|---|---|---|---|
| Cotação Aéreo API | modelos.aereo_api | api | Consulta 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óprio | modelos.aereo_proprio | tabela | Calculada 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(ouaereo_api): só Cotação Aéreo API.tabela(ouproprio/aereo_proprio): só Cotação Aéreo Próprio.
Cada bloco em modelos traz:
| Campo | Descrição |
|---|---|
nome | "Cotação Aéreo API" ou "Cotação Aéreo Próprio". |
fonte | api ou tabela. |
descricao | Como o valor foi obtido. |
sucesso | false se aquele modelo não conseguiu cotar (o outro continua valendo). |
cotacao_id | Número da cotação daquele modelo. |
menor_valor | Menor 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. |
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
| Campo | Descrição |
|---|---|
sucesso | true quando a cotação foi feita. |
cotacao_id | Número da cotação no Portal (do modelo Aéreo API quando houver). Cada modelo tem o seu em modelos.*.cotacao_id. |
origem / destino | CEP, cidade e UF identificados. |
unidade_origem | Unidade de embarque usada no cálculo (padrão NED01). |
peso_real | Soma dos pesos informados (kg). |
peso_cubado | Peso calculado pelas medidas (kg). Ver regras de cálculo. |
peso_taxado | O maior entre o real e o cubado. É o peso cobrado. |
volumes | Total de volumes considerados (soma das quantidades). |
fonte | Modelo(s) pedido(s): ambas, api ou tabela. |
menor_valor | Valor do serviço mais barato entre todos os modelos, ou null se nenhum estiver disponível. |
modelos | Resultado 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[]
| Campo | Descrição |
|---|---|
modal | Modal de transporte (Aéreo). |
servico | Nome comercial: E-commerce, Expresso ou Frete Padrão. |
codigo | Código interno do serviço (ex.: ECOMM, EXP, STD). Use-o para identificar o serviço na sua integração. |
valor | Valor total do frete em reais. |
moeda | Sempre BRL. |
prazo_dias | Prazo estimado em dias úteis, quando informado (null quando não houver). |
unidade_destino | Unidade de destino escolhida, quando conhecida. |
fonte / fonte_nome | api = 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." }
]
}| HTTP | Significado | O que fazer |
|---|---|---|
| 200 | Cotação feita. | Use servicos[]. |
| 401 | Token ausente, inválido ou revogado. | Confira o token e a forma de envio. |
| 404 | Rota não encontrada. | Confira o caminho (/v1/cotacao) ou use ?r=v1/cotacao. |
| 405 | Método não aceito (GET sem parâmetros). | Use POST com JSON, ou GET com os parâmetros na URL. |
| 409 | Cadastro: usuário ou CNPJ já existe. | Use /v1/token com usuário e senha. |
| 422 | Dados inválidos (CEP, peso, tipo de entrega…). | Corrija os campos indicados em erros. Não repita sem corrigir. |
| 429 | Limite de requisições por minuto atingido. | Aguarde alguns segundos e tente de novo. |
| 502 | Nã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. |
| 503 | Serviço temporariamente indisponível. | Tente novamente em alguns minutos. |
Mensagens mais comuns
| Mensagem | Causa |
|---|---|
| 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 totalExemplo: caixa de 20 × 20 × 20 cm com 1 kg → cubado = 8.000 ÷ 6.000 = 1,333 kg. Peso taxado: 1,333 kg.
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
| Limite | Valor |
|---|---|
| Cotações por minuto, por token | 60 (acima disso, HTTP 429) |
Cadastros e pedidos de token (/v1/cadastro, /v1/token) | 10 por hora por endereço IP |
| Volumes por cotação | 100 (somando as quantidades) |
| Tempo de resposta | Normalmente 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
codigodo serviço para identificar a opção escolhida. O nome exibido pode mudar. - Guarde o
cotacao_idjunto 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.