Pular para o conteúdo
ZapCar
Developersv1

Baixar o documento (PDF)

O relatório ou documento oficial da consulta concluída. Confie no Content-Type: alguns documentos chegam como imagem.

GET/v1/consultas/{id}/pdf
GratuitoDevolve arquivoSandbox

Baixa o documento da consulta: o mesmo do painel. Disponível quando o status é concluido; antes disso a resposta é 400 PDF_NOT_READY. A pdf_url da resposta da consulta já aponta para cá. Baixar é gratuito e pode ser repetido (dentro do limite de requisições).

Nos serviços com JSON, o documento é um atalho: você pode montar o seu próprio relatório com dados e veiculo. No CRLV, na 2ª via do ATPV-e e no código de segurança, o documento é o resultado. Detalhes de autoria e layout em Resultados e relatórios.

Informação:
Com a chave de teste não há documento: 422 SANDBOX_SEM_DOCUMENTO.
Pedido
curl -L "https://api.zapcarconsulta.com.br/v1/consultas/6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f/pdf" \
  -H "Authorization: Bearer $ZAPCAR_API_KEY" \
  -o relatorio.pdf
Resposta
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="zapcar_consulta_ABC1D23.pdf"

%PDF-1.7 …(binário)
Testar no API Explorer (sandbox)

Requisição

Parâmetros de caminho

idstring (uuid)obrigatório
Id da consulta (UUID), como devolvido pelo POST /v1/consultas.

Cabeçalhos

Authorizationstringobrigatório
Sua chave no formato Bearer zc_live_… (produção) ou Bearer zc_test_… (teste). O cabeçalho X-API-Key também é aceito. Ver Autenticação.

Exemplo: Bearer zc_test_…

Respostas

  • 200
    Documento binário.Arquivo: application/pdf, image/png, image/jpeg
  • 400
    Pedido inválido. Nada foi criado nem cobrado. codigo diz o que corrigir.Corpo: ApiError
  • 401
    Chave ausente, inválida ou revogada.Corpo: ApiError
  • 404
    Não encontrado, ou não pertence a esta conta (um id de outro cliente responde 404, nunca o dado).Corpo: ApiError
  • 422
    Pedido compreendido mas não processável: serviço indisponível para a conta, Idempotency-Key reusada com outro payload, ou atpve sem a declaração aceite_atpve.Corpo: ApiError
  • 429
    Rate limit excedido. Respeite o header Retry-After (segundos) antes de repetir. Não consome saldo.Corpo: ApiError
  • 500
    Falha interna inesperada. É transitória (retryable: true); informe o request_id ao suporte se persistir.Corpo: ApiError

Cabeçalhos da resposta

RateLimit-Limitintegerpode não vir
Teto de requisições da janela de 60s (120 em produção; 60 com chave de teste, em contador separado).
RateLimit-Remainingintegerpode não vir
Requisições restantes na janela atual.
RateLimit-Resetintegerpode não vir
Segundos até a janela zerar.
X-Request-Idstring (uuid)pode não vir
Id de correlação desta requisição. Informe ao suporte para localizar a chamada nos logs.
Content-Dispositionstringpode não vir
attachment com o nome e a extensão reais do arquivo.

Tipo do arquivo

Content-TypeQuandoExtensão no Content-Disposition
application/pdfQuase todos os serviços..pdf
image/png ou image/jpegAlguns emissores de documento oficial (CRLV) entregam imagem..png ou .jpg
Atenção:

Confie no Content-Type, não na extensão

Salvar tudo como .pdf gera arquivo que não abre quando o documento é imagem. Os bytes são conferidos antes do envio: se o arquivo armazenado não for PDF, PNG nem JPEG, a API recusa em vez de entregar bytes quebrados (DOCUMENTO_CORROMPIDO; refaça a consulta).

Nome do arquivo e white-label

O filename segue o padrão <prefixo>_<servico>_<placa ou id>.<ext>. O prefixo é zapcar, ou relatorio quando a conta tem logo cadastrada (white-label: o nome não leva a marca ZapCar). A personalização é aplicada somente aos relatórios compatíveis. Documentos oficiais, como CRLV, ATPV-e e Código de Segurança, permanecem inalterados, exatamente como o órgão emissor os entrega.