Checklist de produção

O que conferir antes de virar a chave zc_live_: segurança, testes, limites, monitoramento e suporte.

Antes de trocar a chave zc_test_ pela zc_live_, confira cada item. A lista é para você marcar no seu processo de homologação; nada aqui é enviado à ZapCar.

Segurança das credenciais

A chave zc_live_ está numa variável de ambiente ou cofre de segredos do servidor, fora do repositório.
Nenhuma chamada à API sai do navegador ou do app mobile: tudo passa pelo seu backend.
A chave não aparece em URL, query string, log de aplicação nem ferramenta de monitoramento.
O secret do webhook (whsec_…) também está fora do código.
Você sabe quem na empresa pode gerar e revogar chaves e tem um procedimento de rotação.

Testes realizados

O fluxo completo rodou no sandbox com TST0001 (sucesso), TST0404 (erro definitivo), TST0503 (erro retentável) e TST9999 (nunca conclui).
A tela trata TST0002 (gravame), TST0004 (débito sem valor informado) e TST0005 (sinistro e leilão) sem mostrar “nada consta” onde há null.
Os testes automatizados conferem ambiente: "test" nas respostas do sandbox (e a ausência dele em produção).
Uma consulta real de cada serviço usado foi feita e guardada como fixture do campo dados.
Pedidos inválidos (placa errada, campo faltando, UF fora da lista) são recusados com a mensagem certa ao usuário.

Limites de requisições

O volume esperado cabe em 120 requisições por minuto, somando criação e polling. Se não couber, a equipe comercial foi avisada antes.
O 429 é tratado esperando o Retry-After, sem laço apertado.
O polling tem intervalo de 3 a 5 s, teto de 5 minutos e concorrência limitada.

Tratamento de erros

O código decide pelo codigo/erro_codigo e pelo retryable, nunca pelo texto de erro.
status: "erro" é tratado como terminal: nova tentativa é um POST novo, com teto de 3.
retryable ausente é tratado como “não repetir automaticamente”.
O request_id das respostas de erro é registrado para o suporte.
Campos desconhecidos na resposta são ignorados (nada quebra quando a API acrescenta um campo).

Idempotência e cobrança

Todo POST que cobra envia Idempotency-Key derivada do pedido e da tentativa, gravada antes da chamada.
Timeout de rede no POST é repetido com a mesma chave; consulta que falhou ganha chave nova.
O saldo é monitorado com GET /v1/saldo e há alerta antes de acabar.
Há conferência periódica entre os valor_cobrado registrados e o extrato da carteira (débitos e estornos).

Webhooks

A assinatura é validada sobre o corpo bruto, em tempo constante, com tolerância de 5 minutos.
Eventos são deduplicados pelo id e processados fora da requisição (resposta 2xx em menos de 10 s).
Eventos de consultas que o seu sistema não criou (portal, Telegram) são ignorados sem erro.
Há reconciliação por polling para consultas que ficaram em processando além do esperado.

Monitoramento e logs

Você mede taxa de sucesso, de erro por erro_codigo e tempo até a conclusão, por serviço.
Há alarme para 401 (chave revogada), 402 (saldo) e pico de PROVIDER_UNAVAILABLE.
Logs registram id da consulta, serviço, status e request_id, sem o resultado inteiro nem dado pessoal.
Alguém acompanha o changelog e a página de status.

Dados pessoais (LGPD)

Você guarda só o que usa e tem prazo de retenção definido.
Os serviços de pessoa enviam finalidade e declaracao_finalidade verdadeiras para o uso real.
O acesso ao resultado e ao PDF no seu sistema é restrito a quem tem direito ao pedido.

Fluxo de suporte

Existe um caminho interno para levar um problema à ZapCar com request_id ou id da consulta, horário e endpoint.
O contato da equipe de integração é conhecido: Fale conosco › API e integrações.

Pronto para produção? A primeira consulta real de cada serviço é a melhor última verificação: confira o débito no extrato e o resultado na sua tela.