Ambiente de teste

A chave zc_test_: mesma URL, nenhum débito e cenários escolhidos pela placa.

Integre sem gastar saldo. É a mesma URL e são os mesmos endpoints: o que muda é a chave. Uma chave zc_test_ não debita saldo, não consulta base real e não devolve dado pessoal verdadeiro.

Como gerar

No Portal do Cliente, em Conta › Integrações, clique em Chave de teste. O limite de uma chave ativa é por ambiente: a de teste não ocupa a vaga da de produção.

cURLa única diferença é a chave (ZAPCAR_API_KEY=zc_test_…)

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":"TST0001"}'

Cenários escolhidos pela placa

Nada de esperar a base cair para testar o caminho de falha: cada placa reservada produz sempre o mesmo desfecho. A resposta traz o campo cenario com o nome do cenário.

Placa	cenario	O que acontece	Para testar
`TST0001`	`LIMPO`	`concluido`, nada consta	O caminho feliz do seu fluxo.
`TST0002`	`GRAVAME`	`concluido` com gravame ativo	Ler `veiculo.restricoes[]` e mostrar a restrição.
`TST0003`	`RENAJUD`	`concluido` com RENAJUD	Restrição judicial na sua tela.
`TST0004`	`DEBITOS`	`concluido` com débitos	O caso difícil: um item vem com `valor_informado: false` (débito real, valor desconhecido).
`TST0005`	`RISCO`	`concluido` com sinistro e leilão	O seu alerta de risco.
`TST0404`	`NAO_ENCONTRADO`	`erro`, `QUERY_NOT_FOUND`, `retryable: false`	Falha definitiva: o seu código não deve repetir.
`TST0503`	`FALHA_TEMPORARIA`	`erro`, `PROVIDER_UNAVAILABLE`, `retryable: true`	Falha retentável: o seu backoff e o limite de tentativas.
`TST9999`	`NUNCA_CONCLUI`	fica em `processando` para sempre	O seu timeout e o teto do polling.
Qualquer outra placa válida	`LIMPO`	`concluido`, nada consta	Explorar à vontade.

A validação do pedido é a da produção nos pontos que custariam dinheiro descobrir depois: placa fora do formato (400 PLACA_INVALIDA), uf ausente onde o serviço exige (400 UF_INVALIDA), UF não atendida em Débitos Estaduais (400 UF_INDISPONIVEL), 2ª via do ATPV-e sem a declaração (422 ACEITE_ATPVE_OBRIGATORIO), serviços de dado pessoal sem finalidade (400 FINALIDADE_OBRIGATORIA), CPF, CNPJ, CNH, data de nascimento e chave de NF-e inválidos.

O que o sandbox não confere

Os campos que cada UF exige no CRLV (CPF e RENAVAM) e o RENAVAM do código de segurança só são conferidos em produção. Em produção, faltando o campo, a resposta é 400 CRLV_DADOS_OBRIGATORIOS ou 400 RENAVAM_INVALIDO, sempre antes de cobrar. Leia o requer de cada UF em GET /v1/servicos.

Tempo de processamento

A consulta de teste nasce processando e só resolve depois de alguns segundos. É de propósito: se ela concluísse na hora, você não teria como exercitar o laço de polling que vai rodar em produção. A consulta de teste expira em 24 horas; depois disso o id responde 404 CONSULTA_NOT_FOUND.

O que é fiel e o que é reduzido

Parte da resposta	No sandbox
Envelope (`id`, `status`, `schema_version`, `erro_codigo`, `retryable`, `pdf_url`)	Fiel. Mesmos campos, mesmos valores possíveis, mesmas transições de status.
`veiculo`	Fiel na forma: montado com o mesmo contrato da produção, e só nos serviços que têm esse bloco em produção (`consulta`, `consulta-completa`, `consulta-veicular`, `ecv-premium`, `gravame` e `renajud`). Os cenários `TST0002` a `TST0005` aparecem nele; nos demais serviços valem os de erro e de espera.
`dados`	Reduzido e marcado (traz um campo `_sandbox` avisando). O `dados` real vem da base e muda de forma por serviço: imitá-lo ensinaria um contrato que não existe.
Erros de processamento	Mensagem e `retryable` vêm do catálogo real: o sandbox não inventa texto de erro.
PDF e imagens	Não existem: `422 SANDBOX_SEM_DOCUMENTO`. Não geramos documento falso, para ninguém exibi-lo como laudo.
`GET /v1/saldo`	Saldo fictício fixo, que nunca diminui. Não é o saldo real da conta.
`valor_cobrado` e `saldo_restante`	Sempre `0` e o saldo fictício: existem para você usar o mesmo código dos dois lados.

Toda resposta de teste traz ambiente: "test"

Em produção esse campo não existe. Use-o como trava nos seus testes automatizados: se ele aparecer onde você esperava dado real (ou faltar onde esperava teste), a chave está trocada. É melhor descobrir num assert do que num laudo entregue ao seu cliente.

Isolamento entre ambientes

A chave de teste só vê consultas de teste, e a de produção só vê as reais. Um id de um lado consultado com a chave do outro responde 404: nunca dado misturado.

FIPE no sandbox

Endpoint	Comportamento com zc_test_
`POST /v1/fipe`	Valor fictício, sem débito. A placa escolhe o cenário: `TST0404` devolve `404 FIPE_NAO_DISPONIVEL` e `TST0503` devolve `503 FIPE_INDISPONIVEL`.
`GET /v1/fipe/tabela/…`	Listas reais (são públicas e gratuitas), marcadas com `ambiente: "test"`.
`POST /v1/fipe/tabela`	Valor fictício, sem débito. O código FIPE escolhe o cenário: `000404-0` devolve `FIPE_NAO_DISPONIVEL` e `000503-0` devolve `FIPE_INDISPONIVEL`.

Limite de uso

60 requisições por minuto, num contador separado do de produção: exercitar o sandbox nunca consome a cota da integração que está no ar. A chave de teste não gasta saldo, então o limite é o único freio dela. Ver Limites e idempotência.

Se o próprio ambiente de teste estiver fora, a resposta é 503 SANDBOX_INDISPONIVEL, com retryable: true: repita em instantes.

Webhooks no teste

Consultas de sandbox não disparam query.completed. Para validar o seu endpoint (assinatura, deduplicação, resposta rápida), use o botão Testar do webhook no portal, que envia webhook.test pelo mesmo caminho de assinatura e reentrega dos eventos reais, sem custo. Para conferir o seu código de verificação antes disso, use o simulador de payload.

Quando você ainda precisa de uma consulta real

Uma só, de cada serviço que você consome: para conhecer o dados daquele serviço. Guarde a resposta como fixture nos seus testes. Assim o código é testado sem custo, e uma mudança de contrato aparece na comparação da fixture com uma resposta nova.