Conceitos do Miner — kind, natures, tags e tiers - JUDIT

Beta público. O conjunto de filtros pode receber novas opções (especialmente tags para sentence-execution). Trate enums como abertos e ignore valores desconhecidos.

A busca no Miner é definida por um único objeto de filtro — o mesmo schema é usado em POST /requests/count (gratuito) e POST /requests/create (cobra créditos). Esta página explica cada campo, os valores possíveis e as combinações válidas.

`kind` (obrigatório)

Define que tipo de ativo você está garimpando. É o primeiro filtro a escolher porque condiciona quais outros campos podem aparecer.

Valor	O que é	Filtros adicionais permitidos
`judgement-bond`	Precatórios — créditos contra a Fazenda Pública decorrentes de sentenças transitadas em julgado.	`budget_years`, `natures`
`sentence-execution`	Execuções de sentença — fase de cumprimento, com possibilidade de aprovação de cálculo ou expedição de precatório.	`tags`

Você não pode misturar campos exclusivos: tags com kind: judgement-bond ou budget_years/natures com kind: sentence-execution falham com 400.

`natures` (apenas `judgement-bond`)

Tipo do crédito decorrente do precatório.

Valor	Significado
`alimentary`	Precatório de natureza alimentar — verbas salariais, pensões, indenizações por morte, benefícios previdenciários. Tem prioridade de pagamento.
`common`	Precatório comum — qualquer outro tipo de crédito (tributário, indenizatório civil, desapropriação, etc.).

{
  "kind": "judgement-bond",
  "natures": ["alimentary"]
}

Combine os dois para incluir tudo: "natures": ["alimentary", "common"].

`budget_years` (apenas `judgement-bond`)

Anos orçamentários nos quais o precatório foi inscrito. Use para filtrar safras específicas — geralmente o ano de inscrição é o ano civil seguinte ao da sentença transitada em julgado.

{
  "kind": "judgement-bond",
  "budget_years": [2023, 2024]
}

`tags` (apenas `sentence-execution`)

Sinais detectados pela base Judit que indicam estágio de maturação da execução.

Valor	O que indica
`precatory_dispatched`	Precatório já expedido na execução. O ativo está prestes a virar `judgement-bond`.
`possible_precatory`	Sinais textuais sugerindo que um precatório será expedido em breve (decisões, despachos, certidões).
`possible_approved_calculation`	Cálculo de liquidação aparentemente homologado — etapa que costuma anteceder o precatório.

{
  "kind": "sentence-execution",
  "tags": ["possible_precatory", "possible_approved_calculation"]
}

Múltiplas tags são tratadas como OR — qualquer processo que tenha pelo menos uma das tags entra no resultado.

Faixa de valor

Há duas formas mutuamente exclusivas de filtrar por valor:

Modo 1 — Limites livres (`amount_min` / `amount_max`)

{
  "kind": "judgement-bond",
  "amount_min": 50000,
  "amount_max": 500000
}

Campo	Tipo	Regra
`amount_min`	number	Valor mínimo, em reais (R$).
`amount_max`	number	Valor máximo, em reais. Deve ser ≥ `amount_min`.

Use quando você precisa de um corte específico (ex.: “entre R

50k e R

500k”).

Modo 2 — Faixa pré-definida (`amount_tier`)

{
  "kind": "sentence-execution",
  "amount_tier": "250k-500k"
}

Valor de `amount_tier`	Faixa em R$
`0-100k`	até R$ 100.000
`100k-250k`	R $100.000 a R$ 250.000
`250k-500k`	R $250.000 a R$ 500.000
`500k-750k`	R $500.000 a R$ 750.000
`750k-1.5M`	R $750.000 a R$ 1.500.000
`1.5M+`	acima de R$ 1.500.000

Use quando estiver alinhado às faixas comerciais da Judit — é o caminho recomendado porque a precificação por créditos também é por faixa.

Não combine os dois modos. Enviar amount_tier junto com amount_min ou amount_max falha com 400. Escolha um.

`tribunals`

Array de IDs numéricos dos tribunais a incluir. Vazio ou ausente = todos os tribunais cobertos pelo Miner.

{
  "kind": "judgement-bond",
  "tribunals": [10, 18, 1]
}

Para descobrir os IDs: chame GET /tribunals ou veja a tabela completa.

`responses_limit` (apenas `/requests/create`)

Teto opcional para o número de processos materializados em uma busca. Não tem efeito em /requests/count — o count sempre retorna o total real.

{
  "kind": "sentence-execution",
  "tribunals": [10],
  "tags": ["possible_precatory"],
  "responses_limit": 500
}

Cenário	Comportamento
`responses_limit` omitido	Materializa todos os processos que batem (até o limite do plano).
`responses_limit: N` (N ≤ total)	Materializa exatamente N processos, ordenados por critério interno. Custo proporcional.
`responses_limit: N` (N > total)	Materializa todos os disponíveis. Cobrança apenas pelo total real.

Use para controlar custo quando o count retornou um volume alto e você só quer uma amostra.

Regras de combinação

Resumo de tudo que falha com 400:

Tentativa	Por quê
`kind: judgement-bond` + `tags: [...]`	`tags` é exclusivo de `sentence-execution`.
`kind: sentence-execution` + `budget_years: [...]`	`budget_years` é exclusivo de `judgement-bond`.
`kind: sentence-execution` + `natures: [...]`	`natures` é exclusivo de `judgement-bond`.
`amount_min: 100000` + `amount_tier: "250k-500k"`	Modos de valor mutuamente exclusivos.
`amount_min: 100000, amount_max: 50000`	`min` deve ser ≤ `max`.
Qualquer chave fora do schema (ex.: `state: "SP"`)	`RequestLawsuitsFiltersBody` é strict — chaves desconhecidas são rejeitadas.

Schema completo (referência rápida)

{
  "kind": "judgement-bond" | "sentence-execution",                // obrigatório
  "tribunals": [10, 18],                                          // opcional
  "amount_min": 50000,                                            // opcional (não combina com amount_tier)
  "amount_max": 500000,                                           // opcional (não combina com amount_tier)
  "amount_tier": "250k-500k",                                     // opcional (não combina com min/max)
  "budget_years": [2023, 2024],                                   // só para judgement-bond
  "natures": ["alimentary", "common"],                            // só para judgement-bond
  "tags": ["possible_precatory"],                                 // só para sentence-execution
  "responses_limit": 1000                                         // só em /requests/create
}

Próximos passos

Como funciona a cobrança

Cálculo do cost, faixas de preço e tratamento de erros de billing.

Lista de tribunais

Tabela completa de IDs aceitos no campo tribunals.

Quickstart

Receita prática com count → create → poll → paginate.

Referência da API

Spec interativa para testar cada endpoint.

Primeiros Passos

Conceitos

Referência da API · Miner

Conceitos do Miner — kind, natures, tags e tiers

`kind` (obrigatório)

`natures` (apenas `judgement-bond`)

`budget_years` (apenas `judgement-bond`)

`tags` (apenas `sentence-execution`)

Faixa de valor

Modo 1 — Limites livres (`amount_min` / `amount_max`)

Modo 2 — Faixa pré-definida (`amount_tier`)

`tribunals`

`responses_limit` (apenas `/requests/create`)

Regras de combinação

Schema completo (referência rápida)

Próximos passos

Como funciona a cobrança

Lista de tribunais

Quickstart

Referência da API

​kind (obrigatório)

​natures (apenas judgement-bond)

​budget_years (apenas judgement-bond)

​tags (apenas sentence-execution)

​Faixa de valor

​Modo 1 — Limites livres (amount_min / amount_max)

​Modo 2 — Faixa pré-definida (amount_tier)

​tribunals

​responses_limit (apenas /requests/create)

​Regras de combinação

​Schema completo (referência rápida)

​Próximos passos

Como funciona a cobrança

Lista de tribunais

Quickstart

Referência da API

`kind` (obrigatório)

`natures` (apenas `judgement-bond`)

`budget_years` (apenas `judgement-bond`)

`tags` (apenas `sentence-execution`)

Faixa de valor

Modo 1 — Limites livres (`amount_min` / `amount_max`)

Modo 2 — Faixa pré-definida (`amount_tier`)

`tribunals`

`responses_limit` (apenas `/requests/create`)

Regras de combinação

Schema completo (referência rápida)

Próximos passos