Alladino · Integração de Fretes

API de Cotação de Frete

Um endpoint. O ERP envia pedido, CEPs, peso e dimensões; a Alladino devolve a transportadora escolhida, o valor e o prazo.

Versãov1
StatusNo ar
Atualizado01/09/2026

Começando

São dois endpoints: um para cotar e outro para confirmar o pedido. O ERP consulta antes de fechar o pedido, mostra valor e prazo ao cliente e grava a transportadora escolhida. A partir daí a Alladino cuida de etiqueta, rastreio e notificações — sem novas chamadas de API.

URL base

Produção
https://api.alladino.com.br/api/v1
Certificado e disponibilidade

O domínio responde por HTTPS com certificado Let's Encrypt válido; chamadas em HTTP são redirecionadas. Use sempre https:// — o ERP deve recusar conexão sem TLS.

Responsabilidades

QuemFaz o quê
ERPColeta peso e dimensões do pedido, valida o CEP, chama POST /cotacoes, exibe valor e prazo ao cliente e cria o pedido com a transportadora escolhida.
AlladinoValida a entrada, consulta as transportadoras habilitadas para a conta, aplica a precificação e devolve a melhor opção. Fechado o pedido, o painel da Alladino gera a etiqueta em PDF, envia as notificações e mantém o rastreio.

Fluxo em um olhar

Duas chamadas do seu lado. O resto acontece dentro da Alladino.

1
ERP → Alladino

POST /cotacoes — quanto custa e em quantos dias

Você manda CEPs, peso e medidas, junto com o seu numero_pedido.

Volta: transportadora, valor, prazo_dias, cotacao_id e expira_em.
2
Dentro do seu sistema

O cliente vê o frete e fecha o pedido

Grave cotacao_id no pedido, junto com transportadora, valor e prazo. A cotação vale 60 minutos — passou disso, cote de novo.

3
ERP → Alladino

POST /confirmacoes — o pedido saiu

Uma chamada curta com o mesmo numero_pedido da cotação, avisando que ele foi fechado. Só esse campo é obrigatório; quanto mais você mandar (destinatário, nota fiscal), menos precisamos buscar depois.

Volta: 202 com um protocolo de recebimento.
Alladino

Etiqueta, notificações e rastreio

A etiqueta é gerada automaticamente no painel da Alladino, o cliente final é avisado a cada mudança de status e o rastreio fica atualizado. Nenhuma chamada de API a mais do seu lado.


Autenticação

Toda requisição precisa de uma API key da Alladino no header Authorization. A chave identifica o parceiro, define quais transportadoras serão consultadas e controla o limite de uso.

Headers obrigatórios
Authorization: Bearer alld_test_5f3c9a17b24e8d6091c7fa3b8e0d2c44
Content-Type: application/json
PrefixoAmbienteComportamento
alld_test_SandboxPara integrar e testar. Cotações reais, mas nenhum pedido é criado e nenhuma etiqueta é emitida.
alld_live_ProduçãoLiberado após o aceite da homologação.
A chave é mostrada uma única vez

Guarde-a como variável de ambiente no servidor. Ela nunca deve ir para o front-end, para o repositório ou para o app do cliente. Se vazar, avise a equipe Alladino: revogamos e emitimos outra na hora, sem downtime da integração.


POST /cotacoes

Recebe os dados da encomenda e devolve a melhor opção de frete disponível para aquele trecho.

POST https://api.alladino.com.br/api/v1/cotacoes

Corpo da requisição

CampoTipoDescrição
numero_pedidostringobrigatórioIdentificador do pedido no seu sistema. Até 60 caracteres. Volta igual na resposta e é a chave que liga a cotação à confirmação — mande o mesmo valor em POST /confirmacoes.
cep_origemstringobrigatórioCEP de saída, 8 dígitos. Pode enviar com hífen — normalizamos.
cep_destinostringobrigatórioCEP de entrega, 8 dígitos.
peso_kgnumberobrigatórioPeso real da encomenda em quilos. De 0,1 a 30.
altura_cmnumberobrigatórioAltura do volume em centímetros, de 1 a 100.
largura_cmnumberobrigatórioLargura do volume em centímetros, de 1 a 100.
comprimento_cmnumberobrigatórioComprimento do volume em centímetros, de 1 a 100. A ordem dos três lados não importa.
valor_declaradonumberopcionalValor da mercadoria em reais, para seguro. Padrão 0.
Requisiçãoapplication/json
{
  "numero_pedido": "PED-2026-001",
  "cep_origem": "01310100",
  "cep_destino": "20040020",
  "peso_kg": 0.3,
  "comprimento_cm": 16,
  "largura_cm": 11,
  "altura_cm": 7
}

Resposta 200 OK

Respostaapplication/json
{
  "numero_pedido": "PED-2026-001",
  "transportadora": "loggi",
  "valor": 12.90,
  "prazo_dias": 2,

  // metadados — úteis para exibição e suporte
  "modalidade": "Express",
  "cotacao_id": "9f2c1e40-77a8-4b1d-9c3e-2f8a6b104d55",
  "expira_em": "2026-09-01T15:46:12.385Z"
}
CampoTipoDescrição
numero_pedidostringO mesmo identificador enviado na requisição.
transportadorastringCódigo da transportadora escolhida. Grave no pedido — a Alladino usa esse código para despachar.
valornumberValor final do frete em reais, com duas casas.
prazo_diasintegerPrazo de entrega em dias úteis. 0 significa entrega no mesmo dia.
modalidadestringExpress, Same Day ou Economic.
cotacao_idstringUUID desta cotação. Guarde no pedido — é por ele que a equipe Alladino audita qualquer divergência.
expira_emstringData/hora ISO-8601 UTC até quando o valor é garantido (60 minutos).
O que a resposta não traz — de propósito

Os detalhes de como o preço foi formado são internos da Alladino: entram no cálculo e ficam no nosso histórico, mas não voltam na resposta. O ERP trabalha com as medidas que enviou e com o valor final.

Campos novos não quebram sua integração

Os quatro primeiros campos são o contrato estável. Podemos acrescentar metadados em versões futuras, então trate campos desconhecidos como ignoráveis em vez de falhar o parsing.


POST /confirmacoes

Avisa a Alladino que o orçamento virou pedido. A partir daí a etiqueta é gerada automaticamente no painel da Alladino — você não precisa pedir, baixar nem chamar mais nada.

POST https://api.alladino.com.br/api/v1/confirmacoes

Corpo da requisição

Só o numero_pedido é obrigatório. Todo o resto é opcional e existe para poupar consulta depois: quanto mais vier aqui, menos precisamos buscar no seu sistema para emitir a etiqueta.

CampoTipoDescrição
numero_pedidostringobrigatórioO mesmo identificador usado na cotação. É por ele que amarramos a confirmação ao orçamento.
cotacao_idstringopcionalUUID devolvido pela cotação. Mais preciso que o numero_pedido quando houve mais de uma cotação para o mesmo pedido — mande os dois se tiver.
confirmadobooleanopcionalQuando enviado, deve ser true. Só existe para deixar a intenção explícita no payload.
transportadorastringopcionalO código da transportadora, se for diferente do que a cotação devolveu.
destinatarioobjectopcionalQuem recebe: nome, documento, telefone, email e endereco (cep, logradouro, numero, complemento, bairro, cidade, uf).
nota_fiscalobjectopcionalDados fiscais: numero, serie, chave. Se a NF ainda não saiu, mande depois — a etiqueta não depende dela.
observacaostringopcionalRecado livre para a expedição. Até 500 caracteres.
Requisiçãoapplication/json
{
  "numero_pedido": "PED-2026-001",
  "confirmado": true,

  // tudo abaixo é opcional
  "cotacao_id": "9f2c1e40-77a8-4b1d-9c3e-2f8a6b104d55",
  "destinatario": {
    "nome": "Maria Souza",
    "documento": "000.000.000-00",
    "telefone": "11999990000",
    "email": "maria@exemplo.com.br",
    "endereco": {
      "cep": "20040020",
      "logradouro": "Av. Rio Branco",
      "numero": "156",
      "complemento": "sala 1201",
      "bairro": "Centro",
      "cidade": "Rio de Janeiro",
      "uf": "RJ"
    }
  },
  "nota_fiscal": { "numero": "123456", "serie": "1" },
  "observacao": "Entregar em horário comercial"
}

Resposta 202 Accepted

Respostaapplication/json
{
  "numero_pedido": "PED-2026-001",
  "status": "recebido",
  "protocolo": "3a71c0de-5f11-4a02-8e6d-9b7c1f204a88",
  "recebido_em": "2026-09-02T14:03:51.204Z",
  "mensagem": "Confirmação registrada. A etiqueta é gerada no painel da Alladino."
}
CampoTipoDescrição
statusstringrecebido — a confirmação entrou na fila da expedição.
protocolostringUUID do recebimento. Guarde no pedido: é por ele que a equipe Alladino localiza a confirmação.
recebido_emstringData/hora ISO-8601 UTC em que a confirmação entrou.
Reenviar é seguro

Se você não tiver certeza de que a confirmação chegou, mande de novo com o mesmo numero_pedido. Cada envio gera um protocolo próprio no histórico e a expedição trabalha com o mais completo — nada é duplicado na etiqueta.

Erros usam o mesmo formato da cotação

400 VALIDACAO_FALHOU quando falta numero_pedido ou um campo veio no formato errado; 401 INVALIDO_CREDENTIALS para chave inválida; 405 para qualquer método diferente de POST.


Validações

A entrada é validada antes de qualquer consulta a transportadora, então erros de dados voltam em milissegundos. Valide também no seu lado para não gastar requisição.

CampoMínimoMáximoErro retornado
peso_kg0,1 kg30 kgPESO_INVALIDO
altura_cm1 cm100 cmDIMENSOES_INVALIDAS
largura_cm1 cm100 cmDIMENSOES_INVALIDAS
comprimento_cm1 cm100 cmDIMENSOES_INVALIDAS
altura + largura + comprimento200 cmCAIXA_MUITO_GRANDE
cep_origem / cep_destino8 dígitos8 dígitosVALIDACAO_FALHOU
numero_pedido1 caractere60 caracteresVALIDACAO_FALHOU
De onde vêm esses limites

Os máximos seguem o limite de encomenda nacional dos Correios: nenhum lado acima de 100 cm, soma das três dimensões até 200 cm e peso até 30 kg. É o teto mais restritivo entre as transportadoras da rede, então um pacote aceito aqui é aceito por todas.


Erros

Todo erro devolve o mesmo formato. Use error.code na lógica do seu sistema e error.message para mostrar ao operador — a mensagem já vem escrita em português, pronta para exibição.

Formato de erroHTTP 400
{
  "error": {
    "code": "PESO_INVALIDO",
    "message": "Peso deve estar entre 0.1kg e 30kg"
  }
}
CódigoHTTPSignificaO que fazer
PESO_INVALIDO400Peso fora da faixa de 0,1 kg a 30 kgFocar o campo de peso do pedido.
DIMENSOES_INVALIDAS400Altura, largura ou comprimento fora de 1 a 150 cmFocar o campo de dimensões. A mensagem diz qual campo falhou.
CAIXA_MUITO_GRANDE400Soma das três dimensões acima de 200 cmDividir em mais volumes ou usar embalagem menor.
VALIDACAO_FALHOU400Campo obrigatório ausente, CEP inválido ou JSON malformadoA mensagem lista os campos. Corrigir e repetir.
INVALIDO_CREDENTIALS401API key ausente, inválida ou revogadaConferir o header. Se persistir, solicitar nova chave.
LIMITE_EXCEDIDO429Passou de 1000 requisições na última horaAguardar e repetir com backoff. Considerar cache por CEP + faixa de peso.
INDISPONIVEL503Nenhuma transportadora atende o trecho, ou falha internaRepetir em 60 segundos. Se insistir, exibir frete a combinar.

Tratamento sugerido

Pseudocódigo
se resposta.status != 200:
    codigo   = resposta.json().error.code
    mensagem = resposta.json().error.message
    mostrar_ao_operador(mensagem)

    se codigo em ["PESO_INVALIDO"]:                 focar_campo("peso")
    se codigo em ["DIMENSOES_INVALIDAS",
                  "CAIXA_MUITO_GRANDE"]:            focar_campo("dimensoes")
    se codigo em ["VALIDACAO_FALHOU"]:              focar_campo("cep")
    se codigo em ["LIMITE_EXCEDIDO",
                  "INDISPONIVEL"]:                  repetir_com_backoff()

Limites e validade

ItemValorObservação
Rate limit1000 req/horaPor API key, em janela deslizante. Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining.
Validade da cotação60 minutosIndicada em expira_em. Passado o prazo, cote de novo antes de fechar o pedido.
Tempo de resposta~1 a 3 sInclui o encaminhamento até o motor de cotação. Sobe quando os Correios são consultados em tempo real. Use timeout de 10 s.
Métodos aceitosPOSTQualquer outro método devolve 405.

Exemplos de código

Mesma chamada em quatro linguagens. Troque apenas a chave e o corpo.

export ALLADINO_URL="https://api.alladino.com.br/api/v1"
export ALLADINO_TOKEN="alld_test_sua_chave_aqui"

curl -X POST "$ALLADINO_URL/cotacoes" \
  -H "Authorization: Bearer $ALLADINO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "numero_pedido": "TEST-001",
    "cep_origem": "01310100",
    "cep_destino": "20040020",
    "peso_kg": 0.3,
    "comprimento_cm": 16,
    "largura_cm": 11,
    "altura_cm": 7
  }'