Skip to main content
Esta página documenta exclusivamente o fluxo Assíncrono de consulta histórica. O cliente deve fazer um POST /requests, aguardar o processamento (GET /requests/{id}) e resgatar os dados no GET /responses. A resposta da Consulta Histórica retorna um array paginado contendo exclusivamente a Capa e as Partes do processo (omitindo andamentos, anexos, fase e status). É possível filtrar os resultados tanto no payload do POST inicial quanto nas query strings do GET final.

Síncrono vs. Assíncrono

Antes de integrar, é fundamental entender a diferença de arquitetura que a Judit oferece para este endpoint:
  • Consulta Síncrona (Datalake Hotstorage): A resposta com todos os processos é devolvida instantaneamente no corpo (body) do próprio POST. Não exige checagem de status. Ideal para fluxos sensíveis à latência da resposta como onboardings. Veja a documentação Síncrona aqui.
  • Consulta Assíncrona (Datalake / On-Demand): É o fluxo que abordaremos nesta página. Busca em múltiplas fontes externas ou diretamente nos tribunais (On-Demand) em tempo real. Exige um fluxo de 3 etapas (Criar -> Checar -> Consumir).

Passo 1: Criar a Requisição de Busca (POST)

Para iniciar o fluxo assíncrono, faça uma requisição POST informando o documento desejado. POST https://requests.prod.judit.io/requests

Exemplos de consultas históricas

{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99"
    }
}
Ao realizar consultas por nome, é possível que existam homônimos (pessoas ou empresas com o mesmo nome). Recomendamos que, sempre que possível, utilize identificadores únicos, como CPF ou CNPJ, para garantir maior precisão nos resultados.

Parâmetros Base do Payload

ParâmetroTipoObrigatórioDescrição
search.search_typestringSimtipo de entidade que será buscada: "cpf", "cnpj", "oab" ou "name".
search.search_keystringSimO valor a ser buscado (ex: "999.999.999-99", João Silva).
search.on_demandbooleanNãoSe true, força a busca em tempo real nos tribunais em vez do Datalake.
cache_ttl_in_daysintegerNãoConsidera o cache válido se a última extração ocorreu nos últimos X dias.
customer_keystringNãoChave do usuário no Cofre de Credenciais (usado para acessar os tribunais com credenciais cadastrada no cofre de credenciais).
Sobre o uso da customer_key: Esta credencial só terá efeito se o parâmetro on_demand for igual a true. Ao informá-la, a Judit acessará os tribunais de forma autenticada, permitindo a captura de processos em segredo de justiça aos quais o dono da credencial (advogado) esteja previamente vinculado ao respectivo processo.
{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "cache_ttl_in_days": 7
    }
}

Filtros Prévios da Requisição (search_params.filter)

Você pode restringir a busca inicial enviando o objeto filter dentro de search_params no corpo (body) do seu POST. Isso é altamente recomendado, pois evita que o robô perca tempo processando varas ou tribunais de estados ou anos que não importam para o seu negócio. Abaixo, detalhamos como construir cada filtro passo a passo.

1. Filtros de Polo e Valor da Causa

Permite buscar processos onde a pessoa processou alguém, foi processada, ou filtrar por valores em reais.
  • side (string): De qual lado do processo o documento buscado está?
    • "Active" (Autor da ação)
    • "Passive" (Réu na ação)
    • "Interested" (Terceiro interessado)
    • "Unknown" (Polo não identificado)
  • amount_gte (number): Valor da causa Maior ou Igual a (GTE = Greater Than or Equal).
  • amount_lte (number): Valor da causa Menor ou Igual a (LTE = Less Than or Equal).
// Quero achar processos onde o cliente é o Réu ("Passive") 
// E o valor da causa é entre R$ 10.000 e R$ 50.000
{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "side": "Passive",
                "amount_gte": 10000.00,
                "amount_lte": 50000.00
            }
        }
    }
}

2. Filtros de Tribunal (A Regra de Inclusão e Exclusão)

Para filtrar por estados ou tribunais específicos, usamos o objeto tribunals. Ele exige duas informações: a lista de siglas (keys) e uma regra de negação (not_equal).

Lista de Tribunais Aceitos (Filtros)

Utilize as siglas exatas da coluna Sigla (Key) abaixo quando for realizar filtros por tribunais (ex: no parâmetro tribunals.keys).
Sigla (Key)Nome Oficial do Órgão
STFSUPREMO TRIBUNAL FEDERAL
STJSUPERIOR TRIBUNAL DE JUSTIÇA
TSTTRIBUNAL SUPERIOR DO TRABALHO
TSETRIBUNAL SUPERIOR ELEITORAL
STMSUPERIOR TRIBUNAL MILITAR
CNJCONSELHO NACIONAL DE JUSTIÇA
CJFCONSELHO DA JUSTIÇA FEDERAL
CSJTCONSELHO SUPERIOR DA JUSTIÇA DO TRABALHO
Sigla (Key)Nome Oficial do Órgão
TRF1TRIBUNAL REGIONAL FEDERAL DA 1ª REGIÃO
TRF2TRIBUNAL REGIONAL FEDERAL DA 2ª REGIÃO
TRF3TRIBUNAL REGIONAL FEDERAL DA 3ª REGIÃO
TRF4TRIBUNAL REGIONAL FEDERAL DA 4ª REGIÃO
TRF5TRIBUNAL REGIONAL FEDERAL DA 5ª REGIÃO
Sigla (Key)Nome Oficial do Órgão
TRT1TRT DA 1ª REGIÃO (RJ)
TRT2TRT DA 2ª REGIÃO (SP - Capital)
TRT3TRT DA 3ª REGIÃO (MG)
TRT4TRT DA 4ª REGIÃO (RS)
TRT5TRT DA 5ª REGIÃO (BA)
TRT6TRT DA 6ª REGIÃO (PE)
TRT7TRT DA 7ª REGIÃO (CE)
TRT8TRT DA 8ª REGIÃO (PA/AP)
TRT9TRT DA 9ª REGIÃO (PR)
TRT10TRT DA 10ª REGIÃO (DF/TO)
TRT11TRT DA 11ª REGIÃO (AM/RR)
TRT12TRT DA 12ª REGIÃO (SC)
TRT13TRT DA 13ª REGIÃO (PB)
TRT14TRT DA 14ª REGIÃO (RO/AC)
TRT15TRT DA 15ª REGIÃO (SP - Campinas)
TRT16TRT DA 16ª REGIÃO (MA)
TRT17TRT DA 17ª REGIÃO (ES)
TRT18TRT DA 18ª REGIÃO (GO)
TRT19TRT DA 19ª REGIÃO (AL)
TRT20TRT DA 20ª REGIÃO (SE)
TRT21TRT DA 21ª REGIÃO (RN)
TRT22TRT DA 22ª REGIÃO (PI)
TRT23TRT DA 23ª REGIÃO (MT)
TRT24TRT DA 24ª REGIÃO (MS)
Sigla (Key)Nome Oficial do Órgão
TJACTRIBUNAL DE JUSTIÇA DO ACRE
TJALTRIBUNAL DE JUSTIÇA DO ALAGOAS
TJAPTRIBUNAL DE JUSTIÇA DO AMAPÁ
TJAMTRIBUNAL DE JUSTIÇA DO AMAZONAS
TJBATRIBUNAL DE JUSTIÇA DA BAHIA
TJCETRIBUNAL DE JUSTIÇA DO CEARÁ
TJDFTRIBUNAL DE JUSTIÇA DO DISTRITO FEDERAL E TERRITÓRIOS
TJESTRIBUNAL DE JUSTIÇA DO ESPÍRITO SANTO
TJGOTRIBUNAL DE JUSTIÇA DE GOIÁS
TJMATRIBUNAL DE JUSTIÇA DO MARANHÃO
TJMTTRIBUNAL DE JUSTIÇA DO MATO GROSSO
TJMSTRIBUNAL DE JUSTIÇA DO MATO GROSSO DO SUL
TJMGTRIBUNAL DE JUSTIÇA DE MINAS GERAIS
TJPATRIBUNAL DE JUSTIÇA DO PARÁ
TJPBTRIBUNAL DE JUSTIÇA DA PARAÍBA
TJPRTRIBUNAL DE JUSTIÇA DO PARANÁ
TJPETRIBUNAL DE JUSTIÇA DE PERNAMBUCO
TJPITRIBUNAL DE JUSTIÇA DO PIAUÍ
TJRJTRIBUNAL DE JUSTIÇA DO RIO DE JANEIRO
TJSPTRIBUNAL DE JUSTIÇA DE SÃO PAULO
TJRNTRIBUNAL DE JUSTIÇA DO RIO GRANDE DO NORTE
TJRSTRIBUNAL DE JUSTIÇA DO RIO GRANDE DO SUL
TJROTRIBUNAL DE JUSTIÇA DE RONDÔNIA
TJRRTRIBUNAL DE JUSTIÇA DE RORAIMA
TJSCTRIBUNAL DE JUSTIÇA DE SANTA CATARINA
TJSETRIBUNAL DE JUSTIÇA DE SERGIPE
Sigla (Key)Nome Oficial do Órgão
TRE-ACTRIBUNAL REGIONAL ELEITORAL DO ACRE
TRE-ALTRIBUNAL REGIONAL ELEITORAL DO ALAGOAS
TRE-APTRIBUNAL REGIONAL ELEITORAL DO AMAPÁ
TRE-AMTRIBUNAL REGIONAL ELEITORAL DO AMAZONAS
TRE-BATRIBUNAL REGIONAL ELEITORAL DA BAHIA
TRE-CETRIBUNAL REGIONAL ELEITORAL DO CEARÁ
TRE-DFTRIBUNAL REGIONAL ELEITORAL DO DISTRITO FEDERAL
TRE-ESTRIBUNAL REGIONAL ELEITORAL DO ESPÍRITO SANTO
TRE-GOTRIBUNAL REGIONAL ELEITORAL DE GOIÁS
TRE-MATRIBUNAL REGIONAL ELEITORAL DO MARANHÃO
TRE-MTTRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO
TRE-MSTRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO DO SUL
TRE-MGTRIBUNAL REGIONAL ELEITORAL DE MINAS GERAIS
TRE-PATRIBUNAL REGIONAL ELEITORAL DO PARÁ
TRE-PBTRIBUNAL REGIONAL ELEITORAL DA PARAÍBA
TRE-PRTRIBUNAL REGIONAL ELEITORAL DO PARANÁ
TRE-PETRIBUNAL REGIONAL ELEITORAL DE PERNAMBUCO
TRE-PITRIBUNAL REGIONAL ELEITORAL DO PIAUÍ
TRE-RJTRIBUNAL REGIONAL ELEITORAL DO RIO DE JANEIRO
TRE-RNTRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO NORTE
TRE-RSTRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO SUL
TRE-ROTRIBUNAL REGIONAL ELEITORAL DE RONDÔNIA
TRE-RRTRIBUNAL REGIONAL ELEITORAL DE RORAIMA
TRE-SCTRIBUNAL REGIONAL ELEITORAL DE SANTA CATARINA
TRE-SETRIBUNAL REGIONAL ELEITORAL DE SERGIPE
TRE-SPTRIBUNAL REGIONAL ELEITORAL DE SÃO PAULO
TRE-TOTRIBUNAL REGIONAL ELEITORAL DO TOCANTINS
Sigla (Key)Nome Oficial do Órgão
CJM1PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM2SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM3TERCEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM4QUARTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM5QUINTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM6SEXTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM7SÉTIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM8OITAVA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM9NONA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM10DÉCIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM11DÉCIMA PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
CJM12DÉCIMA SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR
TJM-MGTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE MINAS GERAIS
TJM-RSTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DO RIO GRANDE DO SUL
TJM-SPTRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE SÃO PAULO
  • Inclusão: Se not_equal for false, a API vai buscar APENAS nos tribunais da lista.
  • Exclusão: Se not_equal for true, a API vai buscar no Brasil inteiro, EXCETO nos tribunais da lista.

Exemplo JSON: Inclusão vs. Exclusão de Tribunais

// Traz apenas processos de São Paulo e Bahia
{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "search_params": {
            "filter": {
                "tribunals": {
                    "keys": [
                        "TJSP",
                        "TJBA"
                    ],
                    "not_equal": false
                }
            }
        }
    }
}

3. Filtros de Assunto e Classe (Padrão CNJ)

A Judit API utiliza as Tabelas Processuais Unificadas (TPU) oficiais do Conselho Nacional de Justiça (CNJ). Você pode filtrar processos inserindo os códigos numéricos exatos dessas tabelas. 👉 Para descobrir os códigos oficiais de Classes e Assuntos, acesse a Consulta Pública do SGT/CNJ. A mecânica de filtro funciona da seguinte forma:
  • Assuntos (subject_codes): Usa as listas contains (Quero processos que contenham estes códigos) e not_contains (Não quero processos que contenham estes códigos).
  • Classes (classification_codes): Usa a lista keys e a regra not_equal (a mesma lógica de inclusão/exclusão dos tribunais).
{
    "search": {
        "search_type": "cpf",
        "search_key": "99999999999",
        "search_params": {
            "filter": {
                // Quero processos que tenham o assunto 10433, mas rejeito se tiver o 1120
                "subject_codes": {
                    "contains": [
                        "10433"
                    ],
                    "not_contains": [
                        "1120"
                    ]
                },
                // Quero EXATAMENTE a classe processual 985 (ex: Ação Trabalhista)
                "classification_codes": {
                    "keys": [
                        "985"
                    ],
                    "not_equal": false
                }
            }
        }
    }
}

4. Filtros de Datas e Prazos

Otimize a busca por recortes de tempo usando o formato universal de datas (ISO 8601: AAAA-MM-DDTHH:mm:ss.sssZ).
  • distribution_date_gte (string): Traz processos distribuídos (iniciados) a partir de uma data.
  • last_step_date_gte (string): Traz processos cuja última movimentação ocorreu a partir de uma data.
  • last_step_date_lte (string): Traz processos cuja última movimentação ocorreu antes de uma data.
{
    "search": {
        "search_type": "cpf",
        "search_key": "99999999999",
        "search_params": {
            // Quero processos que tiveram alguma movimentação a partir de 10 de Outubro de 2024
            "filter": {
                "last_step_date_gte": "2024-10-10T00:00:00.000Z"
            }
        }
    }
}

5. Filtros Restritivos de Outras Partes

Quer saber se o João processou a Empresa X? Você pode usar os filtros de Nomes e Documentos de outras partes envolvidas no processo.
  • party_names (array de strings): Lista de nomes exatos que devem constar no processo.
  • party_documents (array de strings): Lista de CPFs/CNPJs que devem constar no processo.
Atenção ao usar junto com o filtro side: Se você usar o filtro party_names ou party_documents junto com o filtro side, a regra de “Polo” (Autor/Réu) será aplicada apenas ao documento principal que você está pesquisando, e não aos nomes/documentos extras listados aqui.
{
    "search": {
        "search_type": "cpf",
        "search_key": "99999999999",
        "search_params": {
            // Buscando o CPF principal (via search_key), mas exigindo que
            // a "Empresa Exemplo" ou o CNPJ "99.999.999/0001-99" também estejam no processo.
            "filter": {
                "party_names": [
                    "EMPRESA EXEMPLO LTDA"
                ],
                "party_documents": [
                    "99999999000199"
                ]
            }
        }
    }
}

Exemplo de Requisição (POST)

curl --location 'https://requests.prod.judit.io/requests/' \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '{
    "search": {
        "search_type": "cpf",
        "search_key": "999.999.999-99",
        "on_demand": true,
        "search_params": {
            "filter": {
                "side": "Passive",
                "tribunals": {
                    "keys": ["TJBA"],
                    "not_equal": false
                }
            }
        }
    }
}'
Guarde o request_id (ex: 05ee9825...) gerado na resposta desta chamada. Ele é o seu passaporte para os próximos passos.
🚀 Atalho: Automatize com Webhooks (Recomendado)Se você possui uma URL de Webhook configurada, os Passos 2 e 3 abaixo são totalmente opcionais. Em vez de programar sua aplicação para ficar perguntando o status da requisição, a Judit API enviará os processos encontrados de forma incremental diretamente para o seu servidor assim que eles forem capturados, finalizando o fluxo com um evento de request_completed.👉 Aprenda a configurar e receber Webhooks aqui

Passo 2: Consultar o Status da Requisição

Como um documento pode estar atrelado a centenas de processos no Brasil, a coleta leva tempo. Você deve consultar o status macro da requisição usando o ID do Passo 1. GET https://requests.prod.judit.io/requests/<REQUEST_ID>
cURL (Passo 2)
curl --location 'https://requests.prod.judit.io/requests/<request_id>' \
--header 'api-key: <api-key>' \
--header 'Content-Type: application/json' \
--data ''
Você deve realizar polling (consultas periódicas) nesta rota até que a propriedade "status" mude de "pending" para "completed". (Nota: O uso de Webhooks elimina a necessidade deste passo).

Verificação Granular (Apenas para On-Demand)

Como a busca On-Demand consulta dezenas de sistemas simultaneamente, você pode acompanhar o status individual de cada tribunal acessado usando a rota de Crawls:
cURL
curl --location 'https://crawler.prod.judit.io/crawls/request/<request_id>?page=1&page_size=10' \
    --header 'api-key: <api-key>'
{
    "page": 1,
    "page_data": [
        {
            "source_name": "JPje - RO - Lawsuit - Auth - 2 instance",
            "tribunal_acronym": "TJRO",
            "status": "done",
            "updated_at": "2025-10-28T00:04:40.651Z"
        },
        {
            "source_name": "JTJRJ - RJ - Lawsuit - Auth - 1 instance",
            "tribunal_acronym": "TJRJ",
            "status": "pending",
            "updated_at": "2025-10-28T00:04:53.157Z"
        }
    ]
}

Passo 3: Consumir e Filtrar os Resultados (GET)

Assim que o status no Passo 2 retornar "completed", os dados estão prontos! É aqui, na rota GET /responses, que você puxa o JSON final. A grande sacada deste endpoint é que ele permite aplicar filtros dinâmicos via URL (Query Params), permitindo que você fatie, ordene e pagine a resposta final do jeito que quiser, sem precisar gerar uma nova requisição (POST). GET https://requests.prod.judit.io/responses/

Filtros Dinâmicos na URL (Query Params)

Estes são os parâmetros que você pode concatenar na sua requisição final:
Query ParamTipo / FormatoDescrição
request_idstring (UUID)Obrigatório. O ID gerado no Passo 1.
pageintegerNúmero da página atual para navegação (Padrão: 1).
page_sizeintegerQuantidade de resultados retornados por página. Máximo permitido: 1000 (Recomendado: 100).
response_typearray JSONTipo de resposta desejada. Ex: ["lawsuit"].
codearray JSONFiltra por números de processo específicos. Ex: ["0601708-42..."].
instancearray JSONFiltra pelos graus de jurisdição. Ex: [1, 2].
cachedbooleanRetorna apenas processos cacheados (true) ou de captura nova (false).
classifications_codearray JSONCódigos de classe processual exatos (Ex: ["437"]).
subjects_codearray JSONCódigos de assunto do CNJ exatos (Ex: ["6226"]).
created_at_gte / ltestring (Data)Filtra pela data em que o processo entrou na base da Judit.
orderobjeto JSONOrdena a listagem. Ex: {"created_at": "desc"}.
tags.criminalbooleanRetorna true apenas para processos da esfera criminal.
# Retorna os processos usando apenas o parâmetro obrigatório
curl -X GET "[https://requests.prod.judit.io/responses?request_id=](https://requests.prod.judit.io/responses?request_id=)<SEU_REQUEST_ID>" \
  -H "api-key: SUA_API_KEY" \
  -H "Content-Type: application/json"

O formato da Resposta

O retorno traz as chaves de paginação e o array page_data, onde cada objeto contém a response_data (A Capa do Processo).
request_status
string
Status final da resposta (Deve ser completed).
page
integer
Página atual da busca.
page_count
integer
Total de processos renderizados nesta página.
all_count
integer
Total absoluto de processos encontrados e vinculados ao documento.
all_pages_count
integer
Quantidade total de páginas disponíveis.
page_data
array
Array de objetos. Cada objeto contém a chave response_data que abriga a Capa do Processo.
{
  "page": 1,
  "page_count": 1,
  "all_count": 1,
  "all_pages_count": 1,
  "request_status": "completed",
  "page_data": [
      {
          "request_id": "05ee9825-b2b4-480b-b29e-f071ca7d9c72",
          "response_id": "e49d2e2c-92ed-4dad-8701-c53a569d675b",
          "response_type": "lawsuit",
          "response_data": {
              "code": "0000000-00.0000.0.00.0000",
              "instance": 1,
              "justice": "8",
              "tribunal": "19",
              "tribunal_acronym": "TJRJ",
              "classifications": [
                  { "code": "436", "name": "PROCEDIMENTO DO JUIZADO ESPECIAL CÍVEL" }
              ],
              "subjects": [
                  { "code": "6226", "name": "INCLUSÃO INDEVIDA EM CADASTRO DE INADIMPLENTES" }
              ],
              "amount": 28790,
              "parties": [
                  {
                      "name": "NOME DO CLIENTE",
                      "side": "Active",
                      "person_type": "Autor",
                      "document": "99999999999",
                      "document_type": "CPF"
                  }
              ]
          }
      }
  ]
}
Processo não encontrado: Se o documento não possuir processos vinculados ou se os filtros forem muito restritivos, o all_count será 0 e o array page_data retornará vazio [].