Integre seus sistemas à plataforma Lanet

Autenticação (HMAC-SHA256)

Toda requisição leva três headers:

String canônica (quatro linhas unidas por \n, sem \n final):

<timestamp>
<MÉTODO em maiúsculas>
<path?query exatamente como enviado, ex.: /v1/consultas ou /v1/eventos?desde=2026-09-01T00:00:00Z>
<sha256 hex minúsculo do corpo bruto; para corpo vazio, sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855>

O servidor assina o corpo bruto recebido (bytes), portanto envie exatamente os bytes que assinou (espaços, ordem de chaves e Unicode fazem parte da assinatura). A comparação é em tempo constante.

Idempotência

Idempotency-Key (≤ 128 caracteres) é obrigatório em POST (GETs não usam) e é único por integração — vale para todas as chaves da integração, inclusive durante a graça de uma rotação: repetir a mesma chave com o mesmo corpo, por qualquer credencial da integração, devolve a mesma resposta (uma única cobrança, header Idempotent-Replayed: true); a mesma chave com corpo diferente responde 422 LAN-422-IDEMPOTENCY-REUSE. Chaves expiram após 24 h.

Requisições GET (polling e replay)

Em GET /v1/consultas/{id} e GET /v1/eventos não há corpo: a última linha da string canônica é sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 e a terceira linha é o path?query exatamente como enviado (ex.: /v1/eventos?desde=2026-09-01T00:00:00Z&limit=50). Não envie Idempotency-Key nem Content-Type. Enquanto a consulta processa, o GET responde 202 com Retry-After.

IPs de origem (allowlist)

Nos primeiros 5 dias (horário de Brasília) a integração está em aprendizado: os IPs que chamarem com assinatura válida são registrados e aparecem no portal para aprovação. Depois disso a allowlist é aplicada: IP desconhecido → 403 LAN-403-IP (e o IP entra como candidato no portal). Só IPv4.

Limites

• Por serviço: 2 req/s com rajada de 10 (padrão; pode variar por contrato) — headers X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; excedido → 429 LAN-429 + Retry-After.
• Teto diário de gasto por integração (padrão R$ 500,00; horário de Brasília) → 402 LAN-402-LIMIT.
• Corpo máximo 8 KB. Consultas síncronas têm orçamento de 25 s; além disso a resposta passa a 202 com Location para acompanhamento (a consulta continua na origem por até 4 min; se a origem não responder, termina como falhou LAN-504-UPSTREAM-TIMEOUT, não cobrada).
• Consulta Veicular Completa (30): normalmente excede o orçamento síncrono de 25 s — trate o 202 + Location (polling) ou o evento consulta.concluida como o caminho normal; a conclusão típica fica entre 30 s e 4 min. Os serviços 40, 50, 70 e 90 costumam responder de forma síncrona (o 70 em cerca de 10 s; o 90 leva o tempo da parte mais lenta, não a soma).
• Serviço não contratado: cada serviço precisa de preço vigente no seu contrato. Uma requisição de serviço sem preço é recusada com 422 LAN-422-PRICING-REQUIRED antes de qualquer processamento — nada é cobrado e nada é consultado. Fale com a Lanet para contratar o serviço.
• Só application/json é aceito no corpo (Content-Type diferente → 415 LAN-415); método não aceito por uma rota existente → 405 LAN-405 com header Allow.
• Borda: o balanceador/WAF pode responder um 403 genérico — sem code nem request_id — para corpo acima de 8 KB ou conteúdo considerado suspeito, antes de a requisição chegar à API. Trate um 403 sem code como rejeição da borda e revise o corpo enviado.
• Requisições recusadas por limites, indisponibilidade ou erro do processamento não são cobradas. Consultas concluídas, inclusive parciais (206) ou sem registro encontrado, são cobradas.

Erros

RFC 9457/7807 (application/problem+json): type=https://api.lanet.com.br/errors/<código minúsculo>, title/detail em português, code da tabela fechada LAN-* e request_id (= header X-Lanet-Request-Id).

Eventos (integrações webhook)

Entregues com X-Lanet-Event-Id, X-Lanet-Event-Type (o tipo do evento, para roteamento antes de ler o corpo), X-Lanet-Timestamp e X-Lanet-Signature: v1=<hex HMAC-SHA256(webhook_secret, ts + "\n" + event_id + "\n" + sha256hex(body))>; retentativas em 1 min, 5 min, 30 min, 2 h e 12 h; após 24 h de falhas o endpoint é marcado failing. Cada tentativa usa a URL atual do endpoint da integração: se você corrigir a URL no portal, as entregas pendentes e as reprocessadas pela Lanet passam a ir para a URL nova (a URL de callback informada em uma consulta é fixa). Verificação de posse: ao criar a integração (e a cada mudança de URL) a Lanet envia o evento integracao.verificacao com um challenge; o endpoint deve responder 2xx com {"challenge": "<mesmo valor>"} em até 10 s. Até o endpoint estar verificado, os demais eventos ficam aguardando_verificacao (sem consumir tentativas) e saem assim que a verificação conclui; a verificação pode ser pedida de novo no portal. A URL do webhook não pode redirecionar: 3xx conta como falha de entrega (e a criação recusa http:, IPs privados/metadata e hosts internos). Origem sempre de um dos IPs fixos 54.232.130.59, 18.230.241.10, 56.126.133.99. Replay disponível em GET /v1/eventos por 90 dias (sem desde, a janela padrão são as últimas 24 h).

Serviços de consulta

Serviço 70 — dados do veículo + valor de referência de tabela de preços (1.7.0-m5b). Pela placa, devolve a decodificação do veículo (veiculo: marca, modelo, versão, anos, cor, combustível, tipo/espécie, carroceria, portas, eixos, motor, câmbio, tração, peso bruto total e capacidade máxima de tração, capacidades, procedência, país, local de fabricação, categoria — o que a origem informar, inclusive o número do motor) e o valor de referência de tabela de preços do modelo (referencia): codigo_referencia, competencia (mês/ano de referência da tabela, AAAA-MM), valor_referencia_cents e a lista completa de versoes[] — cada uma com o seu historico[] mensal (previsto: true marca valor projetado) — mais os candidatos[] da decodificação. Quando a placa corresponde a mais de uma versão da tabela e nenhuma casa com a decodificação, a Lanet não escolhe por você: codigo_referencia, competencia e valor_referencia_cents vêm null, versoes[] vem completa e observacao explica ("mais de uma versão de referência para a placa"). Este serviço não devolve o proprietário (serviço 40) nem a ficha técnica (serviço 50).

Serviço 90 — pacote 70 + 50. Uma requisição sua, duas consultas na origem de dados feitas em paralelo, um preço (o do serviço 90 no seu contrato — não a soma do 70 com o 50). A resposta vem unida em um único dados: veiculo (identificação, na forma estendida do 70), referencia (a parte do 70) e ficha_tecnica + equipamentos (a parte do 50); em formato=pdf, o laudo traz as seções dos dois serviços em um documento só. Mudança 1.7.0-m5b: até a versão 1.6.0-m5b o pacote era 40 + 50 e trazia proprietario; desde esta versão o proprietário atual é exclusivo do serviço 40 e o pacote passou a trazer referencia. As duas partes são obrigatórias: se qualquer uma delas falhar, a consulta inteira termina como falhou e não é cobrada (não existe meia-resposta). Se uma parte concluir sem registro para a placa enquanto a outra encontra dados, a resposta é 206 com a seção ausente em secoes_indisponiveis (referencia ou ficha_tecnica) — e é cobrada, como qualquer parcial.

Modo teste (`lnt_test_`)

Respostas fixas por serviço, nunca cobradas. Placas especiais: TST0N00 (não encontrado), TST0P00 (parcial/206 — só no serviço 30; nos demais responde 200 completo), TST0E00 (erro na origem → 502), TST0T00 (tempo limite → 504), TST0B00 (ocupado → 503), TST0S00 (lenta: 202 + Location após 25 s e conclui com 200 em ~27 s — use para exercitar o polling).

Arquivo de Tabela de Preços (serviço 60 — assinatura)

Arquivo mensal com a tabela de preços de referência de carros, motos e caminhões, conferido e publicado pela Lanet no formato Lanet (.xlsx, abas *Tabela*, *Resumo* e *Metadados*; nome lanet-tabela-precos-YYYY-MM-vN.xlsx). Funciona por assinatura: uma integração dedicada ao serviço 60 (formato xlsx) recebe, a cada publicação, o evento arquivo_tabela_precos.disponivel (primeira versão do mês) ou arquivo_tabela_precos.atualizado (nova versão do mesmo mês), e baixa o arquivo pela API:

1. GET /v1/files?mes=YYYY-MM lista os arquivos publicados (todas as versões; a mais nova é publicado, as anteriores substituido e continuam disponíveis). 2. GET /v1/files/{file_id} (autenticado com HMAC + allowlist, como qualquer rota) responde `302` com Location = URL temporária válida por 5 minutos. Siga o redirecionamento com GET sem os headers de autenticação Lanet (a URL já está assinada) e confira o sha256 informado no evento/na lista.

O evento não contém URL de download (só download.caminho): quem baixa é sempre a integração autenticada. Downloads não são cobrados por unidade — o serviço é um item fixo mensal da assinatura; cada download é registrado para rastreio. Integrações de consulta (json/pdf) que não assinam o serviço recebem 403 LAN-403-SERVICE-DISABLED nas rotas de arquivos. Arquivos publicados ficam retidos indefinidamente (histórico); eventos ficam disponíveis para replay por 90 dias.