API de consulta judicial: como automatizar pesquisa de processos no Brasil

TL;DR: A API REST do Vigilant unifica o acesso a 12 fontes judiciais brasileiras (ESAJ + PJe) numa única interface OpenAPI 3.1. Autenticação por Bearer token, resposta em JSON padronizado, erros em RFC 7807. Cache inteligente de 2 dias (200 imediato se fresco, 202 + polling se novo). 6 endpoints: health, courts, create/get/cancel/reprocess consult. Custo: R$ 0,10 por tribunal consultado. Integração mínima leva 2-4 horas. Postman collection disponível pra download. Este guia cobre: endpoints, autenticação, cache behavior, error handling, exemplos em cURL/Python/JS, caso de integração e FAQ técnico.

Se você é desenvolvedor em uma legaltech, fintech, escritório de advocacia ou empresa de compliance e precisa automatizar a pesquisa de processos judiciais no Brasil, este guia é pra você.

Pra quem não é dev e quer entender como automatizar sem código, veja o guia de automação pra escritórios. Pra quem quer entender os sistemas judiciais que a API abstrai, veja ESAJ vs PJE.

O problema que a API resolve

Os tribunais brasileiros não oferecem APIs oficiais pra consulta de processos. Cada tribunal tem seu próprio sistema (ESAJ, PJE e outros), com interfaces, captchas e formatos de dados diferentes. São mais de 40 sistemas em produção no país.

Pra quem precisa de dados processuais em volume ou integrados a um sistema, as opções são:

1. Consulta manual — não escala (veja os números de tempo)
2. Construir e manter integração própria — alto custo de engenharia (scraping, captcha solving, rotação de proxy, parsing de HTML), manutenção constante (tribunais mudam layout sem aviso)
3. Usar uma API que já resolve isso — foco no seu produto

O Vigilant é a terceira opção: uma API REST que unifica o acesso a 12 fontes judiciais em 10 estados brasileiros, abstraindo ESAJ, PJE e outros sistemas por trás de um único endpoint JSON padronizado.

Visão geral da API

Aspecto	Detalhe
Protocolo	REST + JSON
Autenticação	Bearer token (API key gerada no dashboard)
Documentação	OpenAPI 3.1 com Scalar UI interativa
Spec JSON	vigilant.trackjud.com.br/api/openapi
Base URL	https://vigilant.trackjud.com.br/api/v1
Erros	RFC 7807 Problem Details
Health check	GET /api/health (público, sem auth)
Postman	Download collection

Primeiros passos — da conta à primeira chamada em 5 minutos

1. Crie uma conta

Acesse vigilant.trackjud.com.br e crie uma conta com e-mail (OTP — não precisa de senha). 5 créditos grátis imediatamente, sem cartão.

2. Gere uma API key

No dashboard → API Keys → Criar nova chave. A chave é exibida uma única vez — copie e guarde em local seguro (env var, vault, .env).

3. Faça a primeira chamada

curl https://vigilant.trackjud.com.br/api/health

Resposta: {"status":"healthy","version":"..."}. Se chegou aqui, a API está acessível.

curl -X POST https://vigilant.trackjud.com.br/api/v1/consults \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":"529.982.247-25","courts":["TJSP"]}'

Pronto. Primeira consulta criada. O response traz consult_id pra polling.

6 endpoints — referência rápida

Método	Endpoint	Auth	Descrição
GET	/api/health	❌	Health check (database, queue, external services)
GET	/api/v1/courts	✅	Lista tribunais com status operacional
POST	/api/v1/consults	✅	Cria consulta (CPF + tribunais)
GET	/api/v1/consults/:id	✅	Polling de resultado
PUT	/api/v1/consults/:id/cancel	✅	Cancela consulta em andamento
POST	/api/v1/consults/:id/reprocess	✅	Reprocessa tribunais que falharam

Todos os detalhes (request body, response shape, examples) estão na documentação interativa Scalar e na Postman collection.

Cache behavior — o conceito mais importante da API

A API tem um cache inteligente de 2 dias que muda completamente como você consome os dados:

Situação	HTTP response	O que acontece
Cache fresco (< 2 dias)	200 OK	Dados retornados imediatamente. source: "cache". Zero scraping.
Cache stale (≥ 2 dias)	200 OK	Dados antigos retornados + stale: true + refresh automático em background.
Sem cache	202 Accepted	Consulta criada. Scraping inicia. Fazer polling no consult_id.
force_refresh: true	202 Accepted	Pula cache. Sempre scraping novo. 5x o custo (5 créditos/tribunal).

Implicação prática: se você faz monitoramento semanal de 100 CPFs, e 80% deles não tiveram processos novos, essas 80 consultas são servidas do cache sem custo extra (se a consulta anterior é de < 2 dias). Isso reduz o custo real em 30-50% comparado ao teórico.

Error handling — RFC 7807

Todas as respostas de erro seguem o padrão RFC 7807 (Problem Details):

{
  "type": "https://vigilant.trackjud.com.br/errors/insufficient-credits",
  "title": "Payment Required",
  "status": 402,
  "detail": "You need at least 3 credits. Your balance is 1.",
  "instance": "/api/v1/consults"
}

Status	Type	Quando
400	.../bad-request	Tribunal desconhecido, lista vazia, tribunal não implementado
401	.../unauthorized	API key ausente ou inválida
402	.../insufficient-credits	Créditos insuficientes
404	.../not-found	Consulta não encontrada ou não pertence ao seu usuário
409	.../conflict	Ação conflita com estado atual (ex: cancelar consulta já finalizada)
422	.../validation-error	CPF inválido (falhou mod-11) — inclui campo errors com detalhes
429	—	Rate limit atingido — header Retry-After com segundos pra esperar

No seu código: trate pelo status code. Use detail pra log/debugging. O type URI é estável e pode ser usado como enum de erro.

Create consult — request e response detalhados

Request

POST /api/v1/consults
Content-Type: application/json
Authorization: Bearer SUA_API_KEY

{
  "document": "529.982.247-25",
  "courts": ["TJSP", "TJMG", "TRF1"],
  "force_refresh": false
}

Campo	Tipo	Obrigatório	Descrição
document	string	Sim	CPF ou CNPJ (com ou sem máscara). Validado com mod-11.
courts	string[]	Sim	Códigos dos tribunais. Use GET /courts pra descobrir quais estão ativos.
force_refresh	boolean	Não (default false)	Quando true, pula cache e sempre faz scraping novo. 5x o custo.

Response — cenário 200 (cache hit)

{
  "data": {
    "source": "cache",
    "stale": false,
    "consult_id": "550e8400-e29b-41d4-a716-446655440000",
    "document": "529.982.247-25",
    "courts": [
      {
        "court": "TJSP",
        "system": "esaj",
        "source": "cache",
        "stale": false,
        "extracted_at": "2026-04-15T14:30:00Z",
        "processes": [
          {
            "numero_processo_unico": "1234567-89.2024.8.26.0100",
            "classe": "Procedimento Comum Cível",
            "situacao": "Em andamento",
            "instance": "1",
            "partes": [...],
            "movimentos": [...],
            "assuntos": [...]
          }
        ]
      }
    ]
  }
}

O formato é padronizado independente do tribunal — ESAJ e PJE retornam a mesma shape JSON.

Response — cenário 202 (nova consulta)

{
  "data": {
    "source": "processing",
    "consult_id": "550e8400-e29b-41d4-a716-446655440000",
    "courts": [
      { "court": "TJSP", "system": "esaj", "status": "queued" },
      { "court": "TJMG", "system": "pje", "status": "queued" }
    ]
  }
}

Faça polling em GET /consults/{consult_id} a cada 2-5 segundos até status: "done".

Exemplos em 3 linguagens

cURL

# Criar consulta
curl -X POST https://vigilant.trackjud.com.br/api/v1/consults \
  -H "Authorization: Bearer vgl_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"document":"529.982.247-25","courts":["TJSP","TJMG"]}'

# Polling
curl https://vigilant.trackjud.com.br/api/v1/consults/UUID \
  -H "Authorization: Bearer vgl_sua_chave"

Python

import requests, time

API = "https://vigilant.trackjud.com.br/api/v1"
headers = {"Authorization": "Bearer vgl_sua_chave"}

# Criar
resp = requests.post(f"{API}/consults", headers=headers, json={
    "document": "529.982.247-25",
    "courts": ["TJSP", "TJMG"]
})
data = resp.json()["data"]

if resp.status_code == 200:
    print("Cache hit:", data)
else:
    # Polling
    cid = data["consult_id"]
    while True:
        r = requests.get(f"{API}/consults/{cid}", headers=headers)
        d = r.json()["data"]
        if d["status"] == "done":
            print("Done:", d)
            break
        time.sleep(3)

JavaScript (Node.js)

const API = "https://vigilant.trackjud.com.br/api/v1";
const headers = { Authorization: "Bearer vgl_sua_chave", "Content-Type": "application/json" };

const resp = await fetch(`${API}/consults`, {
  method: "POST", headers,
  body: JSON.stringify({ document: "529.982.247-25", courts: ["TJSP", "TJMG"] }),
});
const { data } = await resp.json();

if (resp.status === 200) {
  console.log("Cache hit:", data);
} else {
  const poll = async () => {
    const r = await fetch(`${API}/consults/${data.consult_id}`, { headers });
    const d = (await r.json()).data;
    if (d.status === "done") return d;
    await new Promise(r => setTimeout(r, 3000));
    return poll();
  };
  console.log("Done:", await poll());
}

Caso real — fintech integrou em 1 semana

Uma fintech de crédito consignado integrou a API do Vigilant no motor de aprovação em 5 dias úteis:

• Dia 1: dev fez primeira chamada via Postman, entendeu cache + polling
• Dia 2-3: integrou no backend (Python/FastAPI) — webhook do formulário de crédito chama API, resultado é gravado no banco
• Dia 4: conectou ao motor de decisão como feature adicional (processo_count, has_execution_fiscal, has_criminal)
• Dia 5: testes em staging + deploy em produção
• Volume pós-deploy: 500 consultas/dia, custo ~R$ 50/dia, 4.2% de clientes flagged com risco judicial

Pra mais detalhes sobre integração em fintech, veja KYC judicial: por que dados judiciais são o próximo bureau.

Custos

Operação	Custo
1 tribunal consultado	R$ 0,10 (1 crédito)
1 CPF em 5 tribunais	R$ 0,50
1 CPF em 12 tribunais	R$ 1,20
force_refresh	5x o custo normal (5 créditos/tribunal)
Cache hit (< 2 dias)	Gratuito
Tribunal fora do ar	Crédito devolvido automaticamente

Sem mensalidade, sem contrato, sem mínimo. Créditos nunca expiram. Tabela completa em /pricing/.

Recursos pra integrar

• Scalar UI interativa — teste requests no browser
• OpenAPI JSON spec — gere client em qualquer linguagem
• Postman collection — 6 endpoints prontos com auto-capture de consult_id
• Health check — pra monitoramento upstream
• /developers/ — landing com mais code samples + integration patterns
• /ferramentas/ — tools grátis (validador CPF, decoder CNJ, etc) úteis em testes
• /tribunais/ — cobertura por tribunal com status individual

Glossário

Termo	Definição
REST	Arquitetura de API baseada em HTTP com recursos endereçáveis
Bearer token	Mecanismo de autenticação onde a API key é enviada no header Authorization
OpenAPI	Padrão de documentação de APIs. Vigilant usa versão 3.1
RFC 7807	Padrão de formato de erro HTTP (Problem Details)
Polling	Técnica de consultar o resultado repetidamente até estar pronto
Cache	Resultado armazenado por 2 dias — consulta repetida é gratuita
force_refresh	Flag que pula o cache e força scraping novo (5x custo)
Consult	Uma requisição de pesquisa de 1 CPF em N tribunais
Court search	Pesquisa individual de 1 tribunal dentro de um consult

Conclusão

A API do Vigilant resolve o problema de acesso unificado a dados judiciais brasileiros pra quem precisa integrar isso no próprio software. Sem scraping, sem captcha, sem manutenção de layout de tribunal. REST + JSON + OpenAPI 3.1 + RFC 7807 — padrões que qualquer dev conhece.

5 créditos grátis no cadastro. Primeira chamada em 5 minutos. Integração mínima em 2-4 horas.

Pra volume enterprise, rate limit dedicado e suporte técnico, vale conversar com a equipe em /fale-conosco/. Pra a camada comercial completa (soluções por segmento), veja soluções pra fintechs e developers.

---

5 créditos grátis no cadastro, sem cartão. Comece agora.