Relatórios e PDF

Toda consulta concluída tem um documento em GET /v1/consultas/{id}/pdf. Este guia cobre o download correto, onde guardar e como mostrar o arquivo ao seu cliente sem expor a chave.

Quando baixar

• Só depois de status: "concluido". Antes disso: 400 PDF_NOT_READY (com retryable: true).
• Baixar é gratuito e pode ser repetido. Mesmo assim, guarde uma cópia se o seu cliente vai abrir o documento várias vezes: é mais rápido e não gasta o limite de requisições.
• Nos serviços com JSON, você pode não precisar do PDF: monte o seu relatório com veiculo e dados, com a sua marca.

Download com o tipo certo

Confie no Content-Type: quase sempre application/pdf, mas alguns documentos oficiais (CRLV de algumas UFs) chegam como imagem PNG ou JPEG.

// Baixa o documento e salva com a extensão certa (Node.js 18+).
import { writeFile } from "node:fs/promises";

const EXT = {"application/pdf":"pdf","image/png":"png","image/jpeg":"jpg"};

async function baixarDocumento(consultaId) {
  const resp = await fetch(`https://api.zapcarconsulta.com.br/v1/consultas/${consultaId}/pdf`, {
    headers: { Authorization: `Bearer ${process.env.ZAPCAR_API_KEY}` },
    signal: AbortSignal.timeout(60_000),
  });
  if (resp.status === 400) {
    const e = await resp.json();
    if (e.codigo === "PDF_NOT_READY") return null;          // ainda processando: tente depois
    throw new Error(e.codigo);
  }
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const tipo = (resp.headers.get("content-type") ?? "").split(";")[0];
  const ext = EXT[tipo];
  if (!ext) throw new Error(`Tipo inesperado: ${tipo}`);
  const arquivo = `consulta-${consultaId}.${ext}`;
  await writeFile(arquivo, Buffer.from(await resp.arrayBuffer()));
  return { arquivo, tipo };
}

await baixarDocumento("6f1c2e2a-1b3d-4a9e-8f7c-2a1b3c4d5e6f");

Exibir ao seu cliente

• Sirva o arquivo pelo seu backend (cópia guardada ou repasse do download), nunca com um link que exija a sua chave no navegador.
• Repasse o Content-Type e use Content-Disposition: inline para abrir no navegador ou attachment para baixar.
• Controle o acesso do seu lado: o documento traz dado pessoal (proprietário, financiado). Só quem tem direito ao pedido deve abrir.

Sua marca no relatório

Cadastre a logo em Conta › Empresa, no Portal do Cliente e os relatórios compatíveis baixados pela API saem com ela, e o nome do arquivo deixa de levar a marca ZapCar. Documentos oficiais, como CRLV, ATPV-e e Código de Segurança, permanecem inalterados, exatamente como o órgão emissor os entrega.

Imagens da Consulta Completa

As fotos de leilão vêm por endpoint próprio, com as URLs prontas em dados.fotosLeilao[].url. Baixe com o mesmo cuidado de Content-Type. Ver Imagens da Consulta Completa.