Integre a ZapCar com sua inteligência artificial

# Integrar a API da ZapCar a este projeto

Você é um engenheiro de software sênior trabalhando no meu projeto. Quero integrar a API REST da ZapCar (consultas veiculares e emissão de documentos, com resultado em JSON e PDF) seguindo o contrato oficial, com segurança e sem quebrar o que já existe.

Ferramenta: Claude Code. Você tem acesso a este repositório e ao terminal. Leia os arquivos antes de editar, apresente um plano curto antes de mudanças grandes, rode o lint e os testes do projeto ao final e não faça commit nem deploy sem eu pedir. Para ler a documentação, busque as URLs abaixo.

## Contexto do projeto

- Tipo de projeto: a descobrir. Descubra o tipo de projeto e o objetivo da integração lendo o código. Se não ficar claro quem vai usar as consultas e como o resultado aparece, me pergunte antes de implementar.
- Tecnologia: detectar pelo projeto. Identifique a linguagem, o framework e os padrões lendo o projeto (package.json, requirements, composer.json e a estrutura de pastas). Siga o que já existe: cliente HTTP, organização de pastas, validação, logs e testes.
- Se o que você encontrar no projeto contradizer algo acima, siga o projeto e me avise.

## Fontes oficiais (leia antes de escrever código)

- Documentação: https://www.zapcarconsulta.com.br/api-integradores/docs
- Documentação consolidada para IA (texto único): https://www.zapcarconsulta.com.br/api-integradores/docs/llms-full.txt
- Especificação OpenAPI 3.0: https://api.zapcarconsulta.com.br/public/openapi.json
- Base URL da API (a mesma para teste e produção): https://api.zapcarconsulta.com.br
- Use SOMENTE endpoints, campos, cabeçalhos e códigos que estejam nessas fontes. Não invente parâmetro, não use endpoints internos ou do painel e não trate dado de exemplo como contrato. Se algo que eu pedir não existir na API, diga isso em vez de simular.

## Regras de segurança (inegociáveis)

1. A chave só existe no servidor, lida de variáveis de ambiente (ZAPCAR_API_KEY). Nunca no front-end, no app, no repositório, em logs, em mensagens de erro ou nesta conversa. Eu configuro os valores; você só referencia as variáveis e documenta onde configurá-las.
2. Desenvolva e teste com uma chave de teste (prefixo zc_test_): mesma URL e mesmos endpoints, sem cobrança, sem base real. A chave de produção (zc_live_) cobra saldo; só eu decido quando trocá-la.
3. Todo POST que cobra (POST /v1/consultas, POST /v1/fipe, POST /v1/fipe/tabela) leva Idempotency-Key estável, derivada do id do pedido no meu sistema. Retry de rede repete a MESMA chave e o MESMO corpo; chave nova só para uma consulta nova.
4. Respeite o limite de requisições (120/min em produção, 60/min no teste; cabeçalhos RateLimit-*). No 429, espere o Retry-After. Nada de laço apertado.
5. Dados pessoais (nome, CPF/CNPJ, endereço) seguem a LGPD: só para a finalidade declarada, só para quem tem permissão, nunca em log, e com retenção definida.
6. Valide e normalize a entrada do usuário (placa: 7 caracteres, AAA0A00 ou AAA0000, sem hífen) antes de chamar a API, e confira no meu banco que cada consulta pertence ao usuário antes de mostrar resultado ou documento.

## Contrato essencial da API (confirme no OpenAPI)

- Autenticação: Authorization: Bearer <chave>.
- As consultas são ASSÍNCRONAS: POST /v1/consultas cria, debita o saldo e devolve { id, status: "processando", valor_cobrado, saldo_restante, resultado_url }. O resultado sai em GET /v1/consultas/{id} (polling a cada 3 a 5 s) ou pelo webhook query.completed / query.failed.
- Estados públicos: processando, concluido, erro. concluido e erro são terminais. Repetir o GET num id com erro nunca produz resultado.
- Consulta que termina em erro é estornada automaticamente. retryable: true = vale criar uma consulta NOVA depois de um backoff; false ou ausente = não repita sozinho.
- Erro de requisição: envelope { erro, codigo, retryable, request_id } (detalhes em VALIDATION_ERROR; saldo em SALDO_INSUFICIENTE).
- Toda resposta do ambiente de teste traz ambiente: "test"; em produção o campo não existe. Use isso para detectar configuração errada.
- Exceções síncronas: POST /v1/fipe (FIPE pela placa) e POST /v1/fipe/tabela respondem na mesma chamada.

## Serviços a integrar

Ainda não escolhi os serviços. Comece pela Consulta Simples (servico "consulta", exige placa) e deixe a escolha do serviço configurável. A lista completa, com campos exigidos e preço, vem de GET /v1/servicos; o formato de cada um está em https://www.zapcarconsulta.com.br/api-integradores/docs/servicos.

## Funcionalidades pedidas

- Autenticação: Cliente HTTP único da ZapCar, só no servidor: base https://api.zapcarconsulta.com.br, cabeçalho Authorization: Bearer <ZAPCAR_API_KEY> (X-API-Key também é aceito), timeout de 30 s, e conversão do envelope de erro em exceção tipada (status, codigo, retryable, request_id). Falhe na inicialização se a variável faltar ou não começar com zc_test_ ou zc_live_. Logue no máximo o prefixo da chave, nunca o valor. 401 (MISSING_API_KEY, INVALID_API_KEY) não se repete.
- Listagem de serviços: GET /v1/servicos devolve { servicos: [...] }. Cada item tem servico (o slug do POST), nome, requer (campos obrigatórios), preco ou, no CRLV, preco_por_uf, e opcionais. A FIPE tem endpoint próprio (campo endpoint, sincrono: true). Use esta lista para montar formulários e validar campos; faça cache de 5 a 15 minutos.
- Criação de consultas: POST /v1/consultas com { servico, ...campos de requer } e o cabeçalho Idempotency-Key (8 a 255 caracteres) derivado do id do pedido no MEU sistema, mais o número da tentativa (ex.: pedido-123-t1). 201 = criada e debitada (ou replay da mesma chave); 200 = reaproveitada (reaproveitada: true, nada cobrado). Guarde id e status junto do pedido. Trate 400 (corrigir o pedido), 402 (saldo), 409 IDEMPOTENCY_IN_PROGRESS (esperar e repetir com a MESMA chave), 422 (IDEMPOTENCY_KEY_REUSED é bug: mesma chave com outro corpo), 429 e 503.
- Acompanhamento de status: GET /v1/consultas/{id} a cada 3 a 5 segundos, com teto de cerca de 5 minutos, em job/fila/worker, nunca segurando o request do usuário. Estados públicos: processando (continue), concluido e erro (TERMINAIS: o mesmo id não muda mais). Timeout local não é erro da consulta: guarde o id e volte a consultar depois.
- Visualização de resultados: Na consulta concluida, leia schema_version (1.x), o bloco veiculo (normalizado pela ZapCar, mesma forma em qualquer fonte, só nos serviços de veículo), dados (formato de cada serviço: veja a página do serviço na documentação), proprietario, risco e nao_verificado. null significa NÃO verificado, nunca "nada consta"; um campo listado em nao_verificado também. Na consulta com status erro, mostre o texto do campo erro (pronto para o usuário, sem jargão). Dado pessoal (nome, CPF) só para quem tem permissão.
- Tratamento de erros: Dois tipos de falha. (1) Erro da requisição: envelope { erro, codigo, retryable, request_id }; repita só se retryable for true, com backoff exponencial e jitter, e só em GET ou POST com a MESMA Idempotency-Key. 429: espere o Retry-After. (2) Consulta com status erro: erro_codigo e retryable; true = crie uma consulta NOVA (Idempotency-Key nova) depois de um backoff; false ou AUSENTE = não repita sozinho. O valor de consulta que termina em erro é estornado automaticamente. Logue sempre o request_id.

## O que fazer, em ordem

1. Analise o projeto existente: estrutura, framework, padrões de código, cliente HTTP, configuração, filas, banco e testes.
2. Leia a documentação e o OpenAPI oficiais acima, nos trechos que esta integração usa.
3. Identifique onde a integração deve morar seguindo os padrões do projeto, e me apresente um plano curto (arquivos a criar e a alterar) antes de começar.
4. Implemente a integração no backend: um cliente HTTP único da ZapCar e as funções ou rotas das funcionalidades pedidas.
5. Configure as variáveis de ambiente (ZAPCAR_API_KEY): adicione ao arquivo de exemplo do projeto (.env.example ou equivalente) SEM valores reais e confira que o arquivo com valores está no .gitignore.
6. Use os schemas reais da API (do OpenAPI) para tipar ou validar as respostas, sem inventar campos.
7. Implemente o fluxo assíncrono corretamente: criar, guardar o id, acompanhar fora do request do usuário (job, fila ou worker) e tratar os estados terminais.
8. Exiba o resultado ao usuário, diferenciando "não verificado" (null) de "nada consta".
9. Trate falhas e limites: envelope de erro, retryable, 429 com Retry-After, timeout, rede e saldo insuficiente, com mensagens claras para o usuário e o request_id no log.
10. Crie testes usando o sandbox (chave zc_test_) e, nos testes unitários, mocks da API; nunca chamadas cobradas.
11. Preserve as funcionalidades existentes: não remova nem altere comportamento fora do escopo sem me perguntar.
12. Entregue um resumo: arquivos criados e alterados, variáveis de ambiente, como testar passo a passo e o que ficou pendente ou depende de mim.

## Testes no ambiente de teste (sandbox)

Com a chave zc_test_, o desfecho é escolhido pela PLACA:
- TST0001: conclui sem restrições. TST0002: gravame. TST0003: RENAJUD. TST0004: débitos. TST0005: sinistro e leilão.
- TST0404: termina em erro definitivo (QUERY_NOT_FOUND, retryable false). TST0503: erro transitório (retryable true). TST9999: nunca sai de processando (teste o teto do polling).
- A consulta fica alguns segundos em processando de propósito. O dados vem reduzido e marcado com _sandbox; a forma garantida é o bloco veiculo.
- O sandbox não gera documento (GET /pdf responde 422 SANDBOX_SEM_DOCUMENTO).
- Antes de ir para produção, confira o checklist: https://www.zapcarconsulta.com.br/api-integradores/docs/guias/producao

## Formato da entrega

- Explique em poucas linhas o que vai fazer antes de fazer.
- Código completo, sem trechos omitidos nem "TODO" no lugar de lógica.
- Ao final: lista de arquivos criados e alterados, variáveis de ambiente a configurar (sem valores), comandos para testar e limitações conhecidas.
- Se alguma funcionalidade pedida depender de algo que a API não oferece, diga claramente e não simule.