credit-score-cpf — judicial schema (per-process detail)

This is a companion page to the canonical credit-score-cpf — read that first for the merged shape, free-vs-paid scope, and the recommendation rubric. This page covers everything you need to know about the judicial slice: the raw upstream wire format, every per-process field, the severity bucketing your rental-screening handler uses, and what auxiliar’s pipeline actually guarantees on coverage and freshness.

Raw upstream — directd_processo_por_documento

Backed by Direct Data’s ProcessosJudiciaisCompleta endpoint. Returns one envelope of the form {metaDados, retorno: {documentoConsultado, processos[], totalProcessos, observacoes}}, where each item in processos[] is shaped as:

// Raw upstream — apiv3.directd.com.br/api/ProcessosJudiciaisCompleta?TOKEN=...&CPF=...
{
  "metaDados": { "resultadoId": 1, "mensagem": "Sucesso", "consultaUid": "direct-…", "tempoExecucaoMs": 1840 },
  "retorno": {
    "documentoConsultado": "87489953120",
    "totalProcessos": 1,
    "observacoes": null,
    "processos": [
      {
        "numeroProcesso": "0001234-56.2023.8.26.0100",
        "instancia": 1,
        "justicaGratuita": false,
        "segredoJustica": false,
        "processoDigital": true,
        "tutelaAntecipada": false,
        "prioritario": false,
        "orgaoJulgador": {
          "tribunal": "TJSP",
          "comarca": "São Paulo",
          "orgaoResponsavel": "5ª Vara Cível Central",
          "unidadeOrigem": "Foro Central Cível",
          "cidade": "São Paulo",
          "uf": "SP"
        },
        "ambitoJustica": "Justiça Estadual",
        "sistema": "PJe",
        "areaDireito": "Cível",
        "classificacao": {
          "codigoClassificacao": "7",
          "descricao": "Procedimento Comum Cível"
        },
        "assuntos": [
          { "codigoAssunto": "7691", "assunto": "Cobrança de Aluguéis - Sem Despejo", "assuntoPrincipal": true }
        ],
        "dataDistribuicao": "15/04/2023",
        "dataAutuacao": "15/04/2023",
        "partes": [
          { "nomeCompleto": "...", "documento": "...", "polo": "ATIVO",   "posicaoProcessual": "Autor",   "advogados": [/* … */] },
          { "nomeCompleto": "...", "documento": "...", "polo": "PASSIVO", "posicaoProcessual": "Réu",     "advogados": [/* … */] }
        ],
        "valorProcesso": "25000.00",
        "processosRelacionados": [],
        "detalhesStatusProcesso": {
          "statusDetalhes": "Em andamento",
          "dataArquivamento": null,
          "dataTransitoJulgado": null,
          "julgamentos": [],
          "penhoras": []
        }
      }
    ]
  }
}

The auxiliar gateway returns this verbatim under result. Your client merges into the screening shape as:

{
  "judicial": {
    "process_count": 1,                            // <- result.retorno.totalProcessos
    "processes": [
      {
        "numero": "0001234-56.2023.8.26.0100",     // <- processo.numeroProcesso
        "tribunal": "TJSP",                        // <- processo.orgaoJulgador.tribunal
        "ambito": "Justiça Estadual",              // <- processo.ambitoJustica
        "vara": "5ª Vara Cível Central",           // <- processo.orgaoJulgador.orgaoResponsavel
        "comarca_uf": "São Paulo/SP",              // <- comarca + uf joined
        "data_distribuicao": "2023-04-15",         // <- processo.dataDistribuicao (BR-format → ISO)
        "polo_ativo": ["..."],                     // <- partes[?polo=ATIVO].nomeCompleto[]  (PII — internal only)
        "polo_passivo": ["..."],                   // <- partes[?polo=PASSIVO].nomeCompleto[] (PII — internal only)
        "valor_causa": 25000.00,                   // <- processo.valorProcesso (string → float)
        "area_direito": "Cível",                   // <- processo.areaDireito
        "natureza": "Cobrança de Aluguéis - Sem Despejo",  // <- assuntos[?assuntoPrincipal=true].assunto
        "natureza_codigo": "7691",                 // <- assuntos[?assuntoPrincipal=true].codigoAssunto
        "segredo_justica": false,                  // <- processo.segredoJustica
        "status": "Em andamento",                  // <- detalhesStatusProcesso.statusDetalhes
        "transitado": false,                       // <- detalhesStatusProcesso.dataTransitoJulgado != null
        "arquivado": false                         // <- detalhesStatusProcesso.dataArquivamento != null
      }
    ],
    "tier_required": null
  }
}

Cache TTL is 7 days — process metadata rarely changes mid-week. Pair with a tribunal-specific webhook if you need <24h freshness for a fraud-detection pipeline.

Per-process field reference

Every field on each processos[] item, in upstream camelCase order. Use this when your handler needs to map a raw upstream payload to your snake_case merged shape.

Identity + procedural posture

• numeroProcesso — CNJ-padronizado 20-digit format (NNNNNNN-DD.AAAA.J.TR.OOOO). Already normalized upstream.
• instancia — integer, 1 = primeira instância (trial), 2 = recurso ordinário, etc.
• justicaGratuita — boolean. true = the party is a beneficiary of free legal aid (signal of low-income posture but not decisive).
• segredoJustica — boolean. true = case is sealed; partes[] will be redacted upstream (case number and tribunal still surface). Treat as “exists, can’t read” rather than “doesn’t exist”.
• processoDigital — boolean. true for tribunais on PJe / e-Saj / etc.
• tutelaAntecipada — boolean. true = preliminary-injunction granted before final ruling.
• prioritario — boolean. true = case has procedural priority (idoso, doença grave, criança/adolescente).

Tribunal + organ

• orgaoJulgador.tribunal — short code (e.g. TJSP, TRF3, STJ). See the tribunal coverage table below.
• orgaoJulgador.comarca — judicial-district name.
• orgaoJulgador.orgaoResponsavel — specific vara / câmara / turma (e.g. 5ª Vara Cível Central).
• orgaoJulgador.unidadeOrigem — building / forum complex.
• orgaoJulgador.cidade + orgaoJulgador.uf — city and state.
• ambitoJustica — Justiça Estadual | Justiça Federal | Justiça do Trabalho | Justiça Eleitoral | Justiça Militar | Justiça Especial.
• sistema — case-management system (PJe, e-Saj, Projudi, EProc, etc.).

Subject + classification

• areaDireito — high-level legal area: Cível, Trabalhista, Criminal, Família, Tributário, Empresarial, Consumidor, etc.
• classificacao.codigoClassificacao + classificacao.descricao — CNJ classe code (e.g. 7 / Procedimento Comum Cível). One per process.
• assuntos[] — list of CNJ-tabela assunto entries; each has codigoAssunto, assunto (free-text Portuguese label), and assuntoPrincipal (boolean — exactly one is true). The principal assunto is what you bucket for severity.

Dates + status

• dataDistribuicao — BR-format DD/MM/YYYY when the case was distributed to a tribunal. Normalize to ISO.
• dataAutuacao — BR-format date when filed in the registry. Normalize to ISO.
• detalhesStatusProcesso.statusDetalhes — free-text status (e.g. Em andamento, Suspenso, Arquivado definitivamente, Transitado em julgado). Reflects last upstream tribunal sync (24–72h lag).
• detalhesStatusProcesso.dataArquivamento — ISO-ish date when archived; null if still active. Use as arquivado = (value != null).
• detalhesStatusProcesso.dataTransitoJulgado — ISO-ish date when the matter became res judicata. Use as transitado = (value != null). This is decisive for severity. For the rental “recent eviction within 24 months” hard veto on the canonical page: use this field as the recency anchor when transitado == true (eviction is final), and fall back to dataDistribuicao when transitado == false (action filed but not yet final). Do not key off dataAutuacao or status-text for that rule — those are noisier signals.
• detalhesStatusProcesso.julgamentos[] — list of judgment entries (ruling date, body, vote count). Empty for pending matters.
• detalhesStatusProcesso.penhoras[] — list of attachment / lien entries. Material for collection-risk assessment but rare for residential-rental screening.

Parties + lawyers

• partes[] — list of { nomeCompleto, documento, polo, posicaoProcessual, advogados[] } entries.
  • polo — ATIVO (plaintiff side) or PASSIVO (defendant side).
  • posicaoProcessual — fine-grained role: Autor, Réu, Reclamante, Reclamado, Exequente, Executado, etc.
  • advogados[] — list of OAB-registered attorneys representing this party.
• All party fields are full PII. Per LGPD posture, internal-decisioning only — never re-display in tenant-facing UI.

Financial

• valorProcesso — string, BRL, parses as float. The declared cause-of-action value at filing. Plaintiff-declared, not adjudicated; useful only as a rough magnitude indicator.
• processosRelacionados[] — list of numeroProcesso strings for related cases (apenso, recursos, execução).

Severity bucketing (rental-screening default)

The upstream assunto (or classificacao.descricao) is a free-text Portuguese label drawn from CNJ’s “Tabelas Processuais Unificadas”. There is no built-in numeric severity score — auxiliar surfaces the raw labels and lets your decisioning policy classify. A reasonable default rental-screening bucketing:

This is your policy, not auxiliar’s policy — the gateway does not pre-classify. Build a small lookup table from assunto strings to your bucket and version-pin it; CNJ’s tabela updates infrequently. Use processo.transitado === true as a strong signal that the matter is closed (transitado em julgado).

The 4-way recommendation rubric on the canonical page folds these buckets into the score × judicial decision matrix.

Process normalization

What you can rely on:

• Numeric format. numeroProcesso is the CNJ-padronizado 20-digit format (NNNNNNN-DD.AAAA.J.TR.OOOO). Already normalized upstream — no re-formatting needed.
• Deduplication. Direct Data deduplicates per (numeroProcesso, instancia) before returning. The same process across multiple instâncias appears as separate items — group client-side by the first 14 digits of numeroProcesso if you want a unique-process count.
• Status freshness. detalhesStatusProcesso.statusDetalhes reflects the last upstream tribunal sync Direct Data ran — typical lag 24–72h, occasionally up to 7d for slower tribunals. Direct Data refreshes its mirror nightly; auxiliar’s 7-day cache TTL stacks on top. For fraud-detection pipelines that need <24h freshness, bypass the cache (set Cache-Control: no-cache on your call — the gateway honors it for paid-tier callers and bills you per call) or pair with a court-specific webhook.
• Polo enrichment. partes[].nomeCompleto is full PII (the names of plaintiffs, defendants, advogados). Per LGPD posture, internal-decisioning only — never re-display in tenant-facing UI.

Tribunal coverage

Direct Data’s ProcessosJudiciaisCompleta aggregates from the CNJ DataJud public dataset + per-tribunal direct integrations. Coverage is broad but not 100% of every Brazilian tribunal:

If a tribunal is “Partial” or “Not covered” and the screening matters (e.g. a vendor with material STF activity), pair this call with a tribunal-direct lookup or surface the gap explicitly to the operator. Authoritative source for current Direct Data coverage: https://docs.directd.com.br/ProcessosJudiciaisCompleta (vendor-maintained — re-check before relying on a specific tribunal for compliance-grade screening).

Segredo de justiça

The processo.segredoJustica flag is surfaced when the case is in segredo de justiça but the underlying partes[] are then redacted upstream — you’ll get the case number and tribunal but not party names. Treat this as “exists, can’t read” rather than “doesn’t exist”:

• For rental screening, the existence of a sealed case is itself a signal — even without partes[] you can see assunto and tribunal. A sealed Família — Violência Doméstica case versus a sealed Empresarial — Recuperação Judicial carries very different decisioning weight.
• Don’t try to deduce the redacted parties from processosRelacionados[] — that’s a privacy-defeating workaround and likely breaches LGPD posture.

For the merged shape, recommendation rubric, and LGPD posture, return to /data/credit-score-cpf/.

For the other upstream payload shapes (Direct Data Score, Obito, CadastroPessoaFisicaPlus, sancoes_empresa, rating_actions_brazil_recent), see /data/credit-score-cpf-upstream-shapes/.