API DataJud: tutorial completo com exemplos em curl e Python

A API DataJud é a API pública do Conselho Nacional de Justiça que devolve metadados e movimentações de processos judiciais públicos de quase todos os tribunais do país. Ela é gratuita, usa Elasticsearch por baixo e se autentica com uma chave pública única. Neste tutorial você vai montar requisições que funcionam: consulta pelo número do processo, filtros por classe e órgão julgador, paginação de grandes volumes e a leitura correta dos campos.

Todos os exemplos foram executados contra a API em setembro de 2026. No fim, mostramos o que o DataJud não entrega e como transformar essas consultas em um monitoramento de processos de verdade. Se você ainda está decidindo entre as APIs do CNJ, comece pela visão geral da API CNJ.

O que é a API Pública do DataJud

O DataJud é a Base Nacional de Dados do Poder Judiciário, regulamentada pela Portaria CNJ nº 160/2020. Os tribunais enviam os dados dos seus processos ao CNJ, e a API pública expõe a parte que pode ser divulgada: a "capa" do processo e a lista de movimentações. Processos sigilosos e dados pessoais das partes ficam de fora.

Por baixo há um cluster Elasticsearch com um índice por tribunal. Por isso as buscas usam o Query DSL do Elasticsearch (match, bool, range, sort, agregações) e não parâmetros de URL. A documentação oficial fica na wiki do DataJud e declara que a API está em fase beta.

Como acessar a API DataJud: chave pública e cabeçalho

Não há cadastro. O CNJ publica uma chave pública na página Acesso da wiki, e você a envia no cabeçalho Authorization no formato APIKey <chave>. O CNJ avisa que a chave pode ser alterada a qualquer momento. Por isso, guarde-a em variável de ambiente ou num cofre de segredos e trate respostas 401 como sinal para conferir a wiki.

export DATAJUD_API_KEY="SUA_CHAVE"

Usar a API implica aceitar o termo de uso. Três cláusulas merecem atenção de quem desenvolve: a API é fornecida para fins legais, não comerciais e autorizados; o usuário concorda em não vender nem explorar comercialmente a API ou informação derivada dela; e o CNJ não garante precisão, integridade ou atualidade dos dados.

Resumo prático: o DataJud é gratuito e excelente para estudo, pesquisa, prototipagem e validação de uma ideia de monitoramento. Ele não deve ser a fonte de dados de uma API, SaaS ou serviço pago que você venda ou revenda. Para produto comercial, use outras rotas e leia os termos de cada fonte.

Endpoints da API DataJud por tribunal

A URL base é https://api-publica.datajud.cnj.jus.br/, seguida do alias do tribunal e de /_search. Todas as buscas são POST com corpo JSON. Os aliases seguem a sigla do tribunal em minúsculas; na Justiça Eleitoral há hífen antes da UF.

A lista completa cobre STJ, TST, TSE, STM, os seis TRFs, os 27 TJs, os 24 TRTs, os TREs e os três tribunais de Justiça Militar estaduais. O STF não está na API pública: uma consulta ao alias api_publica_stf retornou index_not_found_exception no nosso teste.

Exemplo 1: consultar um processo pelo número na API DataJud

O campo numeroProcesso guarda os 20 dígitos da numeração única do CNJ, sem pontos e traços. Remova a máscara antes de consultar. Você também precisa saber o tribunal: o segmento J.TR do número (por exemplo, 8.26 para o TJSP e 4.01 para o TRF1) indica para qual endpoint enviar.

curl -sS -X POST "https://api-publica.datajud.cnj.jus.br/api_publica_trf1/_search" \
  -H "Authorization: APIKey $DATAJUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": { "numeroProcesso": "00008323520184013202" }
    }
  }'

import os
import re
import requests

BASE = "https://api-publica.datajud.cnj.jus.br"
HEADERS = {
    "Authorization": f"APIKey {os.environ['DATAJUD_API_KEY']}",
    "Content-Type": "application/json",
}

def consultar_processo(tribunal: str, numero: str) -> dict | None:
    numero = re.sub(r"\D", "", numero)  # 0000832-35.2018.4.01.3202 -> 00008323520184013202
    corpo = {"query": {"match": {"numeroProcesso": numero}}}
    resp = requests.post(f"{BASE}/api_publica_{tribunal}/_search",
                         headers=HEADERS, json=corpo, timeout=60)
    resp.raise_for_status()
    hits = resp.json()["hits"]["hits"]
    return hits[0]["_source"] if hits else None

processo = consultar_processo("trf1", "0000832-35.2018.4.01.3202")
if processo:
    print(processo["classe"]["nome"], "-", processo["orgaoJulgador"]["nome"])
    for mov in processo.get("movimentos", [])[-5:]:
        print(mov["dataHora"], mov["codigo"], mov["nome"])

A resposta segue o formato padrão do Elasticsearch: os documentos ficam em hits.hits[]._source. Um mesmo número pode aparecer em mais de um documento, por exemplo um para o primeiro grau (G1) e outro para o segundo (G2). Trate o resultado como lista e use o campo grau para distinguir.

Exemplo 2: filtrar por classe processual e órgão julgador

Para buscas por critérios, combine filtros com bool. Os códigos de classe, assunto e movimento seguem as Tabelas Processuais Unificadas (TPU) do CNJ; o código 1116, por exemplo, é a classe Execução Fiscal. O código do órgão julgador é o da serventia no tribunal.

{
  "size": 100,
  "_source": ["numeroProcesso", "classe", "orgaoJulgador", "@timestamp"],
  "query": {
    "bool": {
      "must": [
        { "match": { "classe.codigo": 1116 } },
        { "match": { "orgaoJulgador.codigo": 83313 } }
      ],
      "filter": [
        { "range": { "@timestamp": { "gte": "now-30d" } } }
      ]
    }
  },
  "sort": [{ "@timestamp": { "order": "asc" } }]
}

Um aviso prático: o exemplo oficial da wiki usa o órgão 13597, mas em setembro de 2026 esse código não retornava mais nada, e os processos equivalentes apareciam sob o código 83313. Códigos de órgão mudam. Para descobrir os códigos atuais, rode uma agregação antes de filtrar:

{
  "size": 0,
  "query": { "match": { "classe.codigo": 1116 } },
  "aggs": {
    "orgaos": { "terms": { "field": "orgaoJulgador.codigo", "size": 20 } },
    "graus":  { "terms": { "field": "grau.keyword" } }
  }
}

Paginação na API DataJud com size e search_after

Por padrão, cada busca devolve 10 documentos. O parâmetro size aceita até 10.000, e esse também é o teto da janela de resultados: from + size acima de 10.000 retorna erro Result window is too large. Para percorrer volumes maiores, a wiki recomenda search_after: ordene por @timestamp e, na próxima requisição, envie o valor sort do último documento recebido.

import os
import requests

URL = "https://api-publica.datajud.cnj.jus.br/api_publica_tjdft/_search"
HEADERS = {
    "Authorization": f"APIKey {os.environ['DATAJUD_API_KEY']}",
    "Content-Type": "application/json",
}

def buscar_todos(query: dict, tamanho_pagina: int = 100):
    corpo = {
        "size": tamanho_pagina,
        "query": query,
        "sort": [{"@timestamp": {"order": "asc"}}],
    }
    while True:
        resp = requests.post(URL, headers=HEADERS, json=corpo, timeout=60)
        resp.raise_for_status()
        hits = resp.json()["hits"]["hits"]
        if not hits:
            break
        for hit in hits:
            yield hit["_source"]
        corpo["search_after"] = hits[-1]["sort"]

query = {"bool": {"must": [
    {"match": {"classe.codigo": 1116}},
    {"match": {"orgaoJulgador.codigo": 83313}},
]}}

for processo in buscar_todos(query):
    print(processo["numeroProcesso"], len(processo.get("movimentos", [])))

Páginas de 100 a 1.000 documentos costumam equilibrar bem tempo de resposta e número de chamadas, porque cada documento carrega a lista inteira de movimentações. Use _source para trazer só os campos de que você precisa. A wiki não publica um limite de requisições; mesmo assim, espace as chamadas e evite paralelismo agressivo, já que o serviço é compartilhado por todo o país.

Campos retornados pela API DataJud

O documento é plano, sem blocos como dadosBasicos (esse nome é do MNI, usado nos web services dos tribunais). Os campos abaixo vêm do glossário oficial e foram conferidos em respostas reais.

Espere inconsistências. Em respostas reais encontramos dataAjuizamento no formato 20181029000000 enquanto a wiki mostra ISO 8601, códigos de órgão diferentes dos exemplos e nomes de vara com acentuação quebrada. Um parser robusto aceita variações e registra o que não conseguiu interpretar.

Limites da API DataJud: o que ela não entrega

• Não é tempo real: Os tribunais enviam dados em lotes. Em setembro de 2026, o documento mais recente de índices como TJSP e STJ tinha entre cinco e onze dias. Não use o DataJud para contar prazo.
• Sem partes, advogados e documentos: Não há nomes, CPF, CNPJ, OAB, petições nem inteiro teor de decisões. Para publicações e intimações, a fonte é o DJEN, que explicamos no artigo sobre a API CNJ.
• Sem processos sigilosos e sem STF: Segredo de justiça fica fora da API pública, e o Supremo não tem índice nela.
• Janela de 10.000 resultados: Tanto o size máximo quanto from + size param em 10.000. Acima disso, use search_after.
• Beta e sem garantia: A própria wiki chama a API de beta, e o termo de uso afasta garantia de precisão e atualidade. A chave pode mudar sem aviso prévio.
• Uso não comercial: O item 3.3 do termo de uso limita a API a fins legais, não comerciais e autorizados, e o item 3.8 proíbe distribuir, vender ou explorar comercialmente a API ou informação derivada dela. Um serviço pago não pode ter o DataJud como fonte.

Como monitorar movimentações com a API DataJud

O padrão de monitoramento é simples: guarde a lista de processos do cliente, consulte periodicamente e compare. Três decisões fazem diferença na prática.

• Chave de deduplicação: Identifique cada movimento por numeroProcesso + grau + codigo + dataHora. É estável entre coletas e evita alertas repetidos.
• Coleta incremental: Para acompanhar um tribunal inteiro ou uma vara, filtre por @timestamp maior que a última execução em vez de baixar tudo de novo.
• Frequência compatível com a fonte: Como os lotes chegam com defasagem, uma consulta diária por processo costuma ser suficiente. Consultar a cada minuto só gera carga, sem dado novo.

Vale a pena criar sua própria API jurídica sobre o DataJud?

Aqui é preciso separar duas coisas. O DataJud é o melhor laboratório gratuito que existe para aprender como dados processuais se comportam: você entende a numeração CNJ, as tabelas TPU, a estrutura de movimentações e a detecção de mudanças sem gastar nada. Mas, pelo termo de uso, ele não pode ser a fonte de uma API ou SaaS que você cobre de clientes. Construir a sua própria API jurídica como produto significa apoiar a operação em outras rotas: a API de comunicações do DJEN para publicações (verifique os termos dela), consultas públicas dos tribunais respeitando captcha e termos, o MNI com credenciais adequadas ou provedores comerciais licenciados.

Os provedores que comparamos em Jusbrasil API e Escavador API entregam coisas prontas, como partes, documentos e captura de vários tribunais, mas o preço acompanha o volume. Já a solução própria exige manutenção: códigos que mudam, formatos que variam, fontes que saem do ar e termos de uso que precisam de revisão jurídica. Com isso em mente, compare:

Arquitetura de uma API jurídica própria

• Fontes: Para estudo e protótipo, o DataJud. Para um produto comercial, fontes compatíveis com esse uso: publicações do DJEN (conforme os termos da API), consultas públicas e MNI dos tribunais quando houver credenciamento e os termos permitirem, ou provedores licenciados. Veja o guia de API do PJe.
• Coletor: Jobs agendados por tribunal, com fila, retentativa com espera crescente, respeito aos limites de requisição e log de cada execução.
• Normalização: Número CNJ, datas, códigos TPU e nomes de órgão em formato único, com tolerância às variações de cada tribunal.
• Banco de dados: Processos, movimentos e publicações em tabelas separadas, com histórico. PostgreSQL com índice no número CNJ atende bem.
• Detecção de mudanças e alertas: Diferença entre a coleta atual e a anterior, gerando eventos que viram e-mail, mensagem ou webhook assinado para o sistema do cliente.
• Camada de API: REST autenticado por cliente, com isolamento entre escritórios, limites de uso e trilha de auditoria.

Para comparar o DataJud com outras fontes e fornecedores, veja o guia de API de processos judiciais. Se prefere construir com um roteiro pronto, o workshop de robô de monitoramento processual usa o método que está em produção no escritório Mattozo & Ribeiro Advocacia.