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

# Buscar por Número CNJ (Capa)

> Consulte a capa do processo e os metadados das movimentações relacionadas a um NPU — sem o texto integral dos anexos.

# 🔎 Buscar por Número CNJ (Capa)

Este endpoint permite consultar a **capa do processo** e os **metadados das movimentações** associadas a um Número de Processo Único (NPU).

> **Observação:** neste recurso **não é retornado** o campo `movimentos.descricao` (texto integral de anexos como sentença, acórdão, decisão).

Você pode aplicar filtros por grau, tribunal, classe, assunto, valor da causa, status, ramo do direito e mais.

***

## 🔗 Endpoint

```
POST https://api.predictus.com.br/predictus-api/processos/judiciais/capa/buscarPorNumeroCNJ
```

***

## 🧾 Exemplo mínimo

> `numeroProcessoUnico` é o único campo obrigatório. Todos os demais são filtros opcionais.

```json theme={null}
{
  "numeroProcessoUnico": "10004588220255020441"
}
```

***

## 🧾 Exemplo completo (com todos os filtros)

```json theme={null}
{
  "numeroProcessoUnico": "50091485920228240090",
  "grausProcesso": [1],
  "limiteResultados": 10000,
  "tribunais": ["TJ-SC", "TRT-9"],
  "valorCausa": {
    "maiorQue": 1000,
    "menorQue": 100000
  },
  "dataDistribuicao": {
    "maiorQue": "1970-01-01",
    "menorQue": "2025-12-31"
  },
  "classesProcessuais": [
    "CUMPRIMENTO DE SENTENCA",
    "PROCEDIMENTO DO JUIZADO ESPECIAL CIVEL",
    "ACAO TRABALHISTA - RITO ORDINARIO"
  ],
  "assuntosCNJ": [
    "INDENIZACAO POR DANO MORAL",
    "ATRASO DE VOO",
    "ADICIONAL DE HORAS EXTRAS"
  ],
  "statusProcessuais": [
    "EM TRAMITACAO",
    "ARQUIVAMENTO DEFINITIVO",
    "EM GRAU DE RECURSO"
  ],
  "ramosDoDireito": [
    "DIREITO DO TRABALHO",
    "DIREITO DO CONSUMIDOR",
    "DIREITO CIVIL"
  ],
  "segmentos": [
    "JUSTICA ESTADUAL",
    "JUSTICA DO TRABALHO"
  ],
  "camposRetorno": {
    "incluir": [
      "urlProcesso",
      "numeroProcessoUnico",
      "numeroProcessoAntigo",
      "statusObservacao",
      "grauProcesso",
      "juiz",
      "relator",
      "revisores",
      "area",
      "sistema",
      "segmento",
      "tribunalOrigem",
      "tribunal",
      "uf",
      "orgaoJulgador",
      "unidadeOrigem",
      "classeProcessual",
      "assuntosCNJ",
      "dataDistribuicao",
      "dataAutuacao",
      "partes",
      "advogadosSemParte",
      "processosRelacionados",
      "valorCausa",
      "valorExecucao",
      "eTutelaAntecipada",
      "temInjuncao",
      "eJusticaGratuita",
      "ePrioritario",
      "eSegredoJustica",
      "eProcessoDigital",
      "temAcordao",
      "movimentos",
      "acordao",
      "temSentenca",
      "sentenca",
      "dataProcessamento",
      "statusPredictus"
    ]
  }
}
```

> **Nota sobre `movimentos`:** este recurso retorna **metadados** padronizados dos movimentos (por exemplo, data, identificação, classe/tipo, vínculos com anexos quando aplicável). O campo `movimentos.descricao` **não é retornado**.

***

## 📚 Campos importantes

* `numeroProcessoUnico` (string) — **campo obrigatório**
  * Deve conter exatamente **20 dígitos numéricos**
  * Deve ser um NPU válido conforme **Resolução CNJ nº 65/2008**
* `grausProcesso` — lista de inteiros entre 1 e 4:
  * `1` → 1º Grau (ex.: vara cível)
  * `2` → 2º Grau (tribunais estaduais/regionais)
  * `3` → Tribunais Superiores (STJ, TST etc.)
  * `4` → Supremo Tribunal Federal (STF)
* `tribunais` — lista de siglas válidas (ex.: `TJ-SP`, `TRT-9`, `STF`)
  * Ver **lista completa de tribunais** na referência da API
* `valorCausa`, `dataDistribuicao` — permitem filtragem por faixa (`menorQue`/`menorIgualQue`/`maiorQue`/`maiorIgualQue`)
* `classesProcessuais`, `assuntosCNJ` — até **65.000** valores cada
* `statusProcessuais` — ver valores válidos na referência
* `ramosDoDireito` — ver valores válidos na referência
* `segmentos` — deve conter apenas valores válidos (ex.: `JUSTICA DO TRABALHO`, `STF`)
* `limiteResultados` — **mínimo 1** / **máximo 10.000** (padrão: **10.000**)

***

## 📌 Como funcionam os filtros

A API aplica os filtros com **lógica combinada (AND entre filtros diferentes, OR dentro de listas)**:

| Situação                          | Comportamento                                           |
| --------------------------------- | ------------------------------------------------------- |
| Vários filtros usados             | Todos devem ser satisfeitos (lógica **AND**)            |
| Lista de valores (ex.: tribunais) | Basta bater **um dos valores** da lista (lógica **OR**) |
| Campo único (NPU)                 | Precisa ser **exatamente igual**                        |
| Faixas (valor ou data)            | O valor do processo deve estar **dentro do intervalo**  |

***

## 🧾 Códigos de resposta

| Código | Significado                           |
| -----: | ------------------------------------- |
|  `200` | Sucesso — processos encontrados       |
|  `204` | Nenhum processo encontrado para o NPU |
|  `400` | Erro de validação no payload          |
|  `401` | Token inválido ou expirado            |

***

## 🛡️ Validações aplicadas

* **Número do Processo Único (NPU)**:
  * Não nulo
  * 20 dígitos numéricos
  * Validação formal conforme Res. CNJ nº 65/2008
* Listas de `statusProcessuais`, `ramosDoDireito`, `segmentos`, `tribunais`:
  * Todos os valores devem estar nas listas de permitidos
* Campos com listas extensas (`classesProcessuais`, `assuntosCNJ`):
  * Máximo de **65.000** itens
* `limiteResultados`: entre **1** e **10.000**

***

## 🧩 Retorno

Retorna uma lista de objetos do tipo [`processo`](../estrutura), com dados estruturados e padronizados pela Predictus — incluindo a **capa** e os **metadados de movimentações**.

> **Importante:** o campo `movimentos.descricao` (texto integral de anexos) **não é retornado** por este recurso.