Download de processos · Documentação

Quem integra manda o certificado uma vez e, depois, só números de processo. A API devolve um job na hora; o PDF da cópia integral sai quando o job termina. Autenticação: API key (Authorization: Bearer crw_…), ver docs/contas-e-cofre.md.

1. Cadastrar o certificado (uma vez)

curl -X POST https://API/certificados \
  -H "Authorization: Bearer crw_..." \
  -F "arquivo=@meu-certificado.pfx" \
  -F "senha=SENHA_DO_CERTIFICADO" \
  -F "totp=SEGREDO_BASE32_DO_2FA"        # exigido pelo PJe
  # -F "totp_codigo=123456"              # opcional: confere com o app agora
  # -F "rotulo=Certificado escritório"   # opcional: padrão = titular
  # -F "sistemas=pje,eproc"              # opcional: padrão = todos os sistemas

O .pfx é aberto com a senha na hora: senha errada ou certificado vencido respondem 422 e nada é gravado.
Fica no cofre cifrado; nenhuma rota devolve o arquivo, a senha ou o TOTP.
Vale para todos os tribunais e sistemas, salvo se sistemas restringir. GET /certificados lista os cadastrados (titular sem CPF, validade, TOTPs).
O TOTP enviado aqui é o do PJe e vale para todos os tribunais PJe.

No eProc cada tribunal tem o seu TOTP; inclua um por tribunal, sem reenviar o certificado:

curl -X PATCH https://API/credenciais/<id> -H "Authorization: Bearer crw_..." \
  -F "totp=SEGREDO_DO_TJSC" -F "totp_sistema=eproc" -F "totp_tribunal=TJSC"

2. Pedir o download

curl -X POST https://API/processos/download \
  -H "Authorization: Bearer crw_..." -H "Content-Type: application/json" \
  -d '{"numero": "0001234-05.2023.8.13.0024"}'

{"job_id": 42, "status": "na_fila", "numero": "0001234-05.2023.8.13.0024",
 "tribunal": "TJMG", "sistema": "pje", "instancia": 1,
 "certificado": "Certificado FULANO DE TAL", "duplicado": false,
 "acompanhar": "/processos/download/42"}

Campo
`numero`	obrigatório	CNJ com ou sem pontuação; o dígito verificador é conferido
`instancia`	`1`	`1` = 1º grau, `2` = 2º grau
`credencial_id`	automático	qual certificado usar; sem ele, o mais específico (do tribunal > que cita o sistema > que vale para todos; entre iguais, o mais recente)
`prioridade`	`0`	-10..10

Antes de virar job, o pedido é recusado com 422 e o motivo quando: o número é inválido, o tribunal não é suportado, não há certificado que sirva (vencido, de outro tribunal, sem TOTP para o PJe). Pedir de novo o mesmo processo e instância enquanto o anterior está ativo devolve o mesmo job ("duplicado": true).

Vários de uma vez (até 500; os válidos entram, os outros voltam com o motivo):

curl -X POST https://API/processos/download/lote -H "Authorization: Bearer crw_..." \
  -H "Content-Type: application/json" \
  -d '{"numeros": ["0001234-05.2023.8.13.0024", "0001234-60.2023.5.02.0024"]}'
# → {"aceitos": [...], "recusados": [{"numero": "...", "motivo": "..."}]}

3. Acompanhar e baixar

curl https://API/processos/download/42 -H "Authorization: Bearer crw_..."

{"job_id": 42, "status": "sucesso", "etapa": "Concluída", "tribunal": "TJMG",
 "detalhe": "Download concluído; PDF com 312 páginas; ...",
 "arquivo": {"nome": "0001234-05.2023.8.13.0024.pdf", "paginas": 312,
             "bytes": 4823112, "sha256": "…", "numero_confere": true,
             "url": "/jobs/42/artefatos/0001234-05.2023.8.13.0024.pdf"}}

Baixe o PDF com GET em arquivo.url, com a mesma API key.

`status`	Significado
`na_fila` / `rodando`	aguarde; `etapa` diz onde está (login, busca, download)
`sucesso`	PDF baixado e o número do processo confere no documento
`parcial`	PDF baixado, mas o número não foi achado nas primeiras páginas — confira
`sem_dados`	processo não encontrado ou sem acesso com este certificado naquela instância
`bloqueado`	pré-requisito ausente (ex.: tribunal exige janela no servidor); não repete
`falha` / `timeout`	erro do tribunal ou da rede; a fila tenta mais uma vez sozinha

Cobertura

Sistema	Situação
PJe (TJs, TRFs, TRTs, TREs que usam PJe)	disponível — o mesmo fluxo validado no painel de saúde
SAJ (TJSP, TJMS, TJAM, TJAL, TJAC)	recusado com motivo: login por certificado existe, download dos autos ainda não validado
eProc (TRF4, TRF2, TJRS, TJSC…)	recusado com motivo: idem

Detalhes do PJe:

o certificado precisa do TOTP do 2FA do PJe;
TJRN, TRF3 e TJPB só passam com navegador visível: o executor precisa de DISPLAY (no servidor, sessão gráfica); sem ela, respondem bloqueado;
um certificado faz uma sessão por vez em cada tribunal: pedidos do mesmo certificado para o mesmo tribunal entram em fila, os de tribunais diferentes rodam em paralelo (até JOBS_CONCORRENCIA).

O PDF fica em JOBS_DIR e, com MinIO configurado, também em s3://crawlers-jobs/jobs/<job>/ (ver docs/servico-fila.md).