DataJud SDK

SDK TypeScript enxuto, tipado e independente de frameworks para a API Pública do DataJud.

npm install @lorenzoalberto-dev/datajud-sdk

Consulte processos, componha Query DSL com segurança, resolva tribunais pelo número CNJ e percorra grandes conjuntos de resultados sem lidar diretamente com os detalhes do Elasticsearch.

Projeto independente, sem vínculo oficial com o Conselho Nacional de Justiça. A API Pública do DataJud está sujeita a alterações.

Por que usar

• API pequena e centrada em DataJudClient.search()
• Tipagem completa para consultas, processos e respostas
• Query Builder para os filtros processuais mais comuns
• Paginação contínua com search_after e Async Iterator
• Normalização e validação de números processuais CNJ
• Resolução automática de tribunais
• Timeout, AbortSignal e retry com backoff
• Rate limiting local de 120 requisições por minuto
• Erros HTTP consistentes e sem uso de any
• Zero dependências em runtime

Início rápido

import { DataJudClient, QueryBuilder } from '@lorenzoalberto-dev/datajud-sdk';

const client = new DataJudClient({
  apiKey: process.env.DATAJUD_API_KEY!,
});

const query = new QueryBuilder()
  .classe(1116)
  .orgaoJulgador(13597)
  .intervaloDatas('2024-01-01', '2024-12-31')
  .build();

const response = await client.search('TJDFT', {
  query,
  source: ['numeroProcesso', 'classe', 'orgaoJulgador'],
  size: 100,
});

for (const hit of response.hits.hits) {
  console.log(hit._source.numeroProcesso);
}

O primeiro argumento de search() é o alias publicado pelo CNJ, como TJSP, TRF1, TRT15, TRE-SP ou STJ.

Paginação

Percorra resultados com search_after sem gerenciar o cursor manualmente:

const query = new QueryBuilder().intervaloDatas('2024-01-01', '2024-12-31').build();

for await (const processo of client.iterate('TJSP', {
  query,
  source: ['numeroProcesso', '@timestamp'],
  pageSize: 500,
})) {
  console.log(processo.numeroProcesso);
}

Consulta por número CNJ

ProcessosService valida o número, identifica o tribunal e executa a pesquisa:

import { DataJudClient, ProcessosService } from '@lorenzoalberto-dev/datajud-sdk';

const client = new DataJudClient({
  apiKey: process.env.DATAJUD_API_KEY!,
});

const processos = new ProcessosService(client);
const response = await processos.porNumero('0000832-35.2018.4.01.3202');

Os helpers também podem ser usados isoladamente:

import { isValidNumeroProcesso, parseNumeroProcesso } from '@lorenzoalberto-dev/datajud-sdk';

isValidNumeroProcesso('0000832-35.2018.4.01.3202'); // true
parseNumeroProcesso('0000832-35.2018.4.01.3202').alias; // TRF1

Configuração

const client = new DataJudClient({
  apiKey: process.env.DATAJUD_API_KEY!,
  timeout: 30_000,
  retries: 3,
  retryDelay: 250,
  logger: console,
});

| Opção | Padrão | Finalidade | | ------------ | ----------: | ---------------------------------------- | | apiKey | obrigatória | Chave usada no cabeçalho Authorization | | timeout | 30000 | Tempo máximo de cada tentativa, em ms | | retries | 3 | Número máximo de novas tentativas | | retryDelay | 250 | Intervalo-base do backoff, em ms | | rateLimit | 120 rpm | Limite local por instância do cliente | | cache | — | Implementação opcional de cache | | logger | — | Interface simples para logs | | fetch | global | Implementação alternativa de fetch |

A chave da API é pública, mas pode ser alterada pelo CNJ. Consulte a página oficial de acesso e mantenha seu valor configurável.

Tratamento de erros

import {
  AuthenticationError,
  DataJudError,
  RateLimitError,
  ValidationError,
} from '@lorenzoalberto-dev/datajud-sdk';

try {
  await client.search('TJSP');
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('A chave foi recusada pelo DataJud.');
  } else if (error instanceof RateLimitError) {
    console.error('O limite de requisições foi excedido.');
  } else if (error instanceof ValidationError) {
    console.error(error.message);
  } else if (error instanceof DataJudError) {
    console.error(error.status, error.body);
  }
}

Documentação

• Guia completo e referência da API
• Guia do explorador web
• Runbook operacional
• Endpoints oficiais do DataJud
• Glossário oficial de campos

Desenvolvimento

git clone https://github.com/lorenzoalberto/datajud-sdk.git
cd datajud-sdk
npm install
npm run check
npm run smoke:package

O repositório também inclui um explorador web local:

cd frontend
cp .env.example .env
npm install
npm start

Escopo

O SDK utiliza exclusivamente o endpoint público de pesquisa:

POST /api_publica_{alias}/_search

O projeto mantém um único pacote e prioriza uma API pública pequena e confiável. Plugins, múltiplos pacotes, inferência avançada de _source e infraestrutura excessiva permanecem fora do escopo até existir demanda concreta.

Licença

Distribuído sob a Licença MIT.