Rede de processos

Visão Geral

Além dos processos do próprio documento (módulo lawsuits), o enriquecimento consulta os processos das pessoas e empresas ligadas a ele. Cada CPF ou CNPJ consultado é um nó da rede, e aparece uma única vez, mesmo quando é ligado ao documento por mais de um motivo (por exemplo, irmão e co-réu).

A rede roda quando o perfil tem os módulos related e lawsuits ligados. Ela faz parte do enriquecimento: o enriquecimento só chega a COMPLETED depois que todos os nós terminam (veja Quando a rede falha).

Quem entra na rede

Documento consultado	Nós
CPF	irmãos, filhos, pai e mãe (vínculo confirmado em registro, sem falecidos); empresas de que é sócio ou representante legal; co-réus em processos de risco
CNPJ	sócios pessoa física (QSA, sócio, representante legal); empresas sócias e do mesmo grupo; co-réus em processos de risco

Co-réus são as partes que respondem junto com o documento consultado, no polo passivo, em processos com indicador de crime, fraude ou risco de crédito (execução de dívida, falência). Advogados, juízes, peritos e outros não litigantes nunca entram. Uma empresa co-ré só entra se o documento consultado for sócio dela.

Cada caminho tem um limite de 15 documentos, e a rede inteira tem no máximo 60. candidates diz quantos documentos elegíveis existiam; selected, quantos foram consultados.

Como ligar a rede ao related

O related é a resposta do módulo related (GET /api/v3/enrichments/{id}/modules/related, ou data.related em GET /api/v3/enrichments/{id}?include=related).

A chave de nodes é o documento normalizado: só letras e dígitos, em maiúsculas (por exemplo 11144477735, ou 12ABC34501DE35 para o CNPJ alfanumérico). Normalize o valor do related do mesmo jeito (tire a pontuação e ponha em maiúsculas) antes de procurar o nó.

Consultado	Caminho no related	Chave em nodes
CPF	people[].document	o documento normalizado
CPF	companies[].document	o documento normalizado
CNPJ	parties[].taxId (taxIdType: CPF ou CNPJ)	o documento normalizado
CNPJ	group.documents[]	o documento normalizado

Exemplo para um CPF:

const norm = (doc) => doc.replace(/[^0-9A-Za-z]/g, "").toUpperCase();
const network = await get(`/api/v3/enrichments/${id}/modules/lawsuits/network`);
for (const person of related.people) {
  const node = network.nodes[norm(person.document)]; // undefined = não consultado
  if (node?.status === "ok" && node.counters.total > 0) {
    // mostrar o badge; ao abrir, buscar os processos:
    const detail = await get(`/api/v3/enrichments/${id}/modules/lawsuits/network/${node.ref}`);
  }
}

E para um CNPJ:

for (const party of related.parties) {
  const node = network.nodes[norm(party.taxId)];
  // ...
}
for (const doc of related.group.documents) {
  const node = network.nodes[norm(doc)];
  // ...
}

Os co-réus vêm do módulo lawsuits, não do related. Por isso um nó pode existir sem nenhuma entrada no related: para listar os co-réus, percorra o próprio nodes (Object.entries(network.nodes)) e filtre por relations[].type === "CO_DEFENDANT".

Formato de um nó

{
  "ref": "n01",
  "name": "MARIA SILVA",
  "entity": "person",
  "relations": [{ "type": "QSA", "role": "SOCIO-ADMINISTRADOR" }, { "type": "CO_DEFENDANT" }],
  "status": "ok",
  "reason": null,
  "dataset": "person-lawsuits-1.0",
  "counters": { "total": 7, "criminal": 1, "civil": 4 },
  "indicators": { "fraud": { "count": 1 } },
  "coverage": { "total": 8, "distinctCases": 7 }
}

• relations[].type: o motivo de o documento estar na rede (MOTHER, FATHER, SON, BROTHER, QSA, OWNERSHIP, REPRESENTANTELEGAL, LEGAL REPRESENTATIVE, GROUP para empresa do mesmo grupo, vinda de group.documents[], e CO_DEFENDANT).
• name: o nome do relacionado como o dado o traz (related ou as partes do processo); ausente quando nenhum dado traz o nome.
• relations[].role: o nome do vínculo como o provedor o informa, sem tradução (por exemplo OWNER ou SOCIO-ADMINISTRADOR); ausente quando o vínculo não tem (família, GROUP e CO_DEFENDANT). Um nó pode trazer, por exemplo, { "type": "QSA", "role": "SOCIO-ADMINISTRADOR" }.
• Os demais campos são os do dataset de processos, sem a lista de processos. O formato está em Datasets.
• status: ok, failed (reason: not_found, document_refused, exhausted) ou skipped (reason: response_too_large). Um nó com falha não é uma rede limpa: não houve dado para aquele documento.

Detalhe de um nó

GET /api/v3/enrichments/{id}/modules/lawsuits/network/{ref} devolve o nó com o documento e os processos:

{
  "ref": "n01",
  "document": "11144477735",
  "name": "MARIA SILVA",
  "entity": "person",
  "relations": [{ "type": "QSA", "role": "SOCIO-ADMINISTRADOR" }, { "type": "CO_DEFENDANT" }],
  "status": "ok",
  "reason": null,
  "dataset": "person-lawsuits-1.0",
  "lawsuits": {
    "counters": { "total": 7, "criminal": 1, "civil": 4 },
    "indicators": { "fraud": { "count": 1 } },
    "coverage": { "total": 8, "distinctCases": 7 },
    "items": [ ]
  }
}

lawsuits é o fato de processos do dataset, com a lista completa em items. Um nó failed ou skipped responde 200 com status e reason e sem lawsuits; na rede resumida, esses nós também não trazem counters.

Quando a rede não roda

GET …/network responde 200 com status: "skipped" e o motivo em reason:

reason	Quando
related_disabled	o perfil não tem o módulo related ligado
lawsuits_disabled	o perfil não tem o módulo lawsuits ligado
network_not_configured	o perfil não configura a consulta de processos dos relacionamentos
subject_not_found	o documento consultado não tem titular conhecido
not_run	o enriquecimento foi concluído sem a etapa da rede (por exemplo, antes de ela existir)

Nesses casos, GET …/network/{ref} responde 404 node_not_found.

Enquanto o enriquecimento não termina (CREATED ou FETCHING), as duas rotas respondem 409 network_not_ready: tente de novo mais tarde. Se o enriquecimento terminou FAILED e a rede iria rodar, respondem 409 enrichment_failed, que é definitivo: a mensagem traz o motivo da falha e não adianta tentar de novo. Um enriquecimento FAILED cuja rede estava inativa (ou cujo titular não foi encontrado, subject_not_found) responde 200 com skipped em …/network e 404 node_not_found em …/network/{ref}.

Quando a rede falha

Alguns nós podem falhar sem derrubar o enriquecimento: até cerca de 20% dos nós (no mínimo 1) podem terminar failed ou skipped, e o enriquecimento ainda chega a COMPLETED. Esses nós aparecem em nodes com o status e o reason deles.

Acima disso, o enriquecimento termina FAILED com failureReason network_incomplete. Ele também termina FAILED com network_unavailable quando a consulta de processos está indisponível do nosso lado, e com deadline_exceeded quando o prazo do enriquecimento (options.deadline) acaba antes de a rede terminar. Um enriquecimento FAILED não é cobrado.

Estado na raiz

A raiz do enriquecimento (GET /api/v3/enrichments/{id}) mostra o estado da rede em modules.lawsuits.network:

status	Significado
running	o enriquecimento ainda não terminou
ok	a rede foi consultada; documents diz quantos nós ela tem e withLawsuits, quantos têm ao menos um processo (os dois sempre presentes, inclusive 0)
skipped	a rede não rodou; reason traz um dos motivos da tabela acima
failed	o enriquecimento terminou FAILED e a rede iria rodar (com a rede inativa, vale skipped)

"lawsuits": {
  "dataset": "person-lawsuits-2.0",
  "status": "ok",
  "network": { "status": "ok", "documents": 12, "withLawsuits": 3 }
}