Como Validar Número de Processo CNJ (Módulo 97): Algoritmo em Python, JavaScript e TypeScript

Em formulários de cadastro, planilhas importadas por clientes e extrações via OCR/LLM de petições em PDF, cerca de 4% a 9% dos números de processos chegam com dígitos trocados, zeros à esquerda cortados pelo Excel ou hífens fora do padrão. Disparar requisições de rede para números corrompidos desperdiça fila de processamento e gera erros evitáveis.

Neste guia para desenvolvedores entregamos a anatomia exata da Resolução CNJ nº 65/2008, a armadilha clássica de precisão numérica em JavaScript e funções prontas para produção em TypeScript/JavaScript e Python antes de consultar a API de processos judiciais do BuscaProcessos.

1. Anatomia dos 20 dígitos (NNNNNNN-DD.AAAA.J.TR.OOOO)

Quando removemos pontos e traços, sobram exatamente 20 dígitos numéricos divididos em seis campos fixos:

Dica de planilha Excel: quando alguém abre um CSV no Excel sem tipar a coluna como texto, 00012345620248260100 perde os zeros iniciais e vira notação científica (1,23456E+16), destruindo os últimos dígitos. Se o número tiver entre 14 e 19 dígitos inteiros apenas porque perdeu zeros à esquerda, padStart(20, '0') recupera o CNJ e o módulo 97 confirma se a restauração é íntegra!

2. Implementação em TypeScript / JavaScript (usando BigInt)

Nunca converta os 20 dígitos com Number(...) ou parseInt(...): como Number.MAX_SAFE_INTEGER suporta apenas 53 bits (~15,9 dígitos decimais), os últimos 4 dígitos sofrem arredondamento silencioso e quebram o cálculo do módulo 97. Usando BigInt (nativo desde o ES2020 / Node 14+), a validação executa em microssegundos:

export type ParsedCnj = {
  formatted: string;
  digits: string;
  sequencial: string;
  dv: string;
  ano: number;
  justica: string;
  tribunal: string;
  origem: string;
  jtr: string;
};

export function parseAndValidateCnj(raw: string): ParsedCnj | null {
  const digits = raw.replace(/\D+/g, "");
  if (digits.length === 0 || digits.length > 20) return null;

  const normalized = digits.padStart(20, "0");
  if (/^0+$/.test(normalized)) return null;

  const sequencial = normalized.slice(0, 7);
  const dv = normalized.slice(7, 9);
  const anoStr = normalized.slice(9, 13);
  const justica = normalized.slice(13, 14);
  const tribunal = normalized.slice(14, 16);
  const origem = normalized.slice(16, 20);

  const ano = Number(anoStr);
  if (ano < 1900 || ano > 2100 || justica === "0") return null;

  // Resolução CNJ 65/2008: (NNNNNNN + AAAA + J + TR + OOOO + DD) mod 97 === 1
  const rearranged = `${sequencial}${anoStr}${justica}${tribunal}${origem}${dv}`;
  if (BigInt(rearranged) % 97n !== 1n) {
    return null;
  }

  return {
    formatted: `${sequencial}-${dv}.${anoStr}.${justica}.${tribunal}.${origem}`,
    digits: normalized,
    sequencial,
    dv,
    ano,
    justica,
    tribunal,
    origem,
    jtr: `${justica}.${tribunal}`,
  };
}

3. Implementação em Python (zero dependências)

Em Python 3, o tipo int já opera com precisão arbitrária, tornando o validador e o calculador de DV ideais para pipelines de ETL, pandas/Polars e FastAPI:

import re
from dataclasses import dataclass

@dataclass(frozen=True)
class CnjNumber:
    formatted: str
    digits: str
    ano: int
    jtr: str
    origem: str

def parse_cnj(raw: str) -> CnjNumber | None:
    digits = re.sub(r"\D+", "", raw or "")
    if not digits or len(digits) > 20:
        return None

    normalized = digits.zfill(20)
    if normalized == "0" * 20:
        return None

    seq = normalized[0:7]
    dv = normalized[7:9]
    ano_str = normalized[9:13]
    justica = normalized[13:14]
    tribunal = normalized[14:16]
    origem = normalized[16:20]

    ano = int(ano_str)
    if not (1900 <= ano <= 2100) or justica == "0":
        return None

    rearranged = f"{seq}{ano_str}{justica}{tribunal}{origem}{dv}"
    if int(rearranged) % 97 != 1:
        return None

    return CnjNumber(
        formatted=f"{seq}-{dv}.{ano_str}.{justica}.{tribunal}.{origem}",
        digits=normalized,
        ano=ano,
        jtr=f"{justica}.{tribunal}",
        origem=origem,
    )

4. Tabela rápida de códigos J.TR para roteamento

Com o campo jtr validado, seu sistema já sabe qual corte julga o processo — e pode inclusive verificar programaticamente ou visualmente no monitor de status dos tribunais se aquele tribunal está com instabilidade no PJe, e-SAJ, eproc ou Projudi:

• 8.01 a 8.27 (Justiça Estadual — 27 TJs): 8.26 = TJSP, 8.19 = TJRJ, 8.13 = TJMG, 8.16 = TJPR, 8.21 = TJRS, 8.24 = TJSC, 8.05 = TJBA, 8.06 = TJCE, 8.07 = TJDFT, 8.08 = TJES, 8.09 = TJGO, 8.12 = TJMS, 8.14 = TJPA, 8.17 = TJPE.
• 5.01 a 5.24 (Justiça do Trabalho — 24 TRTs): 5.02 = TRT-2 (SP Capital), 5.15 = TRT-15 (Campinas/Interior SP), 5.01 = TRT-1 (RJ), 5.03 = TRT-3 (MG), 5.04 = TRT-4 (RS).
• 4.01 a 4.06 (Justiça Federal — 6 TRFs): 4.01 = TRF-1, 4.02 = TRF-2, 4.03 = TRF-3, 4.04 = TRF-4, 4.05 = TRF-5, 4.06 = TRF-6 (MG).

5. Do CNJ validado para a capa, movimentações e IA

Depois que parseAndValidateCnj aprova o identificador, consulte a capa processual completa, partes, valor da causa, movimentações ou resumo por IA por apenas R$ 0,12 cada na API de Consulta Processual:

curl -sS "https://api.buscaprocessos.app.br/v1/processos/cnj/0001234-56.2024.8.26.0100" \
  -H "x-api-key: ${BUSCAPROCESSOS_API_KEY}"