Gravame

Situação do gravame (ativo/baixado) e dados do agente financeiro quando informados.

gravameJSONPDFR$ 6,99

Resumo

Item	Valor
Identificador técnico	`gravame`
Dados exigidos	placa (no catálogo: `placa`)
O que devolve	JSON cru do provedor + PDF
Preço vigente	R$ 6,99. Com a sua chave, `GET /v1/servicos` traz o seu preço.
Prazo	Poucos minutos; pode variar conforme a base consultada.
Bloco veiculo	Sim (contrato normalizado da ZapCar)

Requisição

Pelo endpoint comum de consultas, POST /v1/consultas. Os valores do exemplo são fictícios.

cURLPOST /v1/consultas (gravame)

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-gravame" \
  -d '{"servico":"gravame","placa":"ABC1D23"}'

Resposta

O POST devolve 201 com o id e status: "processando". O resultado sai em GET /v1/consultas/{id}, que passa por um destes estados:

status	O que vem
processando	Só o envelope. Consulte de novo em 3 a 5 s.
concluido	`dados`, `veiculo` e `pdf_url`.
erro	Valor estornado. `erro_codigo` diz o motivo e `retryable` se vale criar uma consulta nova.

Campo dados

No formato da base consultada (camada de espelho): nomes e preenchimento acompanham a fonte. Para dado com forma garantida, use o bloco veiculo quando o serviço tiver.

JSONExemplo ilustrativo: campo dados (gravame)

{
  "placa": "ABC1D23",
  "ufplaca": "SP",
  "chassi": "9BWZZZ377VT004251",
  "renavam": "00987495364",
  "anofabricacao": 2022,
  "anomodelo": 2022,
  "statusdoveiculo": "ALIENADO FIDUCIARIAMENTE",
  "descricaostatus": "INCLUSAO DE GRAVAME",
  "financeiranome": "BANCO XPTO S.A.",
  "documentofinanceira": "60701190000104",
  "codigofinanceira": null,
  "numerogravame": "8918837",
  "nomefinanciado": "JOAO DA SILVA",
  "documentoproprietarioatual": "12345678901",
  "numerocontrato": "000123456",
  "ufgravame": "SP",
  "datagravame": "14/05/2022",
  "datagravamevigencia": null,
  "marcamodelo": "M.BENZ/ATEGO 2425",
  "cor": "BRANCA",
  "municipio": "RIO DE JANEIRO",
  "combustivel": "DIESEL",
  "motor": "ABC123456",
  "ocorrencias": [
    { "numero_gravame": "8918837", "nome_agente": "BANCO XPTO S.A.",
      "doc_agente": "60701190000104", "numero_contrato": "000123456",
      "uf_placa": "SP", "ativo": true }
  ]
}

O bloco veiculo é o mesmo em todos os serviços que o têm. Ver o exemplo completo em Resultados e os campos no dicionário.

Particularidades

descricaostatus é "NADA CONSTA" quando não há gravame. statusdoveiculo só vem preenchido quando há: trate como sinal, sem comparar o texto, que varia conforme a base.
ocorrencias[] traz todos os registros de gravame do veículo; os campos do topo descrevem o principal.
renavam, ano, cor, municipio, combustivel e motor podem vir null, conforme a base que atendeu. Para identificação estável use o bloco veiculo.
Se a base principal falhar, a mesma chamada tenta uma segunda base antes de devolver erro, sem cobrança dupla.

No sandbox

Cenário escolhido pela placa (TST0001 limpo, TST0002 gravame, TST0003 RENAJUD, TST0004 débitos, TST0005 sinistro e leilão, TST0404 não encontrado, TST0503 falha retentável, TST9999 nunca conclui). Bloco veiculo fiel ao contrato; dados reduzido e marcado com _sandbox.

Cobrança

Debitado no POST, antes do processamento, e estornado automaticamente se a consulta terminar em erro. Pedido recusado na validação (400, 402, 409, 422) não cobra. Ler o resultado e baixar o documento são gratuitos. Ver Cobrança e estorno.

Testar no sandbox: abrir no API Explorer. Base da API: https://api.zapcarconsulta.com.br.