Primeira consulta

O fluxo inteiro: credencial, catálogo, criação, acompanhamento, resultado e falhas.

O fluxo completo de uma consulta, na ordem em que o seu código vai executá-lo: credencial, catálogo, criação, acompanhamento, resultado e falhas. No fim há um cliente pronto para produção em quatro linguagens.

As etapas

Passo 1: Obter a credencial
Gere a chave de teste em Conta › Integrações e guarde em ZAPCAR_API_KEY no servidor. Comece sempre pelo sandbox. Ver Autenticação.
2
Passo 2: Autenticar e listar os serviços
GET /v1/servicos confirma a chave e diz o que cada serviço exige (requer) e custa. Faça isso na inicialização do seu sistema ou com cache curto: o catálogo muda pouco.
cURLGET /v1/servicos
curl "https://api.zapcarconsulta.com.br/v1/servicos" \ -H "Authorization: Bearer $ZAPCAR_API_KEY"

Passo 3: Enviar a consulta

POST /v1/consultas com o serviço, o identificador e uma Idempotency-Key derivada do seu pedido. Guarde o id devolvido junto do pedido.

cURLPOST /v1/consultas

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-t1" \
  -d '{"servico":"consulta","placa":"TST0001"}'

4
Passo 4: Acompanhar o processamento
GET /v1/consultas/{id} a cada 3 a 5 s, com teto de 5 minutos, ou receba por webhook. processando nunca é erro.
cURLGET /v1/consultas/{id}
curl "https://api.zapcarconsulta.com.br/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f" \ -H "Authorization: Bearer $ZAPCAR_API_KEY"
Passo 5: Receber o resultado
Com concluido, leia veiculo (estável) e dados (espelho da fonte). Trate null como “não verificado”, nunca como “nada consta”. Ver Resultados.
Passo 6: Tratar falhas
Com erro, o valor já voltou ao saldo. Se retryable for true, espere e crie uma consulta nova com Idempotency-Key nova (…-t2); se for false ou ausente, mostre o motivo e não repita sozinho.

As decisões do seu código

Situação	O que fazer
POST respondeu 201	Guardar o id e acompanhar.
POST respondeu 200 com reaproveitada: true	Acompanhar o id devolvido (a consulta anterior idêntica ainda está em andamento). Nada foi cobrado.
POST com 4xx	Corrigir o pedido (ler `codigo`). Só repetir se `retryable: true` (ex.: `409 IDEMPOTENCY_IN_PROGRESS`).
POST com 5xx, timeout ou erro de rede	Repetir a MESMA requisição com a MESMA Idempotency-Key, com backoff.
GET com status processando	Esperar e consultar de novo.
GET com status concluido	Usar o resultado.
GET com status erro e retryable true	Nova consulta (POST) com chave nova, até 3 tentativas.
GET com status erro e retryable false ou ausente	Encerrar e mostrar o motivo.
Teto de espera estourado	Guardar o id e consultar depois. Não criar outra consulta.

Código completo

O mesmo fluxo nas quatro linguagens. O de Node.js é o mais completo: timeout por requisição, Idempotency-Key, polling com teto, tratamento de 429 com Retry-After, backoff e limite de tentativas.

cURLcliente de produção: criar, acompanhar, resultado

# A chave fica numa variável de ambiente, nunca colada no comando salvo no histórico.
export ZAPCAR_API_KEY="zc_test_sua_chave_de_teste"

# 1. Cria a consulta (com zc_live_ debita o saldo). Guarde o "id" da resposta.
curl -X POST https://api.zapcarconsulta.com.br/v1/consultas \
  -H "Authorization: Bearer $ZAPCAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"servico":"consulta","placa":"ABC1D23"}'

# 2. Ver o resultado (troque COLE_O_ID). Repita até status = "concluido".
curl https://api.zapcarconsulta.com.br/v1/consultas/COLE_O_ID \
  -H "Authorization: Bearer $ZAPCAR_API_KEY"

# 3. Baixar o PDF (quando concluído).
curl -L https://api.zapcarconsulta.com.br/v1/consultas/COLE_O_ID/pdf \
  -H "Authorization: Bearer $ZAPCAR_API_KEY" \
  -o relatorio.pdf

Rode primeiro com a chave de teste e as placas TST0001 (sucesso), TST0404 (erro definitivo), TST0503 (erro retentável) e TST9999 (nunca conclui): são exatamente os quatro caminhos que o código acima trata.