> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Consulta Histórica por Documento (CPF/CNPJ/OAB/Nome)

> Recupere todo o histórico de processos vinculado a um CPF, CNPJ, OAB ou Nome via fluxo assíncrono da Judit API, com filtros avançados, paginação e suporte a CNPJ alfanumérico.

export const EndpointBadges = ({auth = true, billing = "billable", flow = "sync", attachments = false, requiresVault = false}) => <div style={{
  marginTop: "-8px",
  marginBottom: "16px"
}}>
    {auth && <Badge color="gray">🔒 Requer api-key</Badge>}
    {billing === "billable" && <Badge color="yellow">💰 Cobrança por requisição</Badge>}
    {billing === "free" && <Badge color="green">✅ Grátis</Badge>}
    {billing === "on-demand" && <Badge color="purple">⚡ On-demand (preço diferenciado)</Badge>}
    {flow === "async" && <Badge color="blue">⏳ Assíncrono · webhook ou polling</Badge>}
    {flow === "sync" && <Badge color="green">⚡ Síncrono</Badge>}
    {attachments && <Badge color="purple">📎 Suporta with_attachments</Badge>}
    {requiresVault && <Badge color="red">🔑 Cofre de Credenciais</Badge>}
  </div>;

export const DocumentAnimation = () => <iframe sandbox="allow-scripts" scrolling="no" style={{
  width: '100%',
  height: '600px',
  border: 'none',
  borderRadius: '12px',
  display: 'block',
  margin: '20px 0'
}} srcDoc={`<!doctype html><html><head><meta charset="utf-8"><style>*{margin:0;padding:0;box-sizing:border-box}html,body{width:100%;height:100%;overflow:hidden;background:#090c0d}canvas{display:block;width:100%;height:100%}</style></head><body><canvas id="c"></canvas><script>(function(){
var A='#4FD1C5',J='#1FC16B',T='#E0A82E',D='#8B5CF6',FE='#60A5FA',AM='#F6AD55',RE='#ef4444',M='#7A8599';
var BG='#090c0d',TXT='#e5e7eb',NF='#111827',PT='#0a1020';
var TOTAL=30.0;
var XP={app:0.06,judit:0.25,dl:0.46,ext:0.68,court:0.88};
var NW=80,NH=42;
var FLOWS=[
  {id:'dl',title:'① Assíncrono — Datalake + Fontes Externas',sub:'Datalake + fontes externas indexadas — sem acesso direto aos tribunais',col:D,ts:1,te:11,act:['app','judit','dl','ext'],steps:[
    {fr:'app',to:'judit',label:'POST /requests',note:'{search_type, search_key}',col:A,ts:1.2,te:2.0,yp:0.28},
    {fr:'judit',to:'app',label:'200 {request_id}',note:'status: pending',col:AM,ts:2.5,te:3.3,yp:0.37},
    {fr:'judit',to:'dl',label:'busca datalake',note:'histórico indexado',col:D,ts:3.8,te:4.6,yp:0.47},
    {fr:'judit',to:'ext',label:'busca fontes ext.',note:'bases externas',col:FE,ts:3.8,te:4.6,yp:0.57},
    {fr:'dl',to:'judit',label:'capa + partes',note:'histórico datalake',col:D,ts:5.2,te:6.0,yp:0.67},
    {fr:'ext',to:'judit',label:'dados externos',note:'enriquecimento',col:FE,ts:5.2,te:6.0,yp:0.77},
    {fr:'judit',to:'app',label:'webhook / polling',note:'response_data consolidado',col:J,ts:6.5,te:7.3,yp:0.87}]},
  {id:'od',title:'② On-Demand — Máxima Completude',sub:'Datalake + fontes externas + tribunais em tempo real',col:T,ts:14,te:28,act:['app','judit','dl','ext','court'],steps:[
    {fr:'app',to:'judit',label:'POST /requests',note:'{on_demand: true}',col:A,ts:14.2,te:15.0,yp:0.28},
    {fr:'judit',to:'app',label:'200 {request_id}',note:'status: pending',col:AM,ts:15.5,te:16.3,yp:0.36},
    {fr:'judit',to:'dl',label:'busca datalake',note:'histórico indexado',col:D,ts:16.8,te:17.6,yp:0.44},
    {fr:'judit',to:'ext',label:'busca fontes ext.',note:'bases externas',col:FE,ts:16.8,te:17.6,yp:0.52},
    {fr:'dl',to:'judit',label:'capa + partes',note:'histórico datalake',col:D,ts:18.2,te:19.0,yp:0.60},
    {fr:'ext',to:'judit',label:'dados externos',note:'enriquecimento',col:FE,ts:18.2,te:19.0,yp:0.68},
    {fr:'judit',to:'court',label:'extração tribunal',note:'dados em tempo real',col:T,ts:19.6,te:20.4,yp:0.76},
    {fr:'court',to:'judit',label:'dados do tribunal',note:'maior completude',col:J,ts:20.9,te:21.7,yp:0.84},
    {fr:'judit',to:'app',label:'webhook / polling',note:'response_data consolidado',col:J,ts:22.2,te:23.0,yp:0.92}]}
];
var NODES=[
  {id:'app',label:'Sua App',col:A},
  {id:'judit',label:'Judit API',col:J},
  {id:'dl',label:'Datalake',col:D},
  {id:'ext',label:'Fontes Ext.',col:FE},
  {id:'court',label:'Tribunais',col:T}
];
var cv=document.getElementById('c');
function setup(){var dpr=Math.min(window.devicePixelRatio||1,2),r=cv.getBoundingClientRect(),W=r.width||window.innerWidth,H=r.height||window.innerHeight;cv.width=Math.max(1,W*dpr);cv.height=Math.max(1,H*dpr);var ctx=cv.getContext('2d');ctx.setTransform(dpr,0,0,dpr,0,0);return{ctx:ctx,w:W,h:H};}
function ease(t){return t<0.5?2*t*t:1-Math.pow(-2*t+2,2)/2;}
function rr(ctx,x,y,w,h,r){ctx.beginPath();ctx.moveTo(x+r,y);ctx.arcTo(x+w,y,x+w,y+h,r);ctx.arcTo(x+w,y+h,x,y+h,r);ctx.arcTo(x,y+h,x,y,r);ctx.arcTo(x,y,x+w,y,r);ctx.closePath();}
function gx(n,w){return n==='app'?w*XP.app:n==='judit'?w*XP.judit:n==='dl'?w*XP.dl:n==='ext'?w*XP.ext:w*XP.court;}
function eg(fr,to,w){var fx=gx(fr,w),tx=gx(to,w),d=tx>fx?1:-1;return{x1:fx+d*NW/2,x2:tx-d*NW/2,d:d};}
function dPkt(ctx,x,y,lbl,col){var pw=Math.max(36,lbl.length*6+14),ph=20;ctx.save();ctx.shadowColor=col;ctx.shadowBlur=18;rr(ctx,x-pw/2,y-ph/2,pw,ph,5);ctx.fillStyle=col;ctx.fill();ctx.shadowBlur=0;ctx.fillStyle=PT;ctx.font='bold 9px monospace';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(lbl,x,y+0.5);ctx.restore();}
function draw(ctx,w,h,t){
  var ct=t%TOTAL;
  ctx.fillStyle=BG;ctx.fillRect(0,0,w,h);
  var fl=null;for(var i=0;i<FLOWS.length;i++){if(ct>=FLOWS[i].ts&&ct<FLOWS[i].te){fl=FLOWS[i];break;}}
  var nodeY=h*0.17;
  for(var i=0;i<NODES.length;i++){var n=NODES[i],lx=gx(n.id,w),ia=!fl||(fl.act.indexOf(n.id)>=0);ctx.save();ctx.strokeStyle=n.col;ctx.globalAlpha=ia?0.38:0.08;ctx.lineWidth=1;ctx.setLineDash([4,7]);ctx.beginPath();ctx.moveTo(lx,nodeY+NH/2);ctx.lineTo(lx,h*0.93);ctx.stroke();ctx.restore();}
  if(fl){ctx.save();ctx.fillStyle=fl.col;ctx.font='bold 13px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(fl.title,w/2,h*0.055);ctx.fillStyle=M;ctx.font='10.5px Inter,system-ui,sans-serif';ctx.fillText(fl.sub,w/2,h*0.118);ctx.restore();}
  if(fl){for(var si=0;si<fl.steps.length;si++){var s=fl.steps[si],sy=h*s.yp,e=eg(s.fr,s.to,w),x1=e.x1,x2=e.x2,d=e.d,clx=(x1+x2)/2;var state=ct<s.ts?'pre':ct>s.te?'done':'live',alpha=state==='pre'?0.10:state==='done'?0.55:1.0;ctx.save();ctx.globalAlpha=alpha;ctx.strokeStyle=s.col;ctx.lineWidth=1.5;ctx.setLineDash([]);ctx.beginPath();ctx.moveTo(x1,sy);ctx.lineTo(x2,sy);ctx.stroke();ctx.fillStyle=s.col;ctx.beginPath();ctx.moveTo(x2,sy);ctx.lineTo(x2-d*7,sy-4);ctx.lineTo(x2-d*7,sy+4);ctx.closePath();ctx.fill();ctx.fillStyle=TXT;ctx.font='bold 10px monospace';ctx.textAlign='center';ctx.textBaseline='bottom';ctx.fillText(s.label,clx,sy-4);if(s.note){ctx.fillStyle=M;ctx.font='9px monospace';ctx.fillText(s.note,clx,sy-16);}ctx.restore();if(state==='live'){var p=ease((ct-s.ts)/(s.te-s.ts));dPkt(ctx,x1+(x2-x1)*p,sy+14,s.label,s.col);}}}
  for(var i=0;i<NODES.length;i++){var nd=NODES[i],px=gx(nd.id,w),ia=!fl||(fl.act.indexOf(nd.id)>=0),isCx=fl&&(fl.id==='dl'&&nd.id==='court');ctx.save();ctx.globalAlpha=ia?1:0.18;if(ia){ctx.shadowColor=nd.col;ctx.shadowBlur=15;}rr(ctx,px-NW/2,nodeY-NH/2,NW,NH,8);ctx.fillStyle=NF;ctx.fill();ctx.shadowBlur=0;ctx.strokeStyle=isCx?RE:ia?nd.col:'rgba(255,255,255,0.10)';ctx.lineWidth=ia?1.8:1;ctx.stroke();ctx.fillStyle=isCx?RE:ia?nd.col:M;ctx.font='bold 11px Inter,system-ui,sans-serif';ctx.textAlign='center';ctx.textBaseline='middle';ctx.fillText(nd.label,px,nodeY);ctx.restore();if(isCx){ctx.save();ctx.strokeStyle=RE;ctx.lineWidth=2;ctx.globalAlpha=0.85;var bx=px+NW/2-12,by=nodeY-NH/2+10,br=8;ctx.beginPath();ctx.moveTo(bx-br,by-br);ctx.lineTo(bx+br,by+br);ctx.stroke();ctx.beginPath();ctx.moveTo(bx+br,by-br);ctx.lineTo(bx-br,by+br);ctx.stroke();ctx.restore();}}
  for(var f=0;f<FLOWS.length;f++){var ia=fl&&fl.id===FLOWS[f].id;ctx.save();ctx.beginPath();ctx.arc(w/2+(f-0.5)*24,h*0.962,ia?5:3,0,Math.PI*2);ctx.fillStyle=ia?FLOWS[f].col:'rgba(255,255,255,0.18)';ctx.fill();ctx.restore();}
}
var dim,t0;
function loop(){var t=(performance.now()-t0)/1000;draw(dim.ctx,dim.w,dim.h,t);requestAnimationFrame(loop);}
window.addEventListener('load',function(){dim=setup();t0=performance.now();loop();});
window.addEventListener('resize',function(){dim=setup();});
cv.addEventListener('click',function(e){var r=cv.getBoundingClientRect(),cx=e.clientX-r.left,cy=e.clientY-r.top;for(var f=0;f<FLOWS.length;f++){var dx=cx-(dim.w/2+(f-(FLOWS.length-1)/2)*24),dy=cy-dim.h*0.962;if(dx*dx+dy*dy<=144){t0=performance.now()-FLOWS[f].ts*1000;break;}}});
cv.addEventListener('mousemove',function(e){var r=cv.getBoundingClientRect(),cx=e.clientX-r.left,cy=e.clientY-r.top,over=false;for(var f=0;f<FLOWS.length;f++){var dx=cx-(dim.w/2+(f-(FLOWS.length-1)/2)*24),dy=cy-dim.h*0.962;if(dx*dx+dy*dy<=144){over=true;break;}}cv.style.cursor=over?'pointer':'default';});
})()\x3c/script></body></html>`} />;

<Info>
  **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](https://normasinternet2.receita.fazenda.gov.br/#/consulta/externa/141102).

  * **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.
</Info>

<Info>
  **Resposta em cache (`cached_response`)**

  Quando você cria uma consulta processual ou histórica, a Judit primeiro verifica se o dado já está em nossa base. Se estiver, devolvemos imediatamente o resultado — tanto na resposta da API quanto via webhook (se você tiver cadastrado) — com o campo `cached_response: true`.

  Em paralelo, a Judit dispara uma atualização nos tribunais. Se houver alguma mudança, você recebe **uma segunda resposta** com `cached_response: false`. Esse é o resultado mais atual.

  Por isso, é normal receber dois webhooks aparentemente iguais para o mesmo `request_id`:

  * O primeiro vem do cache (`cached_response: true`)
  * O último é o atualizado (`cached_response: false`)

  Use esse campo para identificar com precisão qual retorno representa o estado mais recente do processo.
</Info>

A **Consulta Histórica por Documento** retorna **toda a carteira processual** vinculada a um CPF, CNPJ, OAB ou Nome. É o caminho ideal para due diligence, KYC, mapeamento de exposição judicial e qualquer cenário em que você precise saber *quais processos existem* (capa + partes), sem necessariamente entrar em cada um.

> 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.

<EndpointBadges auth billing="billable" flow="async" requiresVault />

## Quando usar

<CardGroup cols={2}>
  <Card title="Due diligence / KYC" icon="user-shield">
    Antes de fechar contrato, descubra todo o passivo judicial da contraparte por CPF/CNPJ.
  </Card>

  <Card title="Crédito e cobrança" icon="dollar-sign">
    Combine com filtros (`amount_gte`, `side: "Passive"`) para priorizar abordagens com base no valor de causa.
  </Card>

  <Card title="Vigilância de carteira" icon="briefcase">
    Cruze com [Monitoramento por documento](/tracking/tracking-document) para detectar **novos processos** após a consulta inicial.
  </Card>

  <Card title="Inteligência por OAB" icon="user-tie">
    Consulte por OAB para listar todos os processos em que um advogado atua.
  </Card>
</CardGroup>

## 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](/cache-judit/hotstorage).*
* **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).

***

<DocumentAnimation />

## 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.production.judit.io/requests`

### Exemplos de consultas históricas

<CodeGroup>
  ```json Consulta por CPF theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99"
      }
  }
  ```

  ```json Consulta por CNPJ theme={null}
  {
      "search": {
          "search_type": "cnpj",
          "search_key": "99.999.999/9999-99"
      }
  }
  ```

  ```json Consulta por OAB theme={null}
  {
      "search": {
          "search_type": "oab",
          "search_key": "99999RJ"
      }
  }
  ```

  ```json Consulta por Nome theme={null}
  {
      "search": {
          "search_type": "name",
          "search_key": "João Silva"
      }
  }
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

### Parâmetros Base do Payload

| Parâmetro            | Tipo    | Obrigatório | Descrição                                                                                                                                                          |
| :------------------- | :------ | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search.search_type` | string  | **Sim**     | tipo de entidade que será 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.on_demand`   | boolean | Não         | Se `true`, força a busca em tempo real nos tribunais em vez do Datalake.                                                                                           |
| `cache_ttl_in_days`  | integer | Não         | Considera o cache válido se a última extração ocorreu nos últimos X dias.                                                                                          |
| `customer_key`       | string  | Não         | Chave do usuário no Cofre de Credenciais (usado para acessar os tribunais com credenciais cadastrada no [cofre de credenciais](/essentials/cofre-de-credenciais)). |

<Note>
  **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.
</Note>

<CodeGroup>
  ```json request assíncrona theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "cache_ttl_in_days": 7
      }
  }
  ```

  ```json request on-demand theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true
      }
  }
  ```

  ```json request on-demand com customer_key theme={null}
  {
      "search": {
          "search_type": "cpf",
          "search_key": "999.999.999-99",
          "on_demand": true,
          "customer_key: "ADV01"
      }
  }
  ```
</CodeGroup>

### 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*).

<CodeGroup>
  ```json theme={null}
  // 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
              }
          }
      }
  }

  ```
</CodeGroup>

#### 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`).

<AccordionGroup>
  <Accordion title="Tribunais Superiores e Conselhos">
    | Sigla (Key) | Nome Oficial do Órgão                    |
    | :---------- | :--------------------------------------- |
    | `STF`       | SUPREMO TRIBUNAL FEDERAL                 |
    | `STJ`       | SUPERIOR TRIBUNAL DE JUSTIÇA             |
    | `TST`       | TRIBUNAL SUPERIOR DO TRABALHO            |
    | `TSE`       | TRIBUNAL SUPERIOR ELEITORAL              |
    | `STM`       | SUPERIOR TRIBUNAL MILITAR                |
    | `CNJ`       | CONSELHO NACIONAL DE JUSTIÇA             |
    | `CJF`       | CONSELHO DA JUSTIÇA FEDERAL              |
    | `CSJT`      | CONSELHO SUPERIOR DA JUSTIÇA DO TRABALHO |
  </Accordion>

  <Accordion title="Justiça Federal (TRF)">
    | Sigla (Key) | Nome Oficial do Órgão                  |
    | :---------- | :------------------------------------- |
    | `TRF1`      | TRIBUNAL REGIONAL FEDERAL DA 1ª REGIÃO |
    | `TRF2`      | TRIBUNAL REGIONAL FEDERAL DA 2ª REGIÃO |
    | `TRF3`      | TRIBUNAL REGIONAL FEDERAL DA 3ª REGIÃO |
    | `TRF4`      | TRIBUNAL REGIONAL FEDERAL DA 4ª REGIÃO |
    | `TRF5`      | TRIBUNAL REGIONAL FEDERAL DA 5ª REGIÃO |
  </Accordion>

  <Accordion title="Justiça do Trabalho (TRT)">
    | Sigla (Key) | Nome Oficial do Órgão             |
    | :---------- | :-------------------------------- |
    | `TRT1`      | TRT DA 1ª REGIÃO (RJ)             |
    | `TRT2`      | TRT DA 2ª REGIÃO (SP - Capital)   |
    | `TRT3`      | TRT DA 3ª REGIÃO (MG)             |
    | `TRT4`      | TRT DA 4ª REGIÃO (RS)             |
    | `TRT5`      | TRT DA 5ª REGIÃO (BA)             |
    | `TRT6`      | TRT DA 6ª REGIÃO (PE)             |
    | `TRT7`      | TRT DA 7ª REGIÃO (CE)             |
    | `TRT8`      | TRT DA 8ª REGIÃO (PA/AP)          |
    | `TRT9`      | TRT DA 9ª REGIÃO (PR)             |
    | `TRT10`     | TRT DA 10ª REGIÃO (DF/TO)         |
    | `TRT11`     | TRT DA 11ª REGIÃO (AM/RR)         |
    | `TRT12`     | TRT DA 12ª REGIÃO (SC)            |
    | `TRT13`     | TRT DA 13ª REGIÃO (PB)            |
    | `TRT14`     | TRT DA 14ª REGIÃO (RO/AC)         |
    | `TRT15`     | TRT DA 15ª REGIÃO (SP - Campinas) |
    | `TRT16`     | TRT DA 16ª REGIÃO (MA)            |
    | `TRT17`     | TRT DA 17ª REGIÃO (ES)            |
    | `TRT18`     | TRT DA 18ª REGIÃO (GO)            |
    | `TRT19`     | TRT DA 19ª REGIÃO (AL)            |
    | `TRT20`     | TRT DA 20ª REGIÃO (SE)            |
    | `TRT21`     | TRT DA 21ª REGIÃO (RN)            |
    | `TRT22`     | TRT DA 22ª REGIÃO (PI)            |
    | `TRT23`     | TRT DA 23ª REGIÃO (MT)            |
    | `TRT24`     | TRT DA 24ª REGIÃO (MS)            |
  </Accordion>

  <Accordion title="Justiça Estadual (TJ)">
    | Sigla (Key) | Nome Oficial do Órgão                                 |
    | :---------- | :---------------------------------------------------- |
    | `TJAC`      | TRIBUNAL DE JUSTIÇA DO ACRE                           |
    | `TJAL`      | TRIBUNAL DE JUSTIÇA DO ALAGOAS                        |
    | `TJAP`      | TRIBUNAL DE JUSTIÇA DO AMAPÁ                          |
    | `TJAM`      | TRIBUNAL DE JUSTIÇA DO AMAZONAS                       |
    | `TJBA`      | TRIBUNAL DE JUSTIÇA DA BAHIA                          |
    | `TJCE`      | TRIBUNAL DE JUSTIÇA DO CEARÁ                          |
    | `TJDF`      | TRIBUNAL DE JUSTIÇA DO DISTRITO FEDERAL E TERRITÓRIOS |
    | `TJES`      | TRIBUNAL DE JUSTIÇA DO ESPÍRITO SANTO                 |
    | `TJGO`      | TRIBUNAL DE JUSTIÇA DE GOIÁS                          |
    | `TJMA`      | TRIBUNAL DE JUSTIÇA DO MARANHÃO                       |
    | `TJMT`      | TRIBUNAL DE JUSTIÇA DO MATO GROSSO                    |
    | `TJMS`      | TRIBUNAL DE JUSTIÇA DO MATO GROSSO DO SUL             |
    | `TJMG`      | TRIBUNAL DE JUSTIÇA DE MINAS GERAIS                   |
    | `TJPA`      | TRIBUNAL DE JUSTIÇA DO PARÁ                           |
    | `TJPB`      | TRIBUNAL DE JUSTIÇA DA PARAÍBA                        |
    | `TJPR`      | TRIBUNAL DE JUSTIÇA DO PARANÁ                         |
    | `TJPE`      | TRIBUNAL DE JUSTIÇA DE PERNAMBUCO                     |
    | `TJPI`      | TRIBUNAL DE JUSTIÇA DO PIAUÍ                          |
    | `TJRJ`      | TRIBUNAL DE JUSTIÇA DO RIO DE JANEIRO                 |
    | `TJSP`      | TRIBUNAL DE JUSTIÇA DE SÃO PAULO                      |
    | `TJRN`      | TRIBUNAL DE JUSTIÇA DO RIO GRANDE DO NORTE            |
    | `TJRS`      | TRIBUNAL DE JUSTIÇA DO RIO GRANDE DO SUL              |
    | `TJRO`      | TRIBUNAL DE JUSTIÇA DE RONDÔNIA                       |
    | `TJRR`      | TRIBUNAL DE JUSTIÇA DE RORAIMA                        |
    | `TJSC`      | TRIBUNAL DE JUSTIÇA DE SANTA CATARINA                 |
    | `TJSE`      | TRIBUNAL DE JUSTIÇA DE SERGIPE                        |
  </Accordion>

  <Accordion title="Justiça Eleitoral (TRE)">
    | Sigla (Key) | Nome Oficial do Órgão                              |
    | :---------- | :------------------------------------------------- |
    | `TRE-AC`    | TRIBUNAL REGIONAL ELEITORAL DO ACRE                |
    | `TRE-AL`    | TRIBUNAL REGIONAL ELEITORAL DO ALAGOAS             |
    | `TRE-AP`    | TRIBUNAL REGIONAL ELEITORAL DO AMAPÁ               |
    | `TRE-AM`    | TRIBUNAL REGIONAL ELEITORAL DO AMAZONAS            |
    | `TRE-BA`    | TRIBUNAL REGIONAL ELEITORAL DA BAHIA               |
    | `TRE-CE`    | TRIBUNAL REGIONAL ELEITORAL DO CEARÁ               |
    | `TRE-DF`    | TRIBUNAL REGIONAL ELEITORAL DO DISTRITO FEDERAL    |
    | `TRE-ES`    | TRIBUNAL REGIONAL ELEITORAL DO ESPÍRITO SANTO      |
    | `TRE-GO`    | TRIBUNAL REGIONAL ELEITORAL DE GOIÁS               |
    | `TRE-MA`    | TRIBUNAL REGIONAL ELEITORAL DO MARANHÃO            |
    | `TRE-MT`    | TRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO         |
    | `TRE-MS`    | TRIBUNAL REGIONAL ELEITORAL DO MATO GROSSO DO SUL  |
    | `TRE-MG`    | TRIBUNAL REGIONAL ELEITORAL DE MINAS GERAIS        |
    | `TRE-PA`    | TRIBUNAL REGIONAL ELEITORAL DO PARÁ                |
    | `TRE-PB`    | TRIBUNAL REGIONAL ELEITORAL DA PARAÍBA             |
    | `TRE-PR`    | TRIBUNAL REGIONAL ELEITORAL DO PARANÁ              |
    | `TRE-PE`    | TRIBUNAL REGIONAL ELEITORAL DE PERNAMBUCO          |
    | `TRE-PI`    | TRIBUNAL REGIONAL ELEITORAL DO PIAUÍ               |
    | `TRE-RJ`    | TRIBUNAL REGIONAL ELEITORAL DO RIO DE JANEIRO      |
    | `TRE-RN`    | TRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO NORTE |
    | `TRE-RS`    | TRIBUNAL REGIONAL ELEITORAL DO RIO GRANDE DO SUL   |
    | `TRE-RO`    | TRIBUNAL REGIONAL ELEITORAL DE RONDÔNIA            |
    | `TRE-RR`    | TRIBUNAL REGIONAL ELEITORAL DE RORAIMA             |
    | `TRE-SC`    | TRIBUNAL REGIONAL ELEITORAL DE SANTA CATARINA      |
    | `TRE-SE`    | TRIBUNAL REGIONAL ELEITORAL DE SERGIPE             |
    | `TRE-SP`    | TRIBUNAL REGIONAL ELEITORAL DE SÃO PAULO           |
    | `TRE-TO`    | TRIBUNAL REGIONAL ELEITORAL DO TOCANTINS           |
  </Accordion>

  <Accordion title="Justiça Militar (União e Estadual)">
    | Sigla (Key) | Nome Oficial do Órgão                                      |
    | :---------- | :--------------------------------------------------------- |
    | `CJM1`      | PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                  |
    | `CJM2`      | SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                   |
    | `CJM3`      | TERCEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                  |
    | `CJM4`      | QUARTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM5`      | QUINTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM6`      | SEXTA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                     |
    | `CJM7`      | SÉTIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM8`      | OITAVA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM9`      | NONA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                      |
    | `CJM10`     | DÉCIMA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR                    |
    | `CJM11`     | DÉCIMA PRIMEIRA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR           |
    | `CJM12`     | DÉCIMA SEGUNDA CIRCUNSCRIÇÃO JUDICIÁRIA MILITAR            |
    | `TJM-MG`    | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE MINAS GERAIS      |
    | `TJM-RS`    | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DO RIO GRANDE DO SUL |
    | `TJM-SP`    | TRIBUNAL DE JUSTIÇA MILITAR DO ESTADO DE SÃO PAULO         |
  </Accordion>
</AccordionGroup>

* **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.

<Accordion title="Exemplo JSON: Inclusão vs. Exclusão de Tribunais" defaultOpen>
  <CodeGroup>
    ```json Buscar APENAS nestes theme={null}
    // 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
                    }
                }
            }
        }
    }

    ```

    ```json Buscar em TODOS, MENOS nestes theme={null}
    // Traz do Brasil inteiro, mas ignora a Justiça Federal (TRFs)
    {
        "search": {
            "search_type": "cpf",
            "search_key": "999.999.999-99",
            "search_params": {
                "filter": {
                    "tribunals": {
                        "keys": [
                            "TRF1",
                            "TRF2",
                            "TRF3",
                            "TRF4",
                            "TRF5",
                            "TRF6"
                        ],
                        "not_equal": true
                    }
                }
            }
        }
    }

    ```
  </CodeGroup>
</Accordion>

#### 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](https://www.cnj.jus.br/sgt/consulta_publica_classes.php).*

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).

<Accordion title="Exemplo JSON: Filtrando por Assuntos e Classes">
  ```json theme={null}
  {
      "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
                  }
              }
          }
      }
  }
  ```
</Accordion>

#### 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.

<Accordion title="Exemplo JSON: Filtrando por Datas">
  ```json theme={null}
  {
      "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"
              }
          }
      }
  }
  ```
</Accordion>

#### 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.

<Info>
  **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.
</Info>

<Accordion title="Exemplo JSON: Partes Específicas">
  ```json theme={null}
  {
      "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"
                  ]
              }
          }
      }
  }
  ```
</Accordion>

### Exemplo de Requisição (POST)

<CodeGroup>
  ```bash cURL (Passo 1) theme={null}
  curl --location 'https://requests.production.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
                  }
              }
          }
      }
  }'
  ```
</CodeGroup>

Guarde o `request_id` (ex: `05ee9825...`) gerado na resposta desta chamada. Ele é o seu passaporte para os próximos passos.

***

<Info>
  **🚀 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](/webhook/callbacks)*
</Info>

***

## 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.production.judit.io/requests/<REQUEST_ID>`

```bash cURL (Passo 2) theme={null}
curl --location 'https://requests.production.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*:

```bash cURL theme={null}
curl --location 'https://crawler.production.judit.io/crawls/request/<request_id>?page=1&page_size=10' \
    --header 'api-key: <api-key>'
```

<Accordion title="Ver exemplo de Resposta de Status On-Demand">
  ```json theme={null}
  {
      "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"
          }
      ]
  }
  ```
</Accordion>

***

## 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.production.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 Param              | Tipo / Formato | Descrição                                                                                        |
| :----------------------- | :------------- | :----------------------------------------------------------------------------------------------- |
| `request_id`             | string (UUID)  | **Obrigatório.** O ID gerado no Passo 1.                                                         |
| `page`                   | integer        | Número da página atual para navegação (Padrão: `1`).                                             |
| `page_size`              | integer        | Quantidade de resultados retornados por página. **Máximo permitido: 1000** (Recomendado: `100`). |
| `response_type`          | array JSON     | Tipo de resposta desejada. Ex: `["lawsuit"]`.                                                    |
| `code`                   | array JSON     | Filtra por números de processo específicos. Ex: `["0601708-42..."]`.                             |
| `instance`               | array JSON     | Filtra pelos graus de jurisdição. Ex: `[1, 2]`.                                                  |
| `cached`                 | boolean        | Retorna apenas processos cacheados (`true`) ou de captura nova (`false`).                        |
| `classifications_code`   | array JSON     | Códigos de classe processual exatos (Ex: `["437"]`).                                             |
| `subjects_code`          | array JSON     | Códigos de assunto do CNJ exatos (Ex: `["6226"]`).                                               |
| `created_at_gte` / `lte` | string (Data)  | Filtra pela data em que o processo entrou na base da Judit.                                      |
| `order`                  | objeto JSON    | Ordena a listagem. Ex: `{"created_at": "desc"}`.                                                 |
| `tags.criminal`          | boolean        | Retorna `true` apenas para processos da esfera criminal.                                         |

<CodeGroup>
  ```bash cURL (Busca Básica) theme={null}
  # Retorna os processos usando apenas o parâmetro obrigatório
  curl -X GET "[https://requests.production.judit.io/responses?request_id=](https://requests.production.judit.io/responses?request_id=)<SEU_REQUEST_ID>" \
    -H "api-key: SUA_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```bash cURL (Busca Avançada com Filtros) theme={null}
  # O parâmetro -g (--globoff) permite o uso de colchetes [] na URL sem quebrar o terminal.
  # Nota: Na sua aplicação, lembre-se de aplicar URL Encoding nesses parâmetros.

  curl -g -X GET "[https://requests.production.judit.io/responses](https://requests.production.judit.io/responses)\
  ?request_id=<SEU_REQUEST_ID>\
  &response_type=[\"lawsuit\"]\
  &code=[\"0601708-42.2025.8.04.4700\"]\
  &instance=[1,2]\
  &cached=false\
  &classifications_code=[\"437\"]\
  &classifications_name=[\"PROCEDIMENTO DO JUIZADO ESPECIAL CÍVEL\"]\
  &subjects_code=[\"6226\"]\
  &subjects_name=\"INCLUSÃO INDEVIDA EM CADASTRO DE INADIMPLENTES\"\
  &created_at_gte=2026-03-01T00:00:00.000Z\
  &created_at_lte=2026-03-05T00:00:00.000Z\
  &request_created_at_gte=2026-03-02T00:00:00.000Z\
  &request_created_at_lte=2026-03-05T00:00:00.000Z\
  &page=1\
  &page_size=1000\
  &order={\"created_at\":\"desc\"}\
  &tags.criminal=true" \
    -H "api-key: SUA_API_KEY" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

### 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).

<ParamField body="request_status" name="request_status" type="string">
  Status final da resposta (Deve ser `completed`).
</ParamField>

<ParamField body="page" name="page" type="integer">
  Página atual da busca.
</ParamField>

<ParamField body="page_count" name="page_count" type="integer">
  Total de processos renderizados nesta página.
</ParamField>

<ParamField body="all_count" name="all_count" type="integer">
  Total absoluto de processos encontrados e vinculados ao documento.
</ParamField>

<ParamField body="all_pages_count" name="all_pages_count" type="integer">
  Quantidade total de páginas disponíveis.
</ParamField>

<ParamField body="page_data" name="page_data" type="array">
  Array de objetos. Cada objeto contém a chave `response_data` que abriga a [Capa do Processo](/schemas/lawsuit-object).
</ParamField>

<Accordion title="Ver Exemplo da Estrutura do Processo Retornado">
  ```json theme={null}
  {
    "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",
          "tribunal_acronym": "TJSP",
          "instance": 1,
          "parties": [
            { "name": "Usuário teste", "side": "Active", "person_type": "Autor" }
          ]
        }
      }
    ]
  }
  ```
</Accordion>
