2ª via do ATPV-e

Resumo

Requisição

Pelo endpoint comum de consultas, POST /v1/consultas. Os valores do exemplo são fictícios.

curl -X POST "https://api.zapcarconsulta.com.br/v1/consultas" \
  -H "Authorization: Bearer $ZAPCAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-erp-984281-atpve" \
  -d '{"servico":"atpve","placa":"ABC1D23","aceite_atpve":{"aceito":true,"versao":"2026-09-23"}}'

Declaração obrigatória

A 2ª via não é emitida quando a ATPV-e anterior já foi assinada e teve as firmas reconhecidas em cartório, e isso não pode ser verificado antes da emissão. Por isso o pedido exige a declaração do usuário final em aceite_atpve. A regra vale em todos os canais que vendem a 2ª via, não só na API.

1. 1

   Passo 1: Busque o aviso vigente

   GET /public/avisos/atpve é público (não usa a sua chave) e devolve o texto do aviso, a versao vigente e o hash_sha256 do texto integral.

   curl https://api.zapcarconsulta.com.br/public/avisos/atpve

   {
     "versao": "2026-09-23",
     "titulo": "Atenção antes de continuar",
     "mensagem": "Este serviço não emite uma nova ATPV-e para veículo cuja autorização anterior …",
     "complementar": "Se a ATPV-e existente já foi assinada ou reconhecida em cartório, não efetue a compra. …",
     "impedimentosTitulo": "Também podem impedir a emissão:",
     "impedimentos": ["Comunicação de venda já realizada", "Intenção de venda ativa", "…"],
     "declaracao": "Confirmo que a ATPV-e anterior não foi assinada nem teve firma reconhecida …",
     "texto_integral": "…",
     "hash_sha256": "…"
   }

2. 2

   Passo 2: Mostre o aviso ao usuário final

   Exiba o aviso no seu sistema e colha a confirmação da declaracao antes de pedir a emissão. A declaração é do usuário final: não a envie sem que ele tenha visto o aviso.
3. 3

   Passo 3: Envie a declaração junto com o pedido

   aceito precisa ser o booleano true (o texto "true" é recusado) e versao é a que veio no passo 1.

Resposta

O POST devolve 201 com o id e status: "processando". O resultado sai em GET /v1/consultas/{id}, que passa por um destes estados:

{
  "id": "6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f",
  "servico": "atpve",
  "placa": "ABC1D23",
  "status": "concluido",
  "schema_version": "1.0",
  "valor_cobrado": 39.99,
  "criado_em": "2026-10-18T09:14:02-03:00",
  "pdf_url": "/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f/pdf"
}

Particularidades

• Exige a declaração do usuário final em aceite_atpve: aceito precisa ser o booleano true e versao, a vigente em GET /public/avisos/atpve. Sem a declaração, 422 ACEITE_ATPVE_OBRIGATORIO; versão antiga, 409 AVISO_ATPVE_DESATUALIZADO. Nada é cobrado nos dois casos.
• Cobertura nacional e preço único: não há preco_por_uf. Enviar uf é aceito, mas não decide preço nem disponibilidade.
• É emissão: leva cerca de 1 minuto em processando.

No sandbox

Faz a mesma validação de aceite_atpve da produção (dá para testar o fluxo do aviso sem custo), mas não gera documento: GET /pdf responde 422 SANDBOX_SEM_DOCUMENTO.

Cobrança

Debitado no POST, antes do processamento, e estornado automaticamente se a consulta terminar em erro. Pedido recusado na validação (400, 402, 409, 422) não cobra. Ler o resultado e baixar o documento são gratuitos. Ver Cobrança e estorno.

Testar no sandbox: abrir no API Explorer. Base da API: https://api.zapcarconsulta.com.br.