# ZapCar API

> API REST da ZapCar para consultas veiculares (placa, chassi, motor), consultas de pessoa (CPF e CNPJ, com finalidade LGPD), Tabela FIPE e emissão de documentos (CRLV, 2ª via do ATPV-e, código de segurança), com resultado em JSON e PDF. Assíncrona, autenticada por chave Bearer, com ambiente de teste gratuito pela chave zc_test_. Base URL: https://api.zapcarconsulta.com.br.

Instruções essenciais para agentes de programação:

- A chave de API (zc_live_ em produção, zc_test_ no ambiente de teste) fica só no servidor, numa variável de ambiente (ZAPCAR_API_KEY). Nunca no navegador, em app mobile, no repositório ou em log.
- Autenticação: cabeçalho Authorization: Bearer <chave> (X-API-Key também é aceito). Base URL única: https://api.zapcarconsulta.com.br. Quem decide o ambiente é a chave.
- Consultas são assíncronas: POST /v1/consultas cria, debita o saldo e devolve um id com status "processando". O resultado sai em GET /v1/consultas/{id} (polling a cada 3 a 5 s, teto de cerca de 5 min) ou pelo webhook query.completed / query.failed.
- Estados públicos: processando, concluido e erro. concluido e erro são terminais: o mesmo id não muda mais. Consulta que termina em erro é estornada automaticamente.
- retryable: true = falha transitória (crie uma consulta NOVA depois de um backoff). false ou AUSENTE = não repita sozinho.
- Envie Idempotency-Key (8 a 255 caracteres, derivada do id do pedido no seu sistema) em todo POST que cobra: POST /v1/consultas, POST /v1/fipe e POST /v1/fipe/tabela. Retry com a mesma chave e o mesmo corpo não cobra de novo.
- Erro de requisição: envelope { erro, codigo, retryable, request_id }. No 429, respeite o Retry-After. Limite padrão: 120 requisições/min em produção, 60 no teste.
- Webhooks: X-ZapCar-Signature = t=<unix>,v1=<hex>, HMAC-SHA256 de "<t>.<corpo bruto>" com o secret do endpoint. Compare em tempo constante, recuse timestamp com mais de 5 minutos, responda 2xx em até 10 s e deduplique pelo id do evento.
- POST /v1/fipe e POST /v1/fipe/tabela são síncronos: o resultado vem na mesma resposta.
- Ambiente de teste: toda resposta traz ambiente: "test"; o desfecho é escolhido pela placa (TST0001 limpo, TST0002 gravame, TST0003 RENAJUD, TST0004 débitos, TST0005 sinistro e leilão, TST0404 erro definitivo, TST0503 erro transitório, TST9999 nunca conclui). Não gera documento (422 SANDBOX_SEM_DOCUMENTO).
- null significa "não verificado", nunca "nada consta". Dado pessoal (nome, CPF/CNPJ) segue a LGPD.
- Use só endpoints, campos e códigos desta documentação e do OpenAPI. Não invente parâmetros nem use rotas internas.

## Comece por aqui

- [Documentação completa em texto único](https://www.zapcarconsulta.com.br/api-integradores/docs/llms-full.txt): guia, referência de cada endpoint gerada do OpenAPI, serviços, erros e exemplos.
- [Guia de integração em Markdown](https://www.zapcarconsulta.com.br/api-integradores/docs/guia-integracao.md): o fluxo de ponta a ponta com código.
- [Especificação OpenAPI 3.0](https://api.zapcarconsulta.com.br/public/openapi.json): o contrato oficial, gerado do catálogo vigente.
- [Integração com IA](https://www.zapcarconsulta.com.br/api-integradores/docs/integracao-ia): prompts prontos por ferramenta e gerador de prompt.
- [Exemplos prontos](https://www.zapcarconsulta.com.br/api-integradores/docs/exemplos): código em cURL, JavaScript, TypeScript, Node.js, Next.js, Python e PHP.

## Começando

- [Introdução](https://www.zapcarconsulta.com.br/api-integradores/docs): O que a API faz, como ela entrega o resultado e por onde começar.
- [Quickstart](https://www.zapcarconsulta.com.br/api-integradores/docs/quickstart): Da chave à primeira consulta em seis comandos, sem gastar saldo nos três primeiros.
- [Autenticação](https://www.zapcarconsulta.com.br/api-integradores/docs/autenticacao): A chave de API no cabeçalho Authorization: onde gerar, como guardar e como revogar.
- [Ambiente de teste](https://www.zapcarconsulta.com.br/api-integradores/docs/sandbox): A chave zc_test_: mesma URL, nenhum débito e cenários escolhidos pela placa.
- [Exemplos prontos para integrar](https://www.zapcarconsulta.com.br/api-integradores/docs/exemplos): Código pronto em cURL, JavaScript, TypeScript, Node.js, Next.js, Python e PHP, do cliente ao webhook, com tratamento de erro.

## Integração com IA

- [Integre a ZapCar com sua inteligência artificial](https://www.zapcarconsulta.com.br/api-integradores/docs/integracao-ia): Escolha a ferramenta que você utiliza, copie as instruções e deixe sua IA implementar a ZapCar diretamente no seu projeto.
- [Documentação para agentes de IA](https://www.zapcarconsulta.com.br/api-integradores/docs/agentes-ia): llms.txt, llms-full.txt, guia em Markdown, OpenAPI e prompts por serviço: a documentação em formatos que assistentes de programação leem bem.

## Referência da API

- [Visão geral dos endpoints](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints): Todas as rotas da /v1, com método, finalidade e se a chamada cobra.
- [Listar serviços e preços](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/listar-servicos): Catálogo de serviços liberados para a sua conta, com o preço que será cobrado e os campos que cada um exige.
- [Consultar saldo](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/consultar-saldo): Saldo atual da carteira, em reais. É o valor que as consultas debitam.
- [Criar uma consulta](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/criar-consulta): Cria a consulta, debita o saldo e devolve o id para você acompanhar. O resultado não vem nesta resposta.
- [Consultar o resultado](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/consultar-resultado): Estado da consulta. Quando conclui, a mesma resposta traz dados, o bloco veiculo e o link do PDF.
- [Baixar o documento (PDF)](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/baixar-pdf): O relatório ou documento oficial da consulta concluída. Confie no Content-Type: alguns documentos chegam como imagem.
- [Imagens da Consulta Completa](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/baixar-imagem): Uma foto de leilão (ou, nas consultas antigas, uma imagem de vistoria ou do certificado CSV) por chamada.
- [Tabela FIPE por placa](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/fipe-placa): Valores FIPE do veículo pela placa, na mesma resposta: sem id, sem polling e sem PDF.
- [Tabela FIPE: referências, marcas, modelos e anos](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/fipe-tabela-listas): Navegue a Tabela FIPE sem placa. As listas são gratuitas: só contam no limite de requisições.
- [Tabela FIPE: valor por marca, modelo ou código](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/fipe-tabela-valor): Valor FIPE do mês (ou de um mês passado) por marca, modelo e ano, ou direto pelo código FIPE, com histórico opcional.
- [Dicionário de campos](https://www.zapcarconsulta.com.br/api-integradores/docs/schemas): Cada objeto das respostas, campo a campo: tipo, obrigatoriedade, null e origem.
- [API Explorer](https://www.zapcarconsulta.com.br/api-integradores/docs/explorer): Monte e envie requisições reais ao ambiente de teste, direto do navegador.
- [OpenAPI e Postman](https://www.zapcarconsulta.com.br/api-integradores/docs/openapi): A especificação OpenAPI 3.0 e a coleção Postman, geradas do catálogo vigente.

## Serviços

- [Serviços disponíveis](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos): Cada serviço liberado na API: o que pede, o que devolve, preço vigente e comportamento no sandbox.

## Consultas

- [Ciclo de uma consulta](https://www.zapcarconsulta.com.br/api-integradores/docs/consultas): Criar, acompanhar e receber: os três status, o polling e quando o saldo é debitado e estornado.
- [Resultados e relatórios](https://www.zapcarconsulta.com.br/api-integradores/docs/resultados): Como ler a resposta: schema_version, null x false, as três camadas de dado, PDF e imagens.

## Integração

- [Webhooks](https://www.zapcarconsulta.com.br/api-integradores/docs/webhooks): Eventos assinados com HMAC-SHA256, política de reentrega e um simulador de payload.
- [Tratamento de erros](https://www.zapcarconsulta.com.br/api-integradores/docs/erros): Erro da requisição x erro no processamento, o catálogo de códigos e os problemas mais comuns.
- [Limites e idempotência](https://www.zapcarconsulta.com.br/api-integradores/docs/limites): Rate limit por conta e por IP, cabeçalhos RateLimit-* e a Idempotency-Key que evita cobrança dupla.
- [Segurança e LGPD](https://www.zapcarconsulta.com.br/api-integradores/docs/seguranca): Guarda da chave, isolamento entre contas e as obrigações de quem recebe dado pessoal.

## Guias de integração

- [Guias de integração](https://www.zapcarconsulta.com.br/api-integradores/docs/guias): Integrações de ponta a ponta, com código completo em Node.js, Python, PHP e cURL.
- [Primeira consulta](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/primeira-consulta): O fluxo inteiro: credencial, catálogo, criação, acompanhamento, resultado e falhas.
- [Integração com ERP automotivo](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/erp-automotivo): Como o sistema de uma revenda pede a consulta e mostra o resultado dentro do próprio ERP.
- [Receber resultados por webhook](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/webhooks): Receber o evento, validar a assinatura, deduplicar e atualizar o pedido sem polling.
- [Resiliência e erros](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/resiliencia): Timeouts, retry com backoff, idempotência e como não pagar duas vezes pelo mesmo resultado.
- [Relatórios e PDF](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/relatorios-pdf): Baixar, guardar e exibir o documento: Content-Type, white-label e imagens da Completa.
- [Checklist de produção](https://www.zapcarconsulta.com.br/api-integradores/docs/guias/producao): O que conferir antes de virar a chave zc_live_: segurança, testes, limites, monitoramento e suporte.

## Recursos

- [Changelog](https://www.zapcarconsulta.com.br/api-integradores/docs/changelog): Mudanças na API e na documentação, com o que exige ajuste de quem já integra.
- [FAQ e suporte](https://www.zapcarconsulta.com.br/api-integradores/docs/suporte): Perguntas frequentes, como pedir ajuda, confiabilidade e contato comercial para integradores.

## Serviços

- [Consulta Simples](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/consulta): servico "consulta", exige placa.
- [Consulta Completa](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/consulta-completa): servico "consulta-completa", exige placa.
- [Laudo ECV Premium](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/ecv-premium): servico "ecv-premium", exige placa.
- [Consulta Veicular](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/consulta-veicular): servico "consulta-veicular", exige placa.
- [Gravame](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/gravame): servico "gravame", exige placa.
- [Renajud](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/renajud): servico "renajud", exige placa.
- [Débitos + Código de Barras](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/debitos): servico "debitos", exige placa.
- [Débitos Estaduais](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/debitos-estadual): servico "debitos-estadual", exige placa, uf.
- [Histórico de Proprietários](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/historico-proprietarios): servico "historico-proprietarios", exige placa.
- [Detalhe Comunicação de Venda](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/comunicacao-venda): servico "comunicacao-venda", exige placa.
- [Decodificação de Chassi](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/decodificacao-chassi): servico "decodificacao-chassi", exige chassi.
- [Decodificação de Motor](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/decodificacao-motor): servico "decodificacao-motor", exige motor.
- [Score de Crédito](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/score-credito): servico "score-credito", exige documento.
- [Situação do CPF](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/situacao-cpf): servico "situacao-cpf", exige documento, data_nascimento.
- [Cadastro Simples CPF](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/cadastro-simples-cpf): servico "cadastro-simples-cpf", exige documento.
- [Cadastro Completo CPF](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/cadastro-completo-cpf): servico "cadastro-completo-cpf", exige documento.
- [Cadastro Simples CNPJ](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/cadastro-simples-cnpj): servico "cadastro-simples-cnpj", exige documento.
- [Cadastro Completo CNPJ](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/cadastro-completo-cnpj): servico "cadastro-completo-cnpj", exige documento.
- [Tabela FIPE](https://www.zapcarconsulta.com.br/api-integradores/docs/endpoints/fipe-placa): POST /v1/fipe, síncrono, corpo placa.
- [Crédito Único CPF](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/credito-unico-cpf): servico "credito-unico-cpf", exige documento.
- [Crédito Biro CPF](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/credito-biro-cpf): servico "credito-biro-cpf", exige documento, uf.
- [Crédito Único CNPJ](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/credito-unico-cnpj): servico "credito-unico-cnpj", exige documento.
- [Crédito Biro CNPJ](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/credito-biro-cnpj): servico "credito-biro-cnpj", exige documento, uf.
- [CNH Nacional](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/cnh-nacional): servico "cnh-nacional", exige documento, cnh, uf.
- [Débitos Trabalhistas (CNDT)](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/debitos-trabalhistas): servico "debitos-trabalhistas", exige documento.
- [Dívida Ativa da União](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/divida-ativa): servico "divida-ativa", exige documento.
- [Código de Segurança](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/codigo-seguranca): servico "codigo-seguranca", exige placa, renavam.
- [2ª via do ATPV-e](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/atpve): servico "atpve", exige placa.
- [Consulta NF-e](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/consulta-nfe): servico "consulta-nfe", exige chave.
- [CRLV Digital](https://www.zapcarconsulta.com.br/api-integradores/docs/servicos/crlv): servico "crlv", exige placa, uf.

## Opcional

- [Coleção Postman](https://api.zapcarconsulta.com.br/public/postman-collection.json)
- [Catálogo de erros em JSON](https://api.zapcarconsulta.com.br/public/api-erros)
- [Status da plataforma](https://www.zapcarconsulta.com.br/status)
- [Visão geral da ZapCar](https://www.zapcarconsulta.com.br/llms.txt)