Valera API

API de consulta e análise de processos judiciais nos principais tribunais brasileiros.
Autenticação via ?apikey= · Base URL: http://52.67.210.237:8000

Cache automático: Toda resposta é cacheada em memória (5 min) e S3 (24h). Use ?no_cache=true em processos para forçar nova consulta ao tribunal.

Autenticação

Passe a API key como query param em todas as rotas (exceto /health e /).

GET /processos/1234567-89.2023.4.03.6331?apikey=SUA_KEY

Retorna 401 se a key estiver ausente ou incorreta.

Tribunais disponíveis

65 tribunais em 5 sistemas judiciais. Use o id nas rotas.

PJe — 41 tribunais eProc — 7 tribunais e-SAJ — 10 tribunais Projudi — 1 tribunal

Detecção automática: Use GET /processos/{numero} (sem tribunal) e o número CNJ é decodificado automaticamente para o tribunal correto.

Federais (PJe)

trf1

TRF1 — Norte/Centro-Oeste

trf3

TRF3 — SP / MS

trf5

TRF5 — Nordeste (1º grau)

trf5_2g

TRF5 — Nordeste (2º grau)

trf6

TRF6 — MG

Federais (eProc)

trf2

TRF2 — RJ / ES

trf4

TRF4 — PR / SC / RS

jfes

JF Espírito Santo

jfrj

JF Rio de Janeiro

jfpr

JF Paraná

jfrs

JF Rio Grande do Sul

jfsc

JF Santa Catarina

Federais (PJe 1.0 — seções judiciárias TRF5)

jfal

JF Alagoas

jfce

JF Ceará

jfpb

JF Paraíba

jfpe

JF Pernambuco

jfrn

JF Rio Grande do Norte

jfse

JF Sergipe

TRF5 — dois sistemas: o 1º grau (trf5) usa PJe 2.x (pje1g.trf5.jus.br). O 2º grau (trf5_2g) ainda opera no sistema legado PJe 1.x (pje.trf5.jus.br), assim como as seções judiciárias listadas acima.

Estaduais (e-SAJ)

tjsp

TJSP — 1º grau

tjsp_2g

TJSP — 2º grau

tjms

TJMS — 1º grau

tjms_2g

TJMS — 2º grau

tjal

TJAL — 1º grau

tjal_2g

TJAL — 2º grau

Ver lista completa com todos os estaduais →

Processos

GET /processos Lista todos os tribunais disponíveis sem auth ▶

Retorna todos os tribunais registrados com id, nome e sistema.

Resposta

{"tribunais": [
  {"id": "trf1_pje_1g", "nome": "TRF1 — Tribunal Regional Federal da 1ª Região", "sistema": "pje"},
  {"id": "trf3_pje_1g", "nome": "TRF3 — Tribunal Regional Federal da 3ª Região", "sistema": "pje"},
  {"id": "trf2_eproc_2g", "nome": "TRF2 — ...", "sistema": "eproc"},
  ...
]}

GET /processos/{numero} Consulta processo com detecção automática do tribunal ▶

Detecta o tribunal pelo número CNJ (NNNNNNN-DD.AAAA.J.TT.OOOO) e retorna o processo completo. Recomendado — dispensa saber o tribunal.

Parâmetros

Param	Tipo	Obrig?	Descrição
`numero`	path	sim	Número CNJ do processo — ex: `5001706-61.2021.4.03.6309`
`movimentacoes`	query	não	`pagina` (padrão, 1ª pág) ou `all` (todas as movimentações)
`grau`	query	não	`0` = auto-detecta (padrão), `1` = força 1º grau, `2` = força 2º grau
`cert`	query	não	Nome do certificado A1 a usar (apenas PJe). Padrão: certificado principal do tribunal.
`no_cache`	query	não	`true` ignora cache e re-consulta o tribunal

Exemplo

GET /processos/5001706-61.2021.4.03.6309?apikey=KEY

Resposta

{"numero_processo": "5001706-61.2021.4.03.6309",
 "tribunal": "trf3_pje_1g",
 "sistema": "pje",
 "classe": "Procedimento Comum Cível",
 "assunto": "Vícios de Construção",
 "situacao": "Em andamento",
 "magistrado": "Dr. João Silva",
 "orgao_julgador": "4ª Vara Federal de São Paulo/SP",
 "comarca": "São Paulo",
 "data_autuacao": "2021-03-15",
 "valor_causa": 25000.00,
 "partes": [
   {"polo": "ativo", "nome": "Maria da Silva", "tipo": "autor", "cpf": "123.456.789-00"},
   {"polo": "passivo", "nome": "Construtora XYZ", "tipo": "reu"}
 ],
 "movimentacoes": [
   {"data": "15 jun. 2024",
    "movimentos": ["Petição"],
    "documentos": [{"id_processo_doc": "593344225", "titulo": "Petição Inicial"}]}
 ]}

Retorna 422 se o tribunal não for suportado — use GET /processos para ver a lista de suportados.

GET /processos/{tribunal}/{numero} Consulta processo em tribunal específico ▶

Mesmo que a rota sem tribunal, mas com tribunal fixo — útil quando você sabe o tribunal ou tem vários números do mesmo tribunal.

Parâmetros

Param	Tipo	Obrig?	Descrição
`tribunal`	path	sim	ID do tribunal — ex: `trf3`, `trf1`, `tjsp`
`numero`	path	sim	Número CNJ do processo
`movimentacoes`	query	não	`pagina` (padrão) ou `all`
`grau`	query	não	`0` = auto (padrão), `1` = 1º grau, `2` = 2º grau
`cert`	query	não	Certificado A1 a usar (apenas PJe). Padrão: cert principal do tribunal.
`no_cache`	query	não	`true` força re-consulta

GET /processos/trf3/5001706-61.2021.4.03.6309?apikey=KEY

# Forçar 2º grau
GET /processos/trf5/0802085-26.2016.4.05.8200?grau=2&apikey=KEY

POST /processos/bulk Consulta múltiplos processos em paralelo (até 100) ▶

Detecta o tribunal de cada número automaticamente. Processos com erro retornam junto com os bem-sucedidos — não aborta a listagem.

Body (JSON)

{"numeros": [
  "5001706-61.2021.4.03.6309",
  "1028040-27.2025.4.01.3300",
  "0012345-67.2022.4.04.7100"
]}

Resposta

{"total": 3,
 "ok": 2,
 "erros": 1,
 "processos": [
   {"numero_processo": "5001706-61.2021.4.03.6309", "_status": "ok", ...},
   {"numero": "0012345-67.2022.4.04.7100", "_status": "erro",
    "_http_status": 404, "_detalhe": {...}}
 ]}

curl -X POST "http://52.67.210.237:8000/processos/bulk?apikey=KEY" \
  -H "Content-Type: application/json" \
  -d '{"numeros":["5001706-61.2021.4.03.6309","1028040-27.2025.4.01.3300"]}'

GET /processos/{numero}/novidades Movimentações novas desde uma data ▶

Filtra apenas as movimentações com data ≥ desde. Útil para monitoramento periódico sem precisar comparar o diff manualmente.

Parâmetros

Param	Tipo	Obrig?	Descrição
`numero`	path	sim	Número CNJ do processo
`desde`	query	sim	Data de corte no formato `YYYY-MM-DD`
`grau`	query	não	`0` = auto (padrão), `1` = 1º grau, `2` = 2º grau
`no_cache`	query	não	`true` força re-consulta no tribunal

GET /processos/5001706-61.2021.4.03.6309/novidades?desde=2024-06-01&apikey=KEY

# Buscar novidades no 2º grau
GET /processos/1018430-83.2021.4.01.3200/novidades?desde=2024-06-01&grau=2&apikey=KEY

Resposta

{"numero": "5001706-61.2021.4.03.6309",
 "tribunal": "trf3_pje_1g",
 "grau_consultado": "1g",
 "desde": "2024-06-01",
 "total_novas": 2,
 "movimentacoes": [...],
 "cached": true}

GET /analise/{numero} Análise rápida: última petição, despacho e 3 últimas movimentações ▶

Extrai estrutura do processo (sem IA) — identifica a última petição e o último despacho/decisão com seus documentos. Útil como triagem antes de chamar a análise IA.

GET /analise/5001706-61.2021.4.03.6309?apikey=KEY

Resposta

{"numero": "5001706-61.2021.4.03.6309",
 "tribunal": "trf3_pje_1g",
 "situacao": "Em andamento",
 "ultima_peticao": {
   "data": "15 jun. 2024",
   "movimentos": ["Petição"],
   "documentos": [{"id_processo_doc": "593344225"}]
 },
 "ultimo_despacho": {
   "data": "20 mai. 2024",
   "movimentos": ["Despacho"],
   "documentos": [{"id_processo_doc": "587123456"}]
 },
 "ultimas_movimentacoes": [...]}

Documentos

GET /documentos/{tribunal}/{numero}/{id_doc} Baixa o conteúdo do documento (PDF ou HTML) ▶

Retorna o arquivo original — PDF para peças enviadas pelas partes, HTML para documentos nativos do PJe (sentenças, despachos). O id_doc vem de movimentacoes[].documentos[].id_processo_doc.

Parâmetros

Param	Tipo	Obrig?	Descrição
`tribunal`	path	sim	ID do tribunal — ex: `trf3`
`numero`	path	sim	Número CNJ do processo
`id_doc`	path	sim	ID numérico do documento — ex: `593344225`
`parametros`	query	não	Apenas para e-SAJ: parâmetros retornados por `GET /documentos/{tribunal}/{numero}`

Resposta

Content-Type	Quando
`application/pdf`	Peça enviada por parte (petição, contestação, procuração…)
`text/html`	Documento nativo do PJe/eProc (sentença, despacho, decisão…)

GET /documentos/trf3/5001706-61.2021.4.03.6309/593344225?apikey=KEY

Documentos são cacheados no S3 após o primeiro download. Requisições subsequentes são servidas diretamente do cache sem re-autenticar no tribunal.

GET /documentos/{tribunal}/{numero} Lista documentos do processo (apenas e-SAJ: TJSP, TJMS, TJAL) ▶

Para tribunais e-SAJ, retorna a pasta digital completa com todos os documentos e seus cd_documento para download. Para PJe e eProc os IDs já vêm em movimentacoes[].documentos[].

GET /documentos/tjsp/1001234-56.2023.8.26.0100?apikey=KEY

Resposta

{"tribunal": "tjsp_esaj_1g",
 "numero": "1001234-56.2023.8.26.0100",
 "total": 12,
 "documentos": [
   {"cd_documento": "12345678", "titulo": "Petição Inicial", "parametros": "..."},
   {"cd_documento": "12345679", "titulo": "Contestação", "parametros": "..."}
 ],
 "download_url": "GET /documentos/tjsp/{numero}/{cd_documento}?parametros={parametros}"}

Análise IA GPT-4o-mini

Custo estimado: ~R$ 0,01 por documento (gpt-4o-mini · ~10.000 tokens). Resultados são cacheados no S3 — re-chamadas para o mesmo documento e tipo são gratuitas.

POST /analise/{tribunal}/{numero}/{id_doc} Analisa documento com IA e retorna campos estruturados ▶

Baixa o documento, extrai texto (PDF nativo → OCR como fallback) e envia para GPT-4o-mini com perguntas específicas ao tipo do documento. Retorna JSON estruturado com campos como resumo, pedidos, resultado.

Parâmetros

Param	Tipo	Obrig?	Descrição
`tribunal`	path	sim	ID do tribunal — ex: `trf3`
`numero`	path	sim	Número CNJ do processo
`id_doc`	path	sim	ID do documento (de `movimentacoes[].documentos[].id_processo_doc`)
`tipo`	query	não	Tipo do documento para IA ajustar as perguntas. Valores: `peticao`, `sentenca`, `acordao`, `decisao`, `despacho`, `recurso`, `laudo`. Padrão: `generico`

Exemplo — Analisar petição

curl -X POST "http://52.67.210.237:8000/analise/trf3/5001706-61.2021.4.03.6309/593344225?tipo=peticao&apikey=KEY"

Resposta — tipo: peticao

{"tribunal": "trf3_pje_1g",
 "numero": "5001706-61.2021.4.03.6309",
 "id_processo_doc": "593344225",
 "tipo_canonico": "peticao",
 "chars_texto": 45833,
 "chars_analisados": 40000,
 "analise": {
   "tipo_peticao": "Petição Inicial",
   "resumo": "Ação indenizatória por vícios construtivos em imóvel MCMV...",
   "pedidos_principais": [
     "Reparação dos vícios construtivos (infiltrações, trincas)",
     "Indenização por danos materiais — R$ 25.000,00",
     "Indenização por danos morais — R$ 10.000,00",
     "Gratuidade de justiça"
   ]
 },
 "from_cache": false}

Resposta — tipo: sentenca

{"analise": {
   "resumo": "Sentença procedente em parte — reconhecidos danos materiais...",
   "resultado": "Procedente em parte",
   "condenacao": "Construtora condenada a reparar os vícios em 90 dias...",
   "honorarios": "10% sobre o valor da condenação",
   "prazo_recurso": "15 dias úteis"
 }}

Resposta — tipo: decisao / despacho

{"analise": {
   "resumo": "Deferido pedido de gratuidade de justiça e designada audiência...",
   "determinacao_principal": "Designar audiência de conciliação para 15/03/2025",
   "prazo": "Intimem-se as partes"
 }}

Se o documento já foi analisado anteriormente com o mesmo tipo, retorna o cache imediatamente com "from_cache": true — sem custo de IA.

GET /analise/{tribunal}/{numero} Lista todas as análises IA cacheadas para um processo ▶

Lê do cache S3 — não chama OpenAI nem faz login no tribunal. Retorna o resultado consolidado do relatório e as análises individuais por documento.

GET /analise/trf3/5001706-61.2021.4.03.6309?apikey=KEY

Resposta

{"tribunal": "trf3_pje_1g",
 "numero": "5001706-61.2021.4.03.6309",
 "resultado_consolidado": {
   "ia_pet_tipo": "Petição Inicial",
   "ia_pet_resumo": "Ação indenizatória por vícios construtivos...",
   "ia_pet_pedidos": "Reparação dos vícios | Danos materiais | Danos morais",
   "pub1_ia_resultado": "Procedente em parte",
   "grupo_acao": "Resultado favorável — iniciar execução"
 },
 "analises_documentos": [
   {"id_processo_doc": "593344225", "tipo_canonico": "peticao", "analise": {...}},
   {"id_processo_doc": "587123456", "tipo_canonico": "sentenca", "analise": {...}}
 ]}

Comunicações

GET /comunicacoes/buscar Busca comunicações processuais por tribunal e período ▶

Busca publicações e comunicações em diários oficiais eletrônicos no período especificado.

Parâmetros

Param	Tipo	Obrig?	Descrição
`tribunal`	query	sim	Sigla do tribunal — ex: `TRF3`, `TRF1`
`data_inicio`	query	sim	Data inicial `YYYY-MM-DD`
`data_fim`	query	não	Data final. Padrão: igual a `data_inicio`
`somente_mcmv`	query	não	`true` filtra apenas processos MCMV

GET /comunicacoes/buscar?tribunal=TRF3&data_inicio=2024-06-01&data_fim=2024-06-07&apikey=KEY

Resposta

{"tribunal": "TRF3",
 "data_inicio": "2024-06-01",
 "data_fim": "2024-06-07",
 "total": 42,
 "items": [
   {"numero_processo": "5001234-56.2022.4.03.6331",
    "data_publicacao": "2024-06-03",
    "tipo": "Intimação",
    "conteudo": "..."},
   ...
 ]}

Sessão

Os tribunais requerem login por certificado digital A1 + TOTP. O login ocorre automaticamente na primeira requisição e fica em cache. Essas rotas permitem monitorar e forçar a renovação.

GET /session/status Estado atual de todas as sessões por tribunal ▶

Estados possíveis

Estado	Significado
`valid`	Sessão em cache e dentro do TTL — pronta para uso
`warming_up`	Login em progresso em background
`login_failed`	Último login falhou — cooldown ativo até próxima tentativa
`no_session`	Sem sessão — login automático na próxima requisição

GET /session/status?apikey=KEY

Resposta

{"sessions": {
   "trf1_pje_1g": {"sistema": "pje", "state": "valid"},
   "trf3_pje_1g": {"sistema": "pje", "state": "warming_up"},
   "trf2_eproc_2g": {"sistema": "eproc", "state": "no_session"}
 },
 "pje_login_service": "ok",
 "eproc_login_service": "ok"}

POST /session/renovar Força renovação de sessão — útil após falha de login ▶

Parâmetros

Param	Tipo	Obrig?	Descrição
`tribunal`	query	sim	ID do tribunal — ex: `trf3`
`aguardar`	query	não	`false` (padrão): retorna imediatamente, login em background. `true`: bloqueia ~5min até completar.

# Dispara login em background (retorna imediatamente)
curl -X POST "http://52.67.210.237:8000/session/renovar?tribunal=trf3&apikey=KEY"

# Aguarda completar (~5min)
curl -X POST "http://52.67.210.237:8000/session/renovar?tribunal=trf3&aguardar=true&apikey=KEY"

GET

/session/certificados

Lista os certificados A1 disponíveis e qual está atribuído a cada tribunal.

GET /session/certificados?apikey=KEY

{"certificados_disponiveis": ["escritorio-a1", "reserva-a1"],
 "por_tribunal": {
   "trf1_pje_1g": "escritorio-a1",
   "trf3_pje_1g": "escritorio-a1",
   "trf5_pje_1g": "escritorio-a1",
   "trf5_pje_2g": "escritorio-a1"
 },
 "como_adicionar": {
   "1": "Copie o .pfx para /home/ec2-user/valera/data/cert-store/ na EC2",
   "2": "Adicione o cert a credentials.json na raiz do projeto e faça deploy",
   "3": "Execute: sudo systemctl restart valera-api",
   "4": "Troque o cert de um tribunal: POST /session/tribunal/{tribunal}/certificado"
 }}

POST

/session/tribunal/{tribunal}/certificado

Troca o certificado A1 ativo de um tribunal. Invalida a sessão existente; o próximo scraping faz login com o novo certificado.

Param	Tipo	Obrig?	Descrição
`tribunal`	path	sim	ID do tribunal — ex: `trf3`
`certificate`	query	sim	Nome do certificado a usar (ver `certificados_disponiveis` acima)

curl -X POST "http://52.67.210.237:8000/session/tribunal/trf3/certificado?certificate=reserva-a1&apikey=KEY"

{"ok": true, "tribunal": "trf3_pje_1g",
 "certificate_anterior": "escritorio-a1",
 "certificate_novo": "reserva-a1",
 "message": "Certificado padrão trocado de 'escritorio-a1' para 'reserva-a1'. Sessão anterior invalidada. Próxima requisição disparará novo login com o novo certificado."}

Erros HTTP

Código	Erro	Causa
`401`	Unauthorized	API key ausente ou incorreta
`404`	Not Found	Tribunal não encontrado ou processo não existe no tribunal
`422`	Unprocessable	Número CNJ inválido ou tribunal não suportado
`503`	Service Unavailable	Sessão aquecendo (`warming_up`) ou login falhou. Resposta inclui `Retry-After` e `retry_after_seconds`. Tente novamente após o tempo indicado.
`502`	Bad Gateway	Erro de comunicação com o tribunal (timeout, bloqueio Akamai, HTML inesperado)

Tratando 503 — sessão aquecendo

{"error": "session_warming_up",
 "tribunal": "trf3_pje_1g",
 "retry_after_seconds": 300,
 "acao": {
   "status": "GET /session/status",
   "renovar": "POST /session/renovar?tribunal=trf3"
 }}

Aguarde o valor de retry_after_seconds e repita a requisição.

Lista completa de tribunais

PJe — Federais

trf1

TRF1 — Norte/Centro-Oeste (2.x)

trf3

TRF3 — SP/MS (2.x)

trf5

TRF5 — Nordeste 1º grau (2.x)

trf5_2g

TRF5 — Nordeste 2º grau (1.x)

trf6

TRF6 — MG (2.x)

jfal

JF Alagoas (1.x)

jfce

JF Ceará (1.x)

jfpb

JF Paraíba (1.x)

jfpe

JF Pernambuco (1.x)

jfrn

JF Rio Grande do Norte (1.x)

jfse

JF Sergipe (1.x)

eProc — Federais

trf2

TRF2 — RJ/ES

trf4

TRF4 — PR/SC/RS

jfes

JF Espírito Santo

jfrj

JF Rio de Janeiro

jfpr

JF Paraná

jfrs

JF Rio Grande do Sul

jfsc

JF Santa Catarina

PJe — Estaduais

tjac_1g / tjac_2g

TJAC — Acre

tjap_1g / tjap_2g

TJAP — Amapá

tjba_1g / tjba_2g

TJBA — Bahia

tjce_1g / tjce_2g

TJCE — Ceará

tjdft_1g / tjdft_2g

TJDFT — Distrito Federal

tjma_1g / tjma_2g

TJMA — Maranhão

tjmg_1g / tjmg_2g

TJMG — Minas Gerais

tjpa_1g / tjpa_2g

TJPA — Pará

tjpb_1g / tjpb_2g

TJPB — Paraíba

tjpe_1g / tjpe_2g

TJPE — Pernambuco

tjpi_1g / tjpi_2g

TJPI — Piauí

tjrj_1g / tjrj_2g

TJRJ — Rio de Janeiro

tjrn_1g / tjrn_2g

TJRN — Rio Grande do Norte

tjro_1g / tjro_2g

TJRO — Rondônia

tjrr_1g / tjrr_2g

TJRR — Roraima

tjse_1g / tjse_2g

TJSE — Sergipe

tjto_1g / tjto_2g

TJTO — Tocantins

tjes / tjes_2g

TJES — Espírito Santo

tjsc / tjsc_2g

TJSC — Santa Catarina

tjrs_1g / tjrs_2g

TJRS — Rio Grande do Sul

e-SAJ — Estaduais

tjsp / tjsp_2g

TJSP — São Paulo

tjms / tjms_2g

TJMS — Mato Grosso do Sul

tjal / tjal_2g

TJAL — Alagoas

tjgo / tjgo_2g

TJGO — Goiás

tjam / tjam_2g

TJAM — Amazonas

Projudi

tjpr

TJPR — Paraná