Consulta Síncrona ao Datalake (Hot Storage)

Novo CNPJ (IN 2229/24)A Judit já aceita o novo formato de CNPJ alfanumérico em conformidade com a Instrução Normativa RFB nº 2229/2024.

Zero esforço: nenhuma alteração é necessária na sua integração.
Ambiente de teste: utilize o documento A1B2C3D4/E5F6-68 para validar o fluxo e receber um processo fictício de resposta.

A Consulta Síncrona ao Hot Storage retorna, em milissegundos, todos os processos do nosso datalake vinculados a um CPF, CNPJ, OAB, Nome ou CNJ. Não há fila nem espera por tribunal: a resposta vem direto do cache JUDIT.

🤖 Endpoint: POST https://lawsuits.production.judit.io/lawsuits. A resposta é síncrona (HTTP 200 com o JSON pronto). Esta rota não vai ao tribunal — ela lê o datalake da Judit, então pode haver um pequeno atraso em relação ao estado mais atual do processo. Se precisar de dados atualizados em tempo real, use POST /requests (assíncrono).

Buscando por número de processo (CNJ)?Esta rota é recomendada para descoberta por CPF, CNPJ, OAB ou Nome. Para consultas por número de processo (CNJ), o dado no datalake pode estar desatualizado — ou o processo pode nem existir ainda em nossa base. Use a Consulta On-Demand para garantir atualização em tempo real no tribunal sem sair do fluxo síncrono.

Síncrono vs. assíncrono — qual escolher?

Característica	Síncrono (Hot Storage)	Assíncrono (Requests)
Latência	ms (resposta imediata)	segundos a minutos
Fonte	Datalake JUDIT (cache)	Tribunal em tempo real
Atualidade	Última coleta da JUDIT	Estado atual do tribunal
Webhook	Não aplicável	Sim, opcional
Custo	Mais barato	Mais caro
Caso ideal	Validação rápida, dashboards, busca interativa	Diligência, atualização forçada, consulta sob demanda

Quando usar

Validação em tempo real

Onboarding, KYC, autocomplete — sempre que precisar de uma resposta imediata para a UI.

Dashboards interativos

Dashboards e BI que listam processos vinculados a um cliente sem precisar atualizar o tribunal.

Pré-filtragem de risco

Antes de disparar uma consulta assíncrona cara, descubra rapidamente se vale a pena.

Estatísticas e contagens

Combine com /lawsuits/count e /lawsuits/synthetic para análises agregadas.

Todas as consultas síncronas aceitam filtros (tribunal, valor da causa, classes, partes, datas, fase). Veja a lista completa em filtros da consulta histórica — o mesmo objeto search_params.filter se aplica aqui.

Passo 1: Criar a Consulta Síncrona (POST)

Para iniciar a consulta síncrona, faça uma requisição POST enviando o documento desejado. POST https://lawsuits.production.judit.io/lawsuits

Exemplos de consultas síncronas

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "99.999.999/9999-99"
    }
}

{
    "search": {
        "search_type": "oab",
        "search_key": "99999RJ"
    }
}

{
    "search": {
        "search_type": "name",
        "search_key": "João Silva"
    }
}

Ao realizar consultas por nome, é possível que existam homônimos. Sempre que possível, prefira CPF, CNPJ ou OAB para garantir maior precisão.

Parâmetros do Payload

Parâmetro	Tipo	Obrigatório	Descrição
`search.search_type`	string	Sim	Tipo da entidade buscada: `"cpf"`, `"cnpj"`, `"oab"` ou `"name"`.
`search.search_key`	string	Sim	O valor a ser buscado (ex.: `"999.999.999-99"`, `"João Silva"`).
`search.search_params.filter`	object	Não	Filtros estruturais (tribunal, valor, classes, partes, datas). Mesma estrutura da consulta histórica.
`search.search_params.with_inferred_parties`	boolean	Não	Se `true`, inclui na busca os processos em que o vínculo com o documento pesquisado foi inferido pela Judit. Padrão: `false`.

Inferência de Partes (`search_params.with_inferred_parties`)

Boa parte dos tribunais não publica o CPF/CNPJ das partes — apenas o nome. Com with_inferred_parties: true, a consulta passa a considerar também os processos em que o vínculo com o documento pesquisado foi inferido por validações internas da Judit, e não lido diretamente do tribunal. O parâmetro é opt-in: quando omitido, vale false.

Consulta com inferência de partes

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "with_inferred_parties": true
        }
    }
}

Cada parte na resposta traz o campo was_inferred: false quando o documento foi publicado pelo próprio tribunal e true quando foi inferido pela Judit (nesse caso o array documents normalmente vem vazio e o main_document é o resultado da inferência). Trate a ausência do campo como false — a consulta histórica traz um exemplo de resposta com parte inferida.

Risco de homônimos. Como a inferência parte do nome da parte, existe a possibilidade de vincular ao documento pesquisado um processo que pertence, na verdade, a outra pessoa ou empresa de nome igual ou muito semelhante. As validações internas reduzem esse risco, mas não o eliminam. Em buscas com search_type: "name", esse risco se soma ao dos homônimos do próprio termo pesquisado.Use o was_inferred para decidir como tratar cada processo: um vínculo inferido não tem a mesma confiabilidade de um documento publicado pelo tribunal.

Filtros mais comuns (`search_params.filter`)

A consulta síncrona aceita os mesmos filtros da consulta histórica. Veja exemplos práticos:

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "tribunals": { "keys": ["TJRJ"], "not_equal": false }
            }
        }
    }
}

{
    "search": {
        "search_type": "cnpj",
        "search_key": "00.000.000/0001-00",
        "search_params": {
            "filter": {
                "side": "Passive",
                "amount_gte": 50000
            }
        }
    }
}

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "distribution_date_gte": "2024-01-01T00:00:00.000Z",
                "distribution_date_lte": "2024-12-31T23:59:59.000Z"
            }
        }
    }
}

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "tribunals": { "keys": ["TJSP"], "not_equal": true }
            }
        }
    }
}

Lista completa de tribunais aceitos: veja Filtros da consulta histórica.

Exemplo de Requisição (POST)

curl --request POST \
  --url 'https://lawsuits.production.judit.io/lawsuits' \
  --header 'Content-Type: application/json' \
  --header 'api-key: '"$JUDIT_API_KEY" \
  --data '{
    "search": {
      "search_type": "cpf",
      "search_key": "999.999.999-99"
    }
  }'

import os, requests

resp = requests.post(
    "https://lawsuits.production.judit.io/lawsuits",
    headers={
        "api-key": os.environ["JUDIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "search": {"search_type": "cpf", "search_key": "999.999.999-99"},
    },
    timeout=15,
)
resp.raise_for_status()
print(resp.json())

const res = await fetch("https://lawsuits.production.judit.io/lawsuits", {
  method: "POST",
  headers: {
    "api-key": process.env.JUDIT_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    search: { search_type: "cpf", search_key: "999.999.999-99" },
  }),
});
console.log(await res.json());

package main

import (
    "bytes"
    "encoding/json"
    "io"
    "net/http"
    "os"
)

func main() {
    body, _ := json.Marshal(map[string]any{
        "search": map[string]string{
            "search_type": "cpf",
            "search_key":  "999.999.999-99",
        },
    })
    req, _ := http.NewRequest("POST",
        "https://lawsuits.production.judit.io/lawsuits",
        bytes.NewReader(body))
    req.Header.Set("api-key", os.Getenv("JUDIT_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    println(string(out))
}

Passo 2: Ler a resposta

A resposta vem no corpo do mesmo POST (não há polling). Os campos principais:

Campo	Tipo	Descrição
`has_lawsuits`	boolean	`true` se foram encontrados processos no datalake.
`request_id`	string	Identificador único da consulta — útil para auditoria.
`response_data`	array	Lista de processos. Cada item segue o Schema Lawsuit.
`response_data[].phase`	string	Fase atual do processo — ver tabela abaixo.
`response_data[].status`	string	Status atual do processo — ver tabela abaixo.

Exemplo completo de resposta

Ver exemplo de resposta

A resposta dessa requisição será um objeto JSON com os dados retornados:

{
    "has_lawsuits": true,
    "request_id": "c37cacba-41b5-4694-919f-4a937f2ea5df",
    "response_data": [
        {
            "code": "9999999-99.9999.9.99.9999",
            "justice": "5",
            "tribunal": "01",
            "instance": 2,
            "distribution_date": "2023-05-18T11:12:59.000Z",
            "tribunal_acronym": "TRT1",
            "secrecy_level": 0,
            "tags": {
                "is_fallback_source": true,
                "crawl_id": "28e00227-e41b-4c94-956e-7a0f105eabee"
            },
            "subjects": [
                { "code": "13656", "name": "DOMÉSTICOS" }
            ],
            "classifications": [
                { "code": "1009", "name": "RECURSO ORDINÁRIO TRABALHISTA" }
            ],
            "courts": [
                { "code": "75580", "name": "GAB DES. GLAUCIA ZUCCARI FERNANDES BRAGA" }
            ],
            "parties": [
                {
                    "name": "Usuário teste",
                    "side": "Active",
                    "person_type": "Autor",
                    "document": "99999999999",
                    "document_type": "CPF",
                    "lawyers": [
                        { "name": "Advogada do Autor", "side": "Active", "person_type": "Advogado" }
                    ],
                    "was_inferred": false
                },
                {
                    "name": "Usuário teste",
                    "side": "Passive",
                    "person_type": "Réu",
                    "document": "99999999999",
                    "document_type": "CPF",
                    "lawyers": [
                        { "name": "Advogado do Réu", "side": "Passive", "person_type": "Advogado" }
                    ],
                    "was_inferred": true
                }
            ],
            "steps": [],
            "attachments": [],
            "related_lawsuits": [],
            "crawler": {
                "source_name": "JTJ - BR - Document / Lawsuit - Auth",
                "crawl_id": "28e00227-e41b-4c94-956e-7a0f105eabee",
                "weight": 0,
                "updated_at": "2024-03-18T19:21:02.466Z"
            },
            "amount": 7685.82,
            "last_step": {
                "lawsuit_cnj": "9999999-99.9999.9.99.9999",
                "lawsuit_instance": 2,
                "step_id": "JZzfEPTs10aeE+vpu+p+bkrz5K7enJhAM5kWattktHk=",
                "step_date": "2024-03-18T19:21:02.466Z",
                "private": false,
                "steps_count": 1
            },
            "name": "Nome do Autor X Nome do Réu"
        }
    ]
}

Estrutura completa de cada item do array response_data: veja Schema Lawsuit.

Erros comuns

HTTP	Quando acontece	Como tratar
`400`	`search_type` ou `search_key` inválidos / formato incorreto.	Validar o documento antes de enviar (ex.: 11 dígitos para CPF, 14 para CNPJ).
`401`	API Key ausente ou inválida.	Conferir o header `api-key`.
`404`	Nenhum processo encontrado. A resposta vem com `has_lawsuits: false` mesmo assim.	Tratar como ausência de exposição judicial — não é necessariamente erro.
`429`	Rate limit excedido (500 req/min).	Implementar exponential backoff lendo `X-RateLimit-Reset`.
`500`	Erro interno transitório.	Repetir com backoff. Se persistir, abrir ticket no suporte.

Próximos passos

Para consultar um processo específico por CNJ com garantia de atualização: Consulta On-Demand.
Para listar e filtrar com mais profundidade (filtros avançados, polo, classes): Consulta Histórica por documento.
Para agregação (contagens por tribunal/área/fase): Consulta Agrupada.
Para forçar leitura em tempo real no tribunal: Consulta Assíncrona.

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Síncrono vs. assíncrono — qual escolher?

Quando usar

Validação em tempo real

Dashboards interativos

Pré-filtragem de risco

Estatísticas e contagens

Passo 1: Criar a Consulta Síncrona (POST)

Exemplos de consultas síncronas

Parâmetros do Payload

Inferência de Partes (`search_params.with_inferred_parties`)

Filtros mais comuns (`search_params.filter`)

Exemplo de Requisição (POST)

Passo 2: Ler a resposta

Exemplo completo de resposta

Erros comuns

Próximos passos

​Síncrono vs. assíncrono — qual escolher?

​Quando usar

Validação em tempo real

Dashboards interativos

Pré-filtragem de risco

Estatísticas e contagens

​Passo 1: Criar a Consulta Síncrona (POST)

​Exemplos de consultas síncronas

​Parâmetros do Payload

​Inferência de Partes (search_params.with_inferred_parties)

​Filtros mais comuns (search_params.filter)

​Exemplo de Requisição (POST)

​Passo 2: Ler a resposta

​Exemplo completo de resposta

​Erros comuns

​Próximos passos

Síncrono vs. assíncrono — qual escolher?

Quando usar

Passo 1: Criar a Consulta Síncrona (POST)

Exemplos de consultas síncronas

Parâmetros do Payload

Inferência de Partes (`search_params.with_inferred_parties`)

Filtros mais comuns (`search_params.filter`)

Exemplo de Requisição (POST)

Passo 2: Ler a resposta

Exemplo completo de resposta

Erros comuns

Próximos passos