Dicionário de campos
Cada objeto das respostas, campo a campo: tipo, obrigatoriedade, null e origem.
Cada objeto das respostas, campo a campo, lido da especificação OpenAPI que a API publica. Em cada campo: o tipo, se ele sempre vem ou pode não vir, se aceita null, a descrição e um exemplo.
Informação:
Origem do dado
Objetos marcados como normalizados pela ZapCar têm forma garantida pelo contrato (
schema_version). O conteúdo de dados nas consultas espelha a base consultada e pode mudar quando a base muda: a ZapCar não garante a estabilidade de campos que vêm da fonte externa. Ver as três camadas de dado.Consultas
ConsultaCriada
Resposta do POST /v1/consultas. status é sempre "processando": o resultado sai em GET /v1/consultas/{id}.
idstring (uuid)sempre presenteExemplo: 6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f
servicostringsempre presenteValores:
consultaconsulta-completaecv-premiumconsulta-veiculargravamerenajuddebitosdebitos-estadualhistorico-proprietarioscomunicacao-vendadecodificacao-chassidecodificacao-motorscore-creditosituacao-cpfcadastro-simples-cpfcadastro-completo-cpfcadastro-simples-cnpjcadastro-completo-cnpjcredito-unico-cpfcredito-biro-cpfcredito-unico-cnpjcredito-biro-cnpjcnh-nacionaldebitos-trabalhistasdivida-ativacodigo-segurancaatpveconsulta-nfecrlvExemplo: consulta
statusstringsempre presenteValores:
processandoambientestringpode não virPresente SOMENTE em respostas do ambiente de teste. Ausente em produção.
Valores:
testcenariostringpode não virSó no ambiente de teste: o cenário que a placa reservada seleciona.
valor_cobradonumbersempre presenteDebitado agora, em reais. 0 quando a consulta foi reaproveitada.
Exemplo: 8.9
preco_basenumberpode não virSó quando um Grupo de Desconto foi aplicado.
descontoDescontopode não virGrupo de Desconto da API aplicado a esta conta.Formato: Desconto
saldo_restantenumbersempre presenteExemplo: 465.01
resultado_urlstringsempre presenteCaminho para acompanhar o resultado.
Exemplo: /v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f
reaproveitadabooleanpode não virSó no HTTP 200: uma solicitação idêntica já estava em processamento e foi devolvida. Nada foi cobrado.
mensagemstringpode não virSó no HTTP 200 reaproveitado: explicação para exibir ao usuário.
ConsultaResponse
Resposta do GET /v1/consultas/{id}. Os blocos presentes dependem do status: dados/veiculo/pdf_url apenas em "concluido"; erro/erro_codigo/retryable apenas em "erro".
idstring (uuid)sempre presenteservicostringsempre presenteValores:
consultaconsulta-completaecv-premiumconsulta-veiculargravamerenajuddebitosdebitos-estadualhistorico-proprietarioscomunicacao-vendadecodificacao-chassidecodificacao-motorscore-creditosituacao-cpfcadastro-simples-cpfcadastro-completo-cpfcadastro-simples-cnpjcadastro-completo-cnpjcredito-unico-cpfcredito-biro-cpfcredito-unico-cnpjcredito-biro-cnpjcnh-nacionaldebitos-trabalhistasdivida-ativacodigo-segurancaatpveconsulta-nfecrlvplacastring · aceita nullpode não virExemplo: ABC1D23
statusstringsempre presente"processando" = siga o polling. "concluido" e "erro" são TERMINAIS: o mesmo id não muda mais.
Valores:
processandoconcluidoerroschema_versionstringsempre presenteVersão do contrato de resposta. Minor = só acréscimo de campo; major nunca sai sem aviso no changelog.
Exemplo: 1.0
ambientestringpode não virPresente SOMENTE em respostas do ambiente de teste. Ausente em produção.
Valores:
testcenariostringpode não virSó no ambiente de teste: o cenário que a placa reservada seleciona.
ufstringpode não virSó em crlv e debitos-estadual.
valor_cobradonumber · aceita nullpode não vircriado_emstring (date-time) · aceita nullpode não virFuso America/Sao_Paulo.
dadosDadosPessoa ou objeto · aceita nullpode não virResultado como a base devolveu (camada de espelho, nomes no padrão da fonte). null em crlv e codigo-seguranca, que entregam só o PDF. Para dado com forma garantida, use
veiculo. Na consulta-completa (desde 14/10/2026) vêm também: historicoKm ({ registros: [{ km, data, dataIso }], inconsistente }), historicoProprietarios ([{ nome, documento, anoExercicio, uf }]), rouboFurto ({ constaOcorrencia, ocorrenciaAtiva, ocorrencias: [{ ocorrencia, declaracao, data, boletim, municipio, uf }] }), leilao.score (avaliação do leiloeiro) e fotosLeilao ([{ indice, url }]). Em todos: null = não verificado, lista vazia = sem registro. Não vêm mais: renainf, imagensOutras, alertasSinistro, informacoesAvulsas; restricoes.recall, situacaoLicenciamento e licenciadoAte vêm null. O ecv-premium (desde 14/10/2026) tem o mesmo formato da consulta-completa, sem fotosLeilao, e acrescenta: remarketing ({ marcaModelo, situacaoChassi, segmento, subSegmento, checklist: { dataInspecao, itens: [{ parte, estado }], garantia, fotos } }), anuncios ([{ data, km, valor, opcionais, fotos }]) e codigosFipe ([string]). As passagens por leilão do remarketing entram em leilao.ocorrencias. Nas consultas de pessoa (cadastro-*, credito-*, cnh-nacional, debitos-trabalhistas, divida-ativa; desde 15/10/2026) dados segue o schema DadosPessoa, igual nos 11 serviços, e a resposta não traz placa, veiculo nem proprietario.veiculoVeiculopode não virContrato ZapCar normalizado, em snake_case: a camada ESTÁVEL da resposta. Mesma forma em consulta, consulta-completa, consulta-veicular, ecv-premium, gravame e renajud, independente do fornecedor. null em
recall/sinistro/leilao significa NÃO VERIFICADO por este serviço: nunca "não consta".Formato: VeiculoproprietarioProprietariopode não virFormato: Proprietario
ultimo_licenciamentointeger · aceita nullpode não virExemplo: 2024
riscoobjetopode não virÍndice de risco. Só na consulta-completa, o único serviço que verifica sinistro, leilão e roubo/furto juntos.
nao_verificadoarray de stringpode não virSó na consulta simples: categorias que a base NÃO checou nesta consulta. Campo vazio em
dados que esteja nesta lista é ausência de VERIFICAÇÃO, não ausência de restrição. Desde 09/10/2026 a base tem campo próprio para todas as restrições, então a lista costuma vir vazia; um item aparece quando o estado não respondeu aquela categoria.Exemplo: []
pdf_urlstringpode não virCaminho do documento. Só em "concluido".
Exemplo: /v1/consultas/6f1c2e2a-.../pdf
errostringpode não virSó em "erro": frase para o cliente, sem nome de fornecedor nem jargão técnico.
erro_codigostringpode não virSó em "erro": por que falhou. Ausente em consultas anteriores a 02/09/2026.
Valores:
INVALID_PLATEINVALID_CHASSISINVALID_ENGINEINVALID_RENAVAMINVALID_DOCUMENTMISSING_REQUIRED_FIELDUF_UNAVAILABLEQUERY_NOT_FOUNDPROVIDER_TIMEOUTPROVIDER_UNAVAILABLEPROVIDER_INVALID_RESPONSEPROVIDER_AUTH_ERRORPROVIDER_ERRORPROVIDER_NO_DOCUMENTCIRCUIT_OPENQUEUE_UNAVAILABLEPROCESSING_INTERRUPTEDPDF_GENERATION_FAILEDADAPTER_ERRORCONFIG_ERRORINTERNAL_ERRORExemplo: PROVIDER_UNAVAILABLE
retryablebooleanpode não virSó em "erro". true = transitório, vale criar uma consulta NOVA depois de um backoff. false = definitivo. AUSENTE = a falha não foi classificada: trate como definitivo, não repita automaticamente.
Veículo (normalizado)
Veiculo
Normalizado pela ZapCar
Contrato ZapCar normalizado, em snake_case: a camada ESTÁVEL da resposta. Mesma forma em consulta, consulta-completa, consulta-veicular, ecv-premium, gravame e renajud, independente do fornecedor. null em recall/sinistro/leilao significa NÃO VERIFICADO por este serviço: nunca "não consta".
placastring · aceita nullsempre presenteExemplo: ABC1D23
renavamstring · aceita nullpode não virchassistring · aceita nullpode não virmarcastring · aceita nullpode não virExemplo: VW
modelostring · aceita nullpode não virExemplo: POLO SENSE
ano_fabricacaointeger · aceita nullpode não virExemplo: 2019
ano_modelointeger · aceita nullpode não virExemplo: 2020
corstring · aceita nullpode não vircombustivelstring · aceita nullpode não virespeciestring · aceita nullpode não vircategoriastring · aceita nullpode não virmunicipiostring · aceita nullpode não virufstring · aceita nullpode não virproprietarioProprietario · aceita nullpode não virFormato: Proprietario
Campos de proprietario
nomestring · aceita nullpode não virExemplo: JOAO DA SILVA
documentostring · aceita nullpode não virCPF/CNPJ como a fonte devolveu (pode vir mascarado).
null quando a base não liberou o documento; o nome pode vir mesmo assim.Exemplo: 12345678901
historico_proprietariosarray de objeto · aceita nullpode não virCadeia de titularidade (só consulta-completa e serviço dedicado). Ausente = o serviço não consulta; null = consulta e a base não respondeu; [] = sem registro.
Campos de historico_proprietarios
nomestring · aceita nullpode não virdocumentostring · aceita nullpode não virano_exerciciointeger · aceita nullpode não virmunicipiostring · aceita nullpode não virufstring · aceita nullpode não virocorrenciastring · aceita nullpode não virsituacaostring · aceita nullpode não virExemplo: EM CIRCULACAO
baixadobooleanpode não virrecallboolean · aceita nullpode não virnull = este serviço não verifica recall.
sinistroboolean · aceita nullpode não virnull = este serviço não verifica sinistro.
leilaoLeilaoInfo · aceita nullpode não virnull = nenhuma das fontes de leilão respondeu.Formato: LeilaoInfo
Campos de leilao
constabooleansempre presenteocorrenciasintegersempre presentefotosintegerpode não virImagens em pátio de leiloeiro. Prova positiva por si só, mesmo com ocorrencias: 0.
restricoesarray de Restricaosempre presenteFormato: array de Restricao
debitosarray de Debitosempre presenteFormato: array de Debito
debitos_total_centavosintegersempre presenteSoma dos débitos em centavos. Com algum item
valor_informado: false, é um PISO.Exemplo: 97617
ficha_pesadosobjeto · aceita nullpode não virSó preenchido em caminhão, ônibus e implemento.
Campos de ficha_pesados
eixosinteger · aceita nullpode não vircapacidade_carga_kginteger · aceita nullpode não virpeso_bruto_total_kginteger · aceita nullpode não vircapacidade_maxima_tracao_kginteger · aceita nullpode não vircapacidade_tanque_litrosinteger · aceita nullpode não virfaturamentoobjeto · aceita nullpode não virPara quem a montadora faturou o veículo 0km.
Campos de faturamento
tipo_documentostring · aceita nullpode não virExemplo: CNPJ
documentostring · aceita nullpode não virufstring · aceita nullpode não virultimo_licenciamentointeger · aceita nullpode não virAno do último licenciamento.
Exemplo: 2024
_servicostringpode não virMetadado: serviço que originou o bloco.
_normalizado_emstring (date-time)pode não virMetadado: quando o bloco foi montado.
_fontestringpode não virMetadado. Sempre
zapcar: o contrato público é nosso, não do fornecedor.Exemplo: zapcar
Proprietario
Normalizado pela ZapCar
nomestring · aceita nullpode não virExemplo: JOAO DA SILVA
documentostring · aceita nullpode não virCPF/CNPJ como a fonte devolveu (pode vir mascarado).
null quando a base não liberou o documento; o nome pode vir mesmo assim.Exemplo: 12345678901
Restricao
Normalizado pela ZapCar
tipostringsempre presenteValores:
FINANCEIRARENAJUDJUDICIALADMINISTRATIVATRIBUTARIAGUINCHOROUBO_FURTOCOMUNICACAO_VENDAOUTRAativabooleansempre presenteFonte da verdade. Não inferir de texto.
descricaostring · aceita nullpode não virDebito
Normalizado pela ZapCar
tipostringsempre presenteValores:
IPVALICENCIAMENTODPVATMULTAOUTROdescricaostring · aceita nullpode não virvalor_centavosintegersempre presenteValor em CENTAVOS inteiros (97617 = R$ 976,17).
Exemplo: 97617
valor_informadobooleanpode não virfalse = a fonte CONFIRMA o débito mas não devolveu o valor.
valor_centavos é 0 e NÃO significa ausência de débito.LeilaoInfo
Normalizado pela ZapCar
constabooleansempre presenteocorrenciasintegersempre presentefotosintegerpode não virImagens em pátio de leiloeiro. Prova positiva por si só, mesmo com ocorrencias: 0.
Pessoa
DadosPessoa
Formato ZapCar, preenchimento da base
dados das consultas de pessoa (cadastro-simples-cpf, cadastro-completo-cpf, cadastro-simples-cnpj, cadastro-completo-cnpj, credito-unico-cpf, credito-unico-cnpj, credito-biro-cpf, credito-biro-cnpj, cnh-nacional, debitos-trabalhistas, divida-ativa). Datas em dd/mm/aaaa; valores em reais (número). Bloco null = a base não informou; lista vazia = a base respondeu sem ocorrência.
produtostringpode não virExemplo: CREDITO_BIRO_CPF
documentostringpode não virSó dígitos.
Exemplo: 12345678909
tipo_documentostringpode não virValores:
CPFCNPJufstring · aceita nullpode não virExemplo: SP
identificacaoobjeto · aceita nullpode não virCampos de identificacao
nomestring · aceita nullpode não virdata_nascimentostring · aceita nullpode não viridadeinteger · aceita nullpode não virsexostring · aceita nullpode não virnome_maestring · aceita nullpode não virrgstring · aceita nullpode não viruf_rgstring · aceita nullpode não virtitulo_eleitorstring · aceita nullpode não virsituacao_cpfstring · aceita nullpode não virExemplo: REGULAR
data_situacao_cpfstring · aceita nullpode não virestado_civilstring · aceita nullpode não virescolaridadestring · aceita nullpode não virdependentesstring · aceita nullpode não virregiao_cpfstring · aceita nullpode não virempresaobjeto · aceita nullpode não virCampos de empresa
razao_socialstring · aceita nullpode não virnome_fantasiastring · aceita nullpode não virsituacaostring · aceita nullpode não virExemplo: ATIVA
data_situacaostring · aceita nullpode não virdata_aberturastring · aceita nullpode não virnatureza_juridicastring · aceita nullpode não vircnaestring · aceita nullpode não viratividade_secundariastring · aceita nullpode não virportestring · aceita nullpode não virfaturamento_presumidostring · aceita nullpode não virfuncionariosstring · aceita nullpode não virsitestring · aceita nullpode não virquantidade_filiaisstring · aceita nullpode não virnirestring · aceita nullpode não virrenda_presumidastring · aceita nullpode não virenderecosarray de EnderecoPessoa · aceita nullpode não virFormato: array de EnderecoPessoa
telefonesarray de objeto · aceita nullpode não virCampos de telefones
numerostringpode não virExemplo: (19) 99999-0000
tipostring · aceita nullpode não virValores:
CelularFixoatualizado_emstring · aceita nullpode não viremailsarray de string · aceita nullpode não virsociosarray de objeto · aceita nullpode não virCampos de socios
nomestring · aceita nullpode não virdocumentostring · aceita nullpode não virqualificacaostring · aceita nullpode não virparticipacaostring · aceita nullpode não virExemplo: 50%
entradastring · aceita nullpode não virsaidastring · aceita nullpode não virrelacaostringpode não virparticipacao = empresa em que o CONSULTADO é sócio.Valores:
socioadministradorparticipacaofiliaisarray de objeto · aceita nullpode não virCampos de filiais
nomestring · aceita nullpode não vircidadestring · aceita nullpode não virscoreobjeto · aceita nullpode não virCampos de score
valorinteger · aceita nullpode não virExemplo: 812
riscostring · aceita nullpode não virExemplo: BAIXO
mensagem_riscostring · aceita nullpode não virprobabilidade_pagamentostring · aceita nullpode não virExemplo: 94%
mensagem_probabilidadestring · aceita nullpode não virrazoesarray de stringpode não virpendencias_financeirasobjeto · aceita nullpode não virCampos de pendencias_financeiras
quantidadeintegerpode não virvalor_totalnumber · aceita nullpode não viritensarray de OcorrenciaFinanceirapode não virFormato: array de OcorrenciaFinanceira
protestosobjeto · aceita nullpode não virCampos de protestos
quantidadeintegerpode não virvalor_totalnumber · aceita nullpode não viritensarray de objetopode não virCampos de itens
cartoriostring · aceita nullpode não vircidadestring · aceita nullpode não virufstring · aceita nullpode não virdatastring · aceita nullpode não virvalornumber · aceita nullpode não virquantidadeinteger · aceita nullpode não vircheques_sem_fundoarray de objeto · aceita nullpode não virCampos de cheques_sem_fundo
bancostring · aceita nullpode não viragenciastring · aceita nullpode não virquantidadeinteger · aceita nullpode não virdatastring · aceita nullpode não virmotivostring · aceita nullpode não viracoes_judiciaisobjeto · aceita nullpode não virCampos de acoes_judiciais
totalinteger · aceita nullpode não vircomo_autorinteger · aceita nullpode não vircomo_reuinteger · aceita nullpode não viroutrasinteger · aceita nullpode não virParticipação que não é autor nem réu (advogado, defensor, perito…): não indica dívida.
segredo_justicainteger · aceita nullpode não virultimos_365_diasinteger · aceita nullpode não virprimeira_emstring · aceita nullpode não virultima_emstring · aceita nullpode não viritensarray de AcaoJudicialPessoapode não virRéu primeiro, depois autor, depois o resto.Formato: array de AcaoJudicialPessoa
resumo_ocorrenciasarray de objeto · aceita nullpode não virCampos de resumo_ocorrencias
descricaostringpode não virquantidadeinteger · aceita nullpode não virvalornumber · aceita nullpode não virconsultas_anterioresobjeto · aceita nullpode não virQuantas vezes empresas consultaram o crédito deste documento.
Campos de consultas_anteriores
ultimos_30_diasinteger · aceita nullpode não virde_31_a_60_diasinteger · aceita nullpode não virde_61_a_90_diasinteger · aceita nullpode não virmais_de_90_diasinteger · aceita nullpode não virdebitos_trabalhistasobjeto · aceita nullpode não virCertidão de Débitos Trabalhistas (TST). O PDF da certidão, quando a base envia, vai anexo ao PDF da consulta.
Campos de debitos_trabalhistas
certidaostring · aceita nullpode não virsituacaostring · aceita nullpode não virValores:
NEGATIVAPOSITIVAPOSITIVA_EFEITO_NEGATIVAemitida_emstring · aceita nullpode não virvalidadestring · aceita nullpode não virnomestring · aceita nullpode não virdivida_ativaobjeto · aceita nullpode não virCampos de divida_ativa
quantidade_ativasintegerpode não virvalor_ativonumber · aceita nullpode não viritensarray de objetopode não virAtivas primeiro.
Campos de itens
inscricaostring · aceita nullpode não virsituacaostring · aceita nullpode não virtipo_situacaostring · aceita nullpode não virregularidadestring · aceita nullpode não virtipo_devedorstring · aceita nullpode não virdevedorstring · aceita nullpode não virunidadestring · aceita nullpode não virprocessostring · aceita nullpode não virvalornumber · aceita nullpode não virextintabooleanpode não virPaga ou cancelada: histórico, não débito em aberto.
cnhobjeto · aceita nullpode não virCampos de cnh
categoriastring · aceita nullpode não virExemplo: AB
numero_registrostring · aceita nullpode não virrenachstring · aceita nullpode não virespelhostring · aceita nullpode não viremissaostring · aceita nullpode não virvalidadestring · aceita nullpode não virExemplo: 16/03/2033
primeira_habilitacaostring · aceita nullpode não virufstring · aceita nullpode não virorgao_expedidorstring · aceita nullpode não virimpedimentostring · aceita nullpode não virbloqueiosarray de stringpode não virobservacoesarray de stringpode não virpontosinteger · aceita nullpode não virinfracoes_12_mesesstring · aceita nullpode não virtoxicologicoobjeto · aceita nullpode não virCampos de toxicologico
coletastring · aceita nullpode não virsituacaostring · aceita nullpode não virvencimentostring · aceita nullpode não virexamesarray de objetopode não vircursosarray de objetopode não virEnderecoPessoa
Formato ZapCar, preenchimento da base
logradourostring · aceita nullpode não virExemplo: RUA DAS FLORES
numerostring · aceita nullpode não virExemplo: 100
complementostring · aceita nullpode não virbairrostring · aceita nullpode não vircidadestring · aceita nullpode não virExemplo: CAMPINAS
ufstring · aceita nullpode não virExemplo: SP
cepstring · aceita nullpode não virExemplo: 13010-000
atualizado_emstring · aceita nullpode não virdd/mm/aaaa, quando a base informa.
OcorrenciaFinanceira
Formato ZapCar, preenchimento da base
Uma negativação. A mesma dívida informada por duas bases (mesma data e valor) aparece uma vez só.
fontestringpode não virExemplo: Pefin
tipostring · aceita nullpode não virExemplo: FINANCIAMENTO
credorstring · aceita nullpode não virExemplo: BANCO EXEMPLO S.A.
contratostring · aceita nullpode não virdatastring · aceita nullpode não virExemplo: 15/01/2023
valornumber · aceita nullpode não virExemplo: 2378.38
cidadestring · aceita nullpode não virufstring · aceita nullpode não viravalistaboolean · aceita nullpode não virsem_detalhebooleanpode não virtrue = a base contou ocorrências sem mandar o detalhe;
quantidade diz quantas.quantidadeintegerpode não virAcaoJudicialPessoa
Formato ZapCar, preenchimento da base
Um processo. Só o PAPEL do consultado é entregue: nomes e documentos das outras partes não vêm.
numerostring · aceita nullpode não virtipostring · aceita nullpode não virExemplo: PROCEDIMENTO COMUM CIVEL
assuntostring · aceita nullpode não virtribunalstring · aceita nullpode não virExemplo: TJSP
comarcastring · aceita nullpode não virorgaostring · aceita nullpode não virufstring · aceita nullpode não virstatusstring · aceita nullpode não virExemplo: ARQUIVADO
distribuida_emstring · aceita nullpode não virExemplo: 19/09/2024
ultima_movimentacaostring · aceita nullpode não virvalornumber · aceita nullpode não virValor da causa; null = não informado.
papelstring · aceita nullpode não virAUTOR, REU, EXECUTADO, ADVOGADO, DEFENSOR PUBLICO… null = não identificado.
Exemplo: REU
polostring · aceita nullpode não virValores:
ativopassivooutroCatálogo e saldo
CatalogoServicos
servicosarray de Servicosempre presenteFormato: array de Servico
desconto_apiobjeto · aceita nullpode não virGrupo de Desconto da API da conta, quando houver.
Campos de desconto_api
grupostringpode não virpercentualnumberpode não virServico
servicostringsempre presenteSlug usado no campo
servico do POST /v1/consultas.Valores:
consultaconsulta-completaecv-premiumconsulta-veiculargravamerenajuddebitosdebitos-estadualhistorico-proprietarioscomunicacao-vendadecodificacao-chassidecodificacao-motorscore-creditosituacao-cpfcadastro-simples-cpfcadastro-completo-cpfcadastro-simples-cnpjcadastro-completo-cnpjcredito-unico-cpfcredito-biro-cpfcredito-unico-cnpjcredito-biro-cnpjcnh-nacionaldebitos-trabalhistasdivida-ativacodigo-segurancaatpveconsulta-nfecrlvExemplo: consulta-completa
nomestringsempre presenteExemplo: Consulta Completa
requerarray de stringsempre presenteCampos obrigatórios no corpo da criação.
Exemplo: ["placa"]
preconumberpode não virPreço que SERÁ debitado (já com preço personalizado e desconto). Ausente quando o preço é por UF.
Exemplo: 29.99
preco_basenumberpode não virPreço antes do Grupo de Desconto (só quando há desconto).
preco_tabelanumberpode não virPreço de tabela quando há promoção vigente (
preco já é o promocional).promocaobooleanpode não virHá promoção vigente neste serviço.
descontoDescontopode não virGrupo de Desconto da API aplicado a esta conta.Formato: Desconto
observacaostring · aceita nullpode não virpreco_por_ufarray de objetopode não virSó no CRLV: preço e campos exigidos por estado.
Campos de preco_por_uf
ufstringpode não virExemplo: SP
preconumberpode não virrequerarray de stringpode não virdisponivelbooleanpode não virpreco_basenumberpode não virdescontoDescontopode não virGrupo de Desconto da API aplicado a esta conta.Formato: Desconto
campos_por_ufarray de objetopode não virServiços estaduais (debitos-estadual): as UFs atendidas (as 27) e os campos que cada uma exige, desde 09/10/2026, só uf + placa em todas. UF fora desta lista → 400 UF_INDISPONIVEL, também no sandbox.
Campos de campos_por_uf
ufstringpode não virrequerarray de stringpode não viropcionaisobjetopode não virAdicionais do serviço (ex.:
incluir_fipe na consulta-completa).sincronobooleanpode não virtrue = a resposta vem na mesma chamada (sem polling). Só a FIPE.
endpointstringpode não virEndpoint próprio do serviço, quando não é POST /v1/consultas.
Exemplo: /v1/fipe
codigostringsempre presenteCódigo interno do serviço.
Exemplo: CONSULTA_COMPLETA
categoriastringsempre presenteExemplo: CONSULTAS
descricaostringsempre presenteprazostring · aceita nullpode não virExemplo: Poucos minutos.
nota_precosstring · aceita nullpode não virpagina_sitestring · aceita nullpode não virdisponivel_painelbooleanpode não virdisponivel_apibooleansempre presenteordemintegersempre presenteufs_suportadasarray de string · aceita nullpode não virnull = todas as UFs.
Desconto
Grupo de Desconto da API aplicado a esta conta.
grupostring · aceita nullpode não virExemplo: Parceiro Ouro
percentualnumberpode não virExemplo: 10
valornumberpode não virValor descontado, em reais.
Exemplo: 1.5
SaldoResponse
saldonumbersempre presenteSaldo da carteira, em reais.
Exemplo: 465.01
FIPE
FipeResponse
idstring (uuid)sempre presenteId desta cobrança (não há consulta para acompanhar: o endpoint é síncrono).
servicostringsempre presenteValores:
fipeplacastringsempre presenteExemplo: ABC1D23
veiculoobjetopode não virCampos de veiculo
marcastring · aceita nullpode não virmodelostring · aceita nullpode não virano_modelostring · aceita nullpode não virfipearray de FipeItemsempre presenteFormato: array de FipeItem
valor_cobradonumbersempre presentepreco_basenumberpode não virdescontoDescontopode não virGrupo de Desconto da API aplicado a esta conta.Formato: Desconto
saldo_restantenumbersempre presenteFipeItem
Uma versão do veículo na tabela FIPE. Valores como a FIPE publica (texto em reais).
codigo_fipestring · aceita nullpode não virExemplo: 005340-6
marcastring · aceita nullpode não virmodelostring · aceita nullpode não virano_modelostring · aceita nullpode não vircombustivelstring · aceita nullpode não virsigla_combustivelstring · aceita nullpode não virvalorstring · aceita nullpode não virExemplo: R$ 98.000,00
mes_referenciastring · aceita nullpode não virExemplo: setembro de 2026
referencia_fipeinteger · aceita nullpode não virscorenumber · aceita nullpode não virAderência desta versão à placa consultada.
codigo_marcastring · aceita nullpode não vircodigo_modelostring · aceita nullpode não virtipo_modelointeger · aceita nullpode não virhistoricoarray de FipeHistoricoPonto · aceita nullpode não virÚltimos meses da tabela para esta versão, do mais recente para o mais antigo (o primeiro é o mês de
valor). null = histórico não obtido.Formato: array de FipeHistoricoPontofonte_valorstringpode não vir"fipe" =
valor é o da referência FIPE vigente. "placas" = a fonte de valor atual falhou e valor/mes_referencia são os da base de identificação (podem ser de um mês antigo).Valores:
fipeplacasFipeTabelaResponse
idstring (uuid)sempre presenteId desta cobrança (endpoint síncrono: não há consulta para acompanhar).
servicostringsempre presenteValores:
fipe-tabelatipostringsempre presenteValores:
carrosmotoscaminhoesreferenciastring · aceita nullpode não virCódigo do mês pedido; null = o vigente.
veiculoFipeTabelaVeiculosempre presenteFormato: FipeTabelaVeiculo
valorstringsempre presenteComo a FIPE publica.
Exemplo: R$ 85.179,00
valor_numericonumber · aceita nullpode não virExemplo: 85179
mes_referenciastringsempre presenteExemplo: setembro de 2026
historicoarray de FipeHistoricoPonto · aceita nullpode não virSó quando
historico: true. Do mês mais recente para o mais antigo. null = pedido, mas a fonte não devolveu (o valor foi entregue e cobrado normalmente).Formato: array de FipeHistoricoPontovalor_cobradonumbersempre presentepreco_basenumberpode não virdescontoDescontopode não virGrupo de Desconto da API aplicado a esta conta.Formato: Desconto
saldo_restantenumbersempre presenteFipeTabelaVeiculo
codigo_fipestringsempre presenteExemplo: 005340-6
marcastringsempre presenteExemplo: VW - VolksWagen
modelostringsempre presenteExemplo: AMAROK High.CD 2.0 16V TDI 4x4 Dies. Aut
ano_modelointegersempre presenteExemplo: 2014
anostringsempre presenteId do ano na tabela (ano-combustível).
Exemplo: 2014-3
combustivelstringpode não virExemplo: Diesel
sigla_combustivelstringpode não virExemplo: D
FipeHistoricoPonto
valorstringsempre presenteExemplo: R$ 85.608,00
valor_numericonumber · aceita nullpode não virExemplo: 85608
mes_referenciastringsempre presenteExemplo: agosto de 2026
referenciastringsempre presenteExemplo: 336
FipeReferencias
referenciasarray de FipeReferenciasempre presenteDo mês mais recente para o mais antigo.Formato: array de FipeReferencia
FipeReferencia
codigostringsempre presenteExemplo: 337
messtringsempre presenteExemplo: setembro/2026
FipeMarcas
tipostringsempre presenteValores:
carrosmotoscaminhoesreferenciastring · aceita nullpode não virmarcasarray de FipeOpcaosempre presenteFormato: array de FipeOpcao
FipeModelos
tipostringsempre presenteValores:
carrosmotoscaminhoesmarcastringsempre presentereferenciastring · aceita nullpode não virmodelosarray de FipeOpcaosempre presenteFormato: array de FipeOpcao
FipeAnos
tipostringsempre presenteValores:
carrosmotoscaminhoesmarcastringpode não virmodelostringpode não vircodigo_fipestringpode não virreferenciastring · aceita nullpode não viranosarray de FipeOpcaosempre presenteFormato: array de FipeOpcao
FipeOpcao
Item de uma lista da Tabela FIPE (marca, modelo ou ano). Use codigo na chamada seguinte.
codigostringsempre presenteMarca/modelo: numérico. Ano: "AAAA-C" (ano-combustível); 32000 = zero km.
Exemplo: 59
nomestringsempre presenteExemplo: VW - VolksWagen
Erros e webhooks
ApiError
Envelope único de erro da API pública. erro é frase para humano (pode mudar de redação); codigo é o identificador estável em que se programa; retryable diz se repetir a MESMA chamada pode dar certo.
errostringsempre presenteExemplo: Placa em formato inválido.
codigostringsempre presenteExemplo: PLACA_INVALIDA
retryablebooleansempre presentetrue = falha transitória (provedor/rede/limite). false = corrija o pedido antes de repetir.
Exemplo: false
request_idstringpode não virId de correlação desta requisição nos logs da ZapCar.
Exemplo: 9f2c1b7e-4d52-4a1f-9d3e-7c8a5b2e1f04
detalhesarray de objeto · aceita nullpode não virSó em VALIDATION_ERROR: o que falhou, por campo.
Campos de detalhes
campostringpode não virExemplo: placa
mensagemstringpode não virExemplo: Obrigatório
saldonumber · aceita nullpode não virSó em SALDO_INSUFICIENTE: saldo atual da carteira, em reais.
Exemplo: 12.5
Erro
errostringsempre presenteExemplo: Placa em formato inválido.
codigostringsempre presenteExemplo: PLACA_INVALIDA
retryablebooleansempre presentetrue = falha transitória (provedor/rede/limite). false = corrija o pedido antes de repetir.
Exemplo: false
request_idstringpode não virId de correlação desta requisição nos logs da ZapCar.
Exemplo: 9f2c1b7e-4d52-4a1f-9d3e-7c8a5b2e1f04
detalhesarray de objeto · aceita nullpode não virSó em VALIDATION_ERROR: o que falhou, por campo.
Campos de detalhes
campostringpode não virExemplo: placa
mensagemstringpode não virExemplo: Obrigatório
saldonumber · aceita nullpode não virSó em SALDO_INSUFICIENTE: saldo atual da carteira, em reais.
Exemplo: 12.5
WebhookPayload
Corpo do POST que a ZapCar envia ao seu endpoint. NÃO carrega o resultado da consulta: dado sensível sai só por chamada autenticada com a sua chave.
idstring (uuid)sempre presenteId do EVENTO. Use para deduplicar: um retry reenvia o mesmo id.
typestringsempre presenteValores:
webhook.testquery.completedquery.failedvehicle.restriction.createdvehicle.gravame.createdvehicle.gravame.removedvehicle.debt.createdvehicle.document.changedExemplo: query.completed
created_atstring (date-time)sempre presentedataobjetosempre presenteEm query.*: { id, servico, status }, o
id é o da consulta, para GET /v1/consultas/{id}; servico e status são os nomes INTERNOS (decida pelo type). Em vehicle.*: { placa, tipo, titulo, detalhe }. Em webhook.test: { mensagem, webhook_id }.Campos de data
idstring (uuid)pode não virservicostringpode não virExemplo: CONSULTA_COMPLETA
statusstringpode não virExemplo: CONCLUIDO