Criar uma consulta

Cria a consulta, debita o saldo e devolve o id para você acompanhar. O resultado não vem nesta resposta.

POSThttps://api.zapcarconsulta.com.br/v1/consultas

Cobra saldoIdempotency-KeyAssíncronoSandbox

Cria a consulta, debita o saldo e devolve o id. O resultado não vem nesta resposta: acompanhe por GET /v1/consultas/{id} (polling a cada 3 a 5 s, teto de 5 minutos) ou pelo webhook query.completed.

Envie Idempotency-Key

É o que impede cobrança dupla quando a resposta se perde na rede: repetir a mesma requisição com a mesma chave devolve a resposta original sem cobrar de novo. Use o identificador do pedido no seu sistema. Ver Idempotência.

O corpo leva sempre servico e, conforme o serviço, o identificador (placa, chassi, motor, documento ou chave) e campos extras. Os campos marcados como “depende do serviço” estão na tabela Campos por serviço.

Pedido

curl -X POST "https://api.zapcarconsulta.com.br/v1/consultas" \
  -H "Authorization: Bearer $ZAPCAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-erp-984281" \
  -d '{"servico":"consulta","placa":"ABC1D23"}'

Resposta

{
  "id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
  "servico": "consulta",
  "status": "processando",
  "valor_cobrado": 5.98,
  "saldo_restante": 465.01,
  "resultado_url": "/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f"
}

Testar no API Explorer (sandbox)

Requisição

Cabeçalhos

Authorizationstringobrigatório

Sua chave no formato Bearer zc_live_… (produção) ou Bearer zc_test_… (teste). O cabeçalho X-API-Key também é aceito. Ver Autenticação.

Exemplo: Bearer zc_test_…

Idempotency-Keystringopcional

Identificador SEU desta operação (8–255 caracteres). Repetir a requisição com a mesma chave e o mesmo corpo devolve a resposta original SEM cobrar de novo: a proteção contra cobrança dupla em retry de rede. Validade de 30 dias. Cada nova tentativa de uma consulta que falhou precisa de uma chave NOVA.

Exemplo: pedido-erp-984281

Corpo (JSON)

servicostringobrigatório

Slug do serviço (ver GET /v1/servicos).

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-nfecrlv

placastringdepende do serviço

Com ou sem hífen. Exigida em todos os serviços, exceto as decodificações, o score-credito, o situacao-cpf, o consulta-nfe e as consultas de pessoa (cadastro-*, credito-*, cnh-nacional, debitos-trabalhistas, divida-ativa).

Exemplo: ABC1D23

ufstringdepende do serviço

Exigida em crlv, debitos-estadual, credito-biro-cpf, credito-biro-cnpj e cnh-nacional. Em debitos-estadual vale qualquer uma das 27 UFs e basta a placa; UF ausente ou inválida → 400 UF_INDISPONIVEL, antes de cobrar.

Exemplo: SP

renavamstringdepende do serviço

Exigido em codigo-seguranca e em algumas UFs do CRLV.

cpfstringdepende do serviço

CPF/CNPJ do proprietário. Exigido em algumas UFs do CRLV.

chassistringdepende do serviço

Exigido em decodificacao-chassi.

motorstringdepende do serviço

Exigido em decodificacao-motor.

documentostringdepende do serviço

CPF/CNPJ consultado: score-credito; só CPF em situacao-cpf. Nas consultas de pessoa: CPF nos produtos *-cpf e cnh-nacional, CNPJ nos *-cnpj, qualquer um em debitos-trabalhistas e divida-ativa.

cnhstringdepende do serviço

Número de registro da CNH: exigido em cnh-nacional (com o CPF em documento e a uf).

Exemplo: 01234567890

chavestringdepende do serviço

Chave de acesso da NF-e (44 dígitos, com ou sem espaços): exigida em consulta-nfe.

Exemplo: 35240912345678000190550010000123451000123459

data_nascimentostringdepende do serviço

Data de nascimento do titular (dd/mm/aaaa): exigida em situacao-cpf.

Exemplo: 31/12/1980

finalidadestringdepende do serviço

Finalidade da consulta (LGPD). Obrigatória em comunicacao-venda (traz nome e CPF/CNPJ do comprador) e nas consultas de pessoa; registrada também em score-credito e situacao-cpf.

Valores:NEGOCIACAO_VEICULOANALISE_CREDITOVERIFICACAO_CADASTRALOUTRA

Exemplo: NEGOCIACAO_VEICULO

declaracao_finalidadebooleandepende do serviço

Aceite de uso dos dados só para a finalidade informada. Em comunicacao-venda e nas consultas de pessoa precisa ser true; sem ele → 400 FINALIDADE_OBRIGATORIA, antes de cobrar.

Exemplo: true

incluir_fipebooleanopcional

Só consulta-completa: embute a Tabela FIPE em dados.fipe e cobra o preço da FIPE junto. Se só a FIPE falhar, apenas essa parcela é estornada.

aceite_atpveobjetodepende do serviço

OBRIGATÓRIO em atpve. A 2ª via não sai quando a ATPV-e anterior já foi assinada com firma reconhecida, e isso não é detectável antes da emissão. Mostre ao usuário final o aviso de GET /public/avisos/atpve e envie a declaração dele. Sem ela: 422 ACEITE_ATPVE_OBRIGATORIO; com versão antiga: 409 AVISO_ATPVE_DESATUALIZADO. Nada é cobrado em nenhum dos dois casos. A declaração fica registrada com IP e user-agent da chamada.

Campos de aceite_atpve

aceitobooleanobrigatório

O usuário marcou a declaração.

Valores:true

versaostringobrigatório

Campo versao de GET /public/avisos/atpve.

Exemplo: 2026-09-23

Respostas

200
Nada foi cobrado: solicitação idêntica (mesmo serviço e identificador) ainda em processamento, devolvida com reaproveitada: true. O replay de uma Idempotency-Key já concluída devolve a resposta ORIGINAL, com o status dela (201).Corpo: ConsultaCriada
Só na solicitação idêntica ainda em processamento (reaproveitada: true, valor_cobrado: 0). Acompanhe o id devolvido.
201
Consulta criada e saldo debitado.Corpo: ConsultaCriada
Também é a resposta de um replay da mesma Idempotency-Key com o mesmo corpo: a resposta original, sem cobrar de novo.
400
Pedido inválido. Nada foi criado nem cobrado. codigo diz o que corrigir.Corpo: ApiError
401
Chave ausente, inválida ou revogada.Corpo: ApiError
402
Saldo insuficiente. Nada foi criado nem cobrado; a resposta traz o saldo atual.Corpo: ApiError
409
Conflito: requisição idêntica (mesma Idempotency-Key) ainda em processamento (espere alguns segundos e repita, não crie outra consulta; ou, em atpve, aceite_atpve.versao diferente da vigente (AVISO_ATPVE_DESATUALIZADO)) busque o aviso em GET /public/avisos/atpve, mostre ao usuário e reenvie.Corpo: ApiError
422
Pedido compreendido mas não processável: serviço indisponível para a conta, Idempotency-Key reusada com outro payload, ou atpve sem a declaração aceite_atpve.Corpo: ApiError
429
Rate limit excedido. Respeite o header Retry-After (segundos) antes de repetir. Não consome saldo.Corpo: ApiError
500
Falha interna inesperada. É transitória (retryable: true); informe o request_id ao suporte se persistir.Corpo: ApiError
503
Fornecedor temporariamente indisponível (circuito aberto). Transitório.Corpo: ApiError

Cabeçalhos da resposta

RateLimit-Limitintegerpode não vir

Teto de requisições da janela de 60s (120 em produção; 60 com chave de teste, em contador separado).

RateLimit-Remainingintegerpode não vir

Requisições restantes na janela atual.

RateLimit-Resetintegerpode não vir

Segundos até a janela zerar.

X-Request-Idstring (uuid)pode não vir

Id de correlação desta requisição. Informe ao suporte para localizar a chamada nos logs.

Campos por serviço

O corpo mínimo de cada serviço. A fonte da verdade é o requer de GET /v1/servicos; no CRLV, o requer de cada UF.

Serviço	Corpo mínimo
consulta	`{"servico":"consulta","placa":"ABC1D23"}`
consulta-completa	`{"servico":"consulta-completa","placa":"ABC1D23","incluir_fipe":false}`
ecv-premium	`{"servico":"ecv-premium","placa":"ABC1D23"}`
consulta-veicular	`{"servico":"consulta-veicular","placa":"ABC1D23"}`
gravame	`{"servico":"gravame","placa":"ABC1D23"}`
renajud	`{"servico":"renajud","placa":"ABC1D23"}`
debitos	`{"servico":"debitos","placa":"ABC1D23"}`
decodificacao-chassi	`{"servico":"decodificacao-chassi","chassi":"9C2KD0540CR506454"}`
decodificacao-motor	`{"servico":"decodificacao-motor","motor":"KD05E1234567"}`
score-credito	`{"servico":"score-credito","documento":"12345678909","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
consulta-nfe	`{"servico":"consulta-nfe","chave":"35240912345678000190550010000123451000123459"}`
situacao-cpf	`{"servico":"situacao-cpf","documento":"12345678909","data_nascimento":"01/01/1990"}`
debitos-estadual	`{"servico":"debitos-estadual","placa":"ABC1D23","uf":"SP"}`
historico-proprietarios	`{"servico":"historico-proprietarios","placa":"ABC1D23"}`
comunicacao-venda	`{"servico":"comunicacao-venda","placa":"ABC1D23","finalidade":"NEGOCIACAO_VEICULO","declaracao_finalidade":true}`
cadastro-simples-cpf	`{"servico":"cadastro-simples-cpf","documento":"12345678909","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
cadastro-completo-cpf	`{"servico":"cadastro-completo-cpf","documento":"12345678909","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
cadastro-simples-cnpj	`{"servico":"cadastro-simples-cnpj","documento":"12345678000195","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
cadastro-completo-cnpj	`{"servico":"cadastro-completo-cnpj","documento":"12345678000195","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
credito-unico-cpf	`{"servico":"credito-unico-cpf","documento":"12345678909","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
credito-unico-cnpj	`{"servico":"credito-unico-cnpj","documento":"12345678000195","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
credito-biro-cpf	`{"servico":"credito-biro-cpf","documento":"12345678909","uf":"SP","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
credito-biro-cnpj	`{"servico":"credito-biro-cnpj","documento":"12345678000195","uf":"SP","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
cnh-nacional	`{"servico":"cnh-nacional","documento":"12345678909","cnh":"01234567890","uf":"SP","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
debitos-trabalhistas	`{"servico":"debitos-trabalhistas","documento":"12345678909","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
divida-ativa	`{"servico":"divida-ativa","documento":"12345678000195","finalidade":"ANALISE_CREDITO","declaracao_finalidade":true}`
crlv	`{"servico":"crlv","placa":"ABC1D23","uf":"SP","cpf":"12345678909","renavam":"00987495364"}`
atpve	`{"servico":"atpve","placa":"ABC1D23","aceite_atpve":{"aceito":true,"versao":"2026-09-23"}}`
codigo-seguranca	`{"servico":"codigo-seguranca","placa":"ABC1D23","renavam":"00987495364"}`

Aceitamos também os apelidos consulta-simples, gravames, codigo-de-seguranca, atpv-e, debitos-estaduais e outros, mas prefira o slug do catálogo: é ele que volta nas respostas.

Validações que recusam antes de cobrar

Serviço desconhecido (400 SERVICO_INVALIDO) ou desligado (422 SERVICO_INDISPONIVEL), placa, UF, documento, chassi, motor, CNH, chave de NF-e ou data de nascimento inválidos (400), finalidade ausente nos serviços de dado pessoal (400 FINALIDADE_OBRIGATORIA), ATPV-e sem declaração (422 ACEITE_ATPVE_OBRIGATORIO) ou com versão antiga (409 AVISO_ATPVE_DESATUALIZADO) e saldo insuficiente (402). Em todos, nada é criado nem cobrado.