Quickstart

Este roteiro roda inteiro no ambiente de teste: a chave zc_test_ usa a mesma URL e os mesmos endpoints da produção, não debita saldo e não consulta base real. No fim, trocar para produção é trocar a chave.

Passo a passo

1. 1

   Passo 1: Gere a chave de teste

   Crie sua conta e, no Portal do Cliente, abra Conta › Integrações e clique em Chave de teste. Copie o valor zc_test_…: ele aparece uma única vez. A chave de teste não ocupa a vaga da chave de produção.
2. 2

   Passo 2: Guarde a chave numa variável de ambiente

   Os exemplos desta documentação leem a chave de ZAPCAR_API_KEY. Assim ela não fica no código nem no histórico do terminal.

   export ZAPCAR_API_KEY="zc_test_cole_sua_chave_aqui"

3. 3

   Passo 3: Liste os serviços (confirma que a chave funciona)

   Responder 200 significa chave válida e API no ar. Esta chamada nunca cobra.

   cURLNode.jsPythonPHP

   curl "https://api.zapcarconsulta.com.br/v1/servicos" \
     -H "Authorization: Bearer $ZAPCAR_API_KEY"

4. 4

   Passo 4: Crie uma consulta

   Envie o serviço e a placa. No sandbox, a placa escolhe o desfecho: TST0001 conclui sem restrições. A resposta é 201 com um id e o status processando.

   cURLNode.jsPythonPHP

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

   {
     "id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
     "servico": "consulta",
     "status": "processando",
     "ambiente": "test",
     "valor_cobrado": 0,
     "saldo_restante": 1000,
     "resultado_url": "/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
     "cenario": "LIMPO"
   }

5. 5

   Passo 5: Acompanhe o processamento

   Repita a cada 3 a 5 segundos enquanto o status for processando. É gratuito (conta só no limite de requisições). No sandbox a consulta fica alguns segundos em processamento de propósito, para você exercitar o laço.

   cURLNode.jsPythonPHP

   curl "https://api.zapcarconsulta.com.br/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f" \
     -H "Authorization: Bearer $ZAPCAR_API_KEY"

6. 6

   Passo 6: Leia o resultado

   Com status: "concluido", a mesma resposta traz dados, o bloco veiculo e a pdf_url. Com status: "erro", o valor é estornado e o campo retryable diz se vale criar uma consulta nova. Experimente as placas TST0404 (erro definitivo) e TST0503 (erro retentável).

Ir para produção

Quando o fluxo estiver redondo no sandbox:

1. 1

   Passo 1: Gere a chave de produção

   Em Conta › Integrações, Gerar nova chave. O valor começa com zc_live_ e também aparece uma única vez.
2. 2

   Passo 2: Adicione saldo

   A API é pré-paga: cada consulta debita o saldo da carteira (recarga por Pix ou assinatura). Consulta que falha é estornada automaticamente.
3. 3

   Passo 3: Envie Idempotency-Key em todo POST que cobra

   É o que impede cobrança dupla quando a resposta se perde na rede. Use o identificador do pedido no seu sistema. Ver Idempotência.
4. 4

   Passo 4: Revise o checklist

   O checklist de produção cobre guarda da chave, timeouts, retry, webhooks e monitoramento.