Documentos públicos e downloads

Use um CNJ conhecido para listar os documentos públicos disponíveis e baixar somente os arquivos necessários ao seu fluxo. A disponibilidade depende do que a fonte publica e permite consultar.

Etapa	Endpoint	Referência
Listar documentos	GET /v1/processos/cnj/{cnj}/documentos-publicos	Listagem
Baixar um documento	Use o downloadUrl devolvido pela listagem	Download
Solicitar atualização dos dados	POST /v1/processos/cnj/{cnj}/solicitar-atualizacao	Atualização
Acompanhar atualização	GET /v1/processos/cnj/{cnj}/status-atualizacao	Status

Listar

curl --get 'https://api.buscaprocessos.app.br/v1/processos/cnj/0000000-00.2026.8.26.0000/documentos-publicos' \
  --header "x-api-key: ${BUSCAPROCESSOS_API_KEY}" \
  --header 'Accept: application/json'

O CNJ é fictício; substitua por um número válido. Se receber 202 com URL de acompanhamento, siga HTTP 202 antes de interpretar a lista. Preserve o downloadUrl completo de cada item, inclusive a query string.

Baixar o arquivo

Um downloadUrl assinado contém download_token, é restrito à conta, ao CNJ e ao documento e expira por padrão em 10 minutos. Ele pode ser aberto no navegador sem expor a API Key. A listagem autenticada continua obrigatória para emitir novos links.

Para baixar no backend:

curl --fail --location \
  --output documento.pdf \
  "$DOWNLOAD_URL_RETORNADO_PELA_API"

O endpoint de download devolve o conteúdo do arquivo, não o envelope JSON da listagem. Confira o Content-Type retornado e trate erros pelo status HTTP antes de salvar o resultado como documento.

Trate o URL como uma credencial temporária: não publique nem registre seu token em logs. Não altere o CNJ, o ID ou a query string. Links expirados precisam ser renovados por nova listagem. Tentativas do mesmo link reutilizam a cobrança registrada; falha anterior estornada pode exigir um link novo.

Atualizar quando necessário

Quando os dados disponíveis não atenderem à consulta, solicite atualização e acompanhe o status retornado, sem repetir o POST em loop. Depois da conclusão, consulte novamente a listagem.

A atualização não torna documentos sigilosos, restritos ou não publicados acessíveis. Uma lista vazia ou um campo ausente não comprova a inexistência de documentos na origem.

Custo e erros

Listagem, atualização e download têm regras próprias de cobrança. Confira a referência e os preços da conta; evite baixar automaticamente todos os documentos de todos os processos.

Código	Ação
INVALID_DOWNLOAD_TOKEN	Use o URL completo retornado, sem alterações
DOWNLOAD_TOKEN_EXPIRED	Gere novo link pela listagem
DOWNLOAD_ALREADY_IN_PROGRESS	Aguarde a tentativa anterior
DOWNLOAD_TOKEN_ALREADY_FAILED	Gere outro link; a tentativa anterior foi estornada

Veja também Autenticação, Erros e Segurança.