---
url: https://developers.zarv.com/api/id-v3/lawsuits-network.md
description: >-
  Como ler os processos dos relacionamentos de um CPF ou CNPJ no Zarv ID v3:
  quem entra na rede, o formato de cada nó e como ligar a rede ao módulo
  related.
---

# 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](#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:

```js
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:

```js
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ó

```json
{
  "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](/api/id-v3/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:

```json
{
  "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`) |

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