Resultados e relatórios
Como ler a resposta: schema_version, null x false, as três camadas de dado, PDF e imagens.
Anatomia de uma resposta concluída
Quando o status vira concluido, o GET /v1/consultas/{id} traz o envelope e, conforme o serviço, até quatro blocos de resultado:
{
"id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
"servico": "consulta",
"placa": "ABC1D23",
"status": "concluido",
"schema_version": "1.0",
"valor_cobrado": 5.98,
"criado_em": "2026-10-18T09:14:02-03:00",
"dados": { "dados_do_veiculo": { "...": "..." }, "restricoes_e_impedimentos": { "...": "..." } },
"veiculo": { "placa": "ABC1D23", "marca": "VW", "...": "..." },
"proprietario": { "nome": "JOAO DA SILVA", "documento": "12345678901" },
"ultimo_licenciamento": 2024,
"nao_verificado": [],
"pdf_url": "/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f/pdf"
}| Campo | Quando vem | O que é |
|---|---|---|
dados | Serviços com JSON | O resultado como a base devolveu (espelho da fonte). null no CRLV e no código de segurança. |
veiculo | consulta, consulta-completa, consulta-veicular, ecv-premium, gravame, renajud | Bloco normalizado pela ZapCar: mesma forma em todos esses serviços. |
proprietario, ultimo_licenciamento | consulta e a família da Completa | Atalhos normalizados no topo da resposta. |
risco | consulta-completa, consulta-veicular, ecv-premium | O mesmo índice de risco do painel e do laudo. Não é garantia de compra. |
nao_verificado | consulta | Categorias que a base estadual não checou nesta consulta. |
pdf_url | Toda consulta concluída | Caminho do documento. Ver Baixar o documento. |
uf | crlv e debitos-estadual | A UF da consulta. |
Contrato e schema_version
A resposta de GET /v1/consultas/{id} traz schema_version. Ele não é a versão da API (essa é o /v1 da URL) nem a do backend: é o número que diz se a forma dos campos que você lê mudou.
| Mudança | O que significa para você |
|---|---|
1.0 → 1.1 (minor) | Somente acréscimo: campo ou bloco novo. Nada é removido, renomeado ou muda de tipo. Quem ignora campo desconhecido não sente. |
1.x → 2.0 (major) | Mudança incompatível. Não sai sem aviso no changelog e sem um caminho novo: /v1 continua entregando 1.x. |
O que o schema_version não cobre
veiculo. O conteúdo de dados espelha a base consultada e pode mudar quando a base muda: campos que passam a vir null, campos novos, valores escritos de outro jeito. Essas mudanças são publicadas no changelog com o selo Atenção, mas não são versionadas. Para dado com forma garantida, use veiculo.Cliente resiliente
null, false, ausência e “não verificado”
São situações diferentes. Tratá-las como iguais transforma falta de informação em atestado de que não há nada.
| O que veio | O que significa | O que você NÃO pode concluir |
|---|---|---|
false | A fonte verificou e a informação não existe. É um “nada consta” legítimo. | (nada a ressalvar) |
[] (lista vazia) | A fonte respondeu e não há ocorrência. | (nada a ressalvar) |
null | A informação não estava disponível ou a fonte não a devolveu nesta consulta. | Que não existe. sinistro: null não é “sem sinistro”. |
| campo ausente | O campo não faz parte deste serviço ou deste schema. | Nada sobre o veículo: o serviço não verifica esse item. |
vazio e listado em nao_verificado | Não verificado. Ninguém pode afirmar presença ou ausência. | Nunca exiba como “nada consta” ao seu cliente final. |
Regra para a sua tela
false e []. Para null, campo ausente e nao_verificado, exiba não verificado.Casos concretos: recall e sinistro vêm null nos serviços que não checam o item; leilao: null significa que nenhuma das fontes de leilão respondeu (já leilao.fotos > 0 confirma a passagem por leilão, mesmo com ocorrencias: 0); em veiculo.debitos[], um item com valor_informado: false é um débito real de valor desconhecido, e por isso debitos_total_centavos é um piso, não o total.
Campo vazio na Consulta Simples
Na Consulta Simples, os campos de restrição de dados têm três estados: "NADA CONSTA" (verificado e limpo), texto descritivo (restrição ativa) e vazio com a categoria listada em nao_verificado (não informado). A base estadual atual tem campo próprio para todas as restrições, então nao_verificado costuma vir vazio; uma categoria só entra na lista quando o estado não a respondeu naquela consulta.
Três camadas de dado na mesma resposta
Serviços diferentes vêm de bases diferentes, que não combinaram nomes entre si. Em vez de esconder isso, a resposta entrega camadas, da mais estável para a mais crua:
| Bloco | Padrão dos nomes | Estabilidade |
|---|---|---|
veiculo | snake_case, contrato ZapCar (ano_fabricacao, valor_centavos) | Estável. A camada recomendada: mesma forma nos serviços que a têm. Trocar de base não a altera. |
proprietario, ultimo_licenciamento, risco, nao_verificado | snake_case, contrato ZapCar | Estável. Atalhos normalizados. |
dados | Como a base devolveu (snake_case, camelCase ou MAIÚSCULAS) | Espelho da fonte. Para quem quer tudo, inclusive o que ainda não foi normalizado. Se a base mudar um nome, muda aqui. |
veiculo e em dados, prefira veiculo. Dinheiro nele é sempre inteiro em centavos (valor_centavos: 97617 = R$ 976,17), nunca texto com R$.A referência campo a campo do bloco está no dicionário de campos. O veiculo.proprietario.documento pode vir mascarado por algumas bases ("***.490.411-**"): valide o tamanho antes de usar.
Documentos (PDF) e imagens
Toda consulta concluída tem pdf_url. Nos serviços com JSON, o documento é um atalho para quem quer o relatório pronto: você pode montar o seu próprio a partir de dados e veiculo. No CRLV, na 2ª via do ATPV-e e no código de segurança, o documento é o resultado.
| Ponto | Como é |
|---|---|
| Formato | Confie no Content-Type: quase sempre application/pdf, mas alguns emissores de documento oficial entregam image/png ou image/jpeg. A extensão certa vem no Content-Disposition. |
| Quem desenha | A maioria dos relatórios (Consulta Simples, gravame, RENAJUD, débitos, decodificações, score e outros) é desenhada pela ZapCar a partir dos mesmos dados da API. Na família da Consulta Completa, e quando gravame ou RENAJUD são atendidos pela base de segunda tentativa, o documento pode ser o emitido pela base. Documentos oficiais (CRLV, ATPV-e, código de segurança) chegam como o órgão emitiu. |
| Sua marca | Quem cadastra a logo em Conta › Empresa, no Portal do Cliente recebe os relatórios pela API com a própria marca. A personalização é aplicada somente aos relatórios compatíveis. Documentos oficiais, como CRLV, ATPV-e e Código de Segurança, permanecem inalterados, exatamente como o órgão emissor os entrega. A logo é sempre a do dono da chave. |
| Layout | O layout e a paginação dos PDFs podem mudar (o changelog avisa). Se você extrai texto do PDF por posição, prefira o JSON. |
| Imagens | As fotos de leilão da Consulta Completa vêm por endpoint próprio, com URL pronta em dados.fotosLeilao[]. |
| Custo | Baixar documento e imagens é gratuito e ilimitado (dentro do limite de requisições). |