API de Frete Alladino

Começando

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

URL base

Produção

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

Sempre HTTPS

O domínio responde por HTTPS com certificado válido e chamadas em HTTP são redirecionadas. O ERP deve recusar conexão sem TLS.

Responsabilidades

Quem	Faz o quê
ERP	Coleta peso e dimensões do pedido, valida o CEP, chama `POST /cotacoes`, exibe valor e prazo ao cliente e, fechado o pedido, chama `POST /confirmacoes`.
Alladino	Valida 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.

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.

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.

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.

Header

Authorization: Bearer alld_live_sua_chave_aqui
Content-Type: application/json

Prefixo	Ambiente	Para quê
alld_test_	Sandbox	Homologação da integração. Mesmo contrato de resposta da produção.
alld_live_	Produção	Pedidos reais. Emitida pela Alladino quando a integração é aprovada.

A chave fica no servidor

Guarde-a em variável de ambiente, nunca no front-end nem no repositório. Ela dá acesso a cotar e confirmar pedidos na conta. Se suspeitar de vazamento, peça revogação à Alladino — a chave é substituída na hora.

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

Campo	Tipo		Descrição
numero_pedido	string	obrigatório	Identificador 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_origem	string	obrigatório	CEP de saída, 8 dígitos. Pode enviar com hífen — normalizamos.
cep_destino	string	obrigatório	CEP de entrega, 8 dígitos.
peso_kg	number	obrigatório	Peso real da encomenda em quilos. De 0,1 a 30.
altura_cm	number	obrigatório	Altura do volume em centímetros, de 1 a 100.
largura_cm	number	obrigatório	Largura do volume em centímetros, de 1 a 100.
comprimento_cm	number	obrigatório	Comprimento do volume em centímetros, de 1 a 100. A ordem dos três lados não importa.
valor_declarado	number	opcional	Valor 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-10-24T15:46:12.385Z"
}

Campo	Tipo	Descrição
numero_pedido	string	O mesmo identificador enviado na requisição.
transportadora	string	Código da transportadora escolhida. Grave no pedido — a Alladino usa esse código para despachar.
valor	number	Valor final do frete em reais, com duas casas.
prazo_dias	integer	Prazo de entrega em dias úteis. `0` significa entrega no mesmo dia.
modalidade	string	`Express`, `Same Day` ou `Economic`.
cotacao_id	string	UUID desta cotação. Guarde no pedido — é por ele que a equipe Alladino audita qualquer divergência.
expira_em	string	Data/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.

Campo	Tipo		Descrição
numero_pedido	string	obrigatório	O mesmo identificador usado na cotação. É por ele que amarramos a confirmação ao orçamento.
cotacao_id	string	opcional	UUID 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.
confirmado	boolean	opcional	Quando enviado, deve ser `true`. Só existe para deixar a intenção explícita no payload.
transportadora	string	opcional	O código da transportadora, se for diferente do que a cotação devolveu.
destinatario	object	opcional	Quem recebe: `nome`, `documento`, `telefone`, `email` e `endereco` (`cep`, `logradouro`, `numero`, `complemento`, `bairro`, `cidade`, `uf`).
nota_fiscal	object	opcional	Dados fiscais: `numero`, `serie`, `chave`. Se a NF ainda não saiu, mande depois — a etiqueta não depende dela.
observacao	string	opcional	Recado 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-10-24T14:03:51.204Z",
  "mensagem": "Confirmação registrada. A etiqueta é gerada no painel da Alladino."
}

Campo	Tipo	Descrição
status	string	`recebido` — a confirmação entrou na fila da expedição.
protocolo	string	UUID do recebimento. Guarde no pedido: é por ele que a equipe Alladino localiza a confirmação.
recebido_em	string	Data/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.

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.

Campo	Mínimo	Máximo	Erro retornado
peso_kg	0,1 kg	30 kg	`PESO_INVALIDO`
altura_cm	1 cm	100 cm	`DIMENSOES_INVALIDAS`
largura_cm	1 cm	100 cm	`DIMENSOES_INVALIDAS`
comprimento_cm	1 cm	100 cm	`DIMENSOES_INVALIDAS`
altura + largura + comprimento	—	200 cm	`CAIXA_MUITO_GRANDE`
cep_origem / cep_destino	8 dígitos	8 dígitos	`VALIDACAO_FALHOU`
numero_pedido	1 caractere	60 caracteres	`VALIDACAO_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 para decidir o que fazer e error.message para exibir ao operador.

Erroapplication/json

{
  "error": {
    "code": "PESO_INVALIDO",
    "message": "Peso deve estar entre 0.1kg e 30kg"
  }
}

Código	HTTP	Quando acontece	O que fazer
PESO_INVALIDO	400	Peso fora da faixa de 0,1 a 30 kg	Corrigir o peso no pedido e cotar de novo.
DIMENSOES_INVALIDAS	400	Algum lado fora da faixa de 1 a 100 cm	Conferir as medidas do volume.
CAIXA_MUITO_GRANDE	400	Soma das três dimensões acima de 200 cm	Dividir em mais volumes ou usar embalagem menor.
VALIDACAO_FALHOU	400	Campo obrigatório ausente, CEP inválido, JSON malformado ou método diferente de POST	A mensagem nomeia o campo. Corrigir e reenviar.
INVALIDO_CREDENTIALS	401	Header `Authorization` ausente, chave inválida ou revogada	Conferir a chave. Não repetir a chamada em loop.
LIMITE_EXCEDIDO	429	Limite de requisições por hora atingido	Aguardar e repetir com backoff exponencial.
INDISPONIVEL	503	Nenhuma transportadora atende o trecho, ou falha temporária	Repetir em 60 segundos. Persistindo, acionar a Alladino.

Tratamento sugerido

Pseudocódigo

# erros de dados: o operador corrige no pedido
["PESO_INVALIDO", "DIMENSOES_INVALIDAS",
 "CAIXA_MUITO_GRANDE"]:            focar_campo("dimensoes")

# erro de configuração: avisar o time técnico, não o operador
["INVALIDO_CREDENTIALS"]:            alertar_suporte()

# transitórios: repetir com backoff, nunca em loop apertado
["LIMITE_EXCEDIDO", "INDISPONIVEL"]:  repetir_com_backoff(max=3)

Limites e validade

Item	Valor	Observação
Rate limit	1000 req/hora	Por API key, em janela deslizante. Cada resposta traz `X-RateLimit-Limit` e `X-RateLimit-Remaining`.
Validade da cotação	60 minutos	Indicada em `expira_em`. Passado o prazo, cote de novo antes de fechar o pedido.
Tempo de resposta	~1 a 3 s	Inclui o encaminhamento até o motor de cotação. Use timeout de 10 s.
Métodos aceitos	POST	Qualquer outro método devolve 405.

Exemplos de código

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

cURL

curl -X POST https://api.alladino.com.br/api/v1/cotacoes \
  -H "Authorization: Bearer $ALLADINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "numero_pedido": "PED-2026-001",
    "cep_origem": "01310100",
    "cep_destino": "20040020",
    "peso_kg": 0.3,
    "comprimento_cm": 16,
    "largura_cm": 11,
    "altura_cm": 7
  }'

Node.js

const resposta = await fetch(
  "https://api.alladino.com.br/api/v1/cotacoes",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ALLADINO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      numero_pedido: pedido.id,
      cep_origem: deposito.cep,
      cep_destino: pedido.cep_entrega,
      peso_kg: pedido.peso,
      comprimento_cm: volume.comprimento,
      largura_cm: volume.largura,
      altura_cm: volume.altura,
    }),
    signal: AbortSignal.timeout(10000),
  }
);

const dados = await resposta.json();

if (!resposta.ok) {
  // dados.error.code diz o que fazer
  throw new Error(dados.error.message);
}

// dados.transportadora, dados.valor, dados.prazo_dias, dados.cotacao_id

PHP

$ch = curl_init('https://api.alladino.com.br/api/v1/cotacoes');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('ALLADINO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'numero_pedido'  => $pedido->id,
        'cep_origem'     => '01310100',
        'cep_destino'    => $pedido->cepEntrega,
        'peso_kg'        => $pedido->peso,
        'comprimento_cm' => 16,
        'largura_cm'     => 11,
        'altura_cm'      => 7,
    ]),
]);

$corpo   = curl_exec($ch);
$status  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$dados = json_decode($corpo, true);

if ($status !== 200) {
    throw new RuntimeException($dados['error']['message']);
}

Python

import os, requests

resposta = requests.post(
    "https://api.alladino.com.br/api/v1/cotacoes",
    headers={
        "Authorization": f"Bearer {os.environ['ALLADINO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "numero_pedido": pedido.id,
        "cep_origem": "01310100",
        "cep_destino": pedido.cep_entrega,
        "peso_kg": 0.3,
        "comprimento_cm": 16,
        "largura_cm": 11,
        "altura_cm": 7,
    },
    timeout=10,
)

dados = resposta.json()

if resposta.status_code != 200:
    raise RuntimeError(dados["error"]["message"])

# dados["transportadora"], dados["valor"], dados["prazo_dias"]

Começando

URL base

Responsabilidades

Fluxo em um olhar

POST /cotacoes — quanto custa e em quantos dias

O cliente vê o frete e fecha o pedido

POST /confirmacoes — o pedido saiu

Etiqueta, notificações e rastreio

Autenticação

POST /cotacoes

Corpo da requisição

Resposta 200 OK

POST /confirmacoes

Corpo da requisição

Resposta 202 Accepted

Validações

Erros

Tratamento sugerido

Limites e validade

Exemplos de código

`POST /cotacoes` — quanto custa e em quantos dias

`POST /confirmacoes` — o pedido saiu