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

# Obter sócios materializados

> Lê os sócios e os demais relacionamentos já materializados de uma entidade, sem executar enrichment de novo.

## Visão geral

Devolve os **sócios e os demais relacionamentos já gravados** de uma pessoa ou empresa. É uma leitura de `entities` e `entity_relationships`. **Não** chama integrações, **não** materializa linhas novas e **não** consome créditos de enrichment.

Use depois da [criação automática](/pt/api-reference/entities/create-automatic) quando precisar dos mesmos sócios mais tarde. `data.shareholders` desse POST é só a resposta da criação (`id`, `name`, `taxId`, `type` das fichas filhas materializadas naquela corrida). Percentual e papéis ficam no relacionamento e são lidos aqui em `shareholderInfo`.

Linhas de QSA que nunca viraram entidades (por exemplo um documento mascarado) não entram. Continuam em [Obter enrichment normalizado](/pt/api-reference/enrichment/get-normalized).

Exige a permissão granular **`entities:read`** na API key (fallback legacy `entities:read`).

## Endpoints

Os dois devolvem o mesmo body. A organização vem da API key.

```
GET https://api.gu1.ai/entities/{id}/shareholders
GET https://api.gu1.ai/entities/by-tax-id/{taxId}/shareholders
```

## Autenticação

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parâmetros de rota

<ParamField path="id" type="string">
  UUID da entidade. Use em `GET /entities/{id}/shareholders`.
</ParamField>

<ParamField path="taxId" type="string">
  Identificador fiscal gravado na entidade (CNPJ, CUIT, etc.). Os dígitos são comparados do mesmo jeito que [obter por tax id](/pt/api-reference/entities/get). Use em `GET /entities/by-tax-id/{taxId}/shareholders`. Se houver várias linhas, usa-se a criada mais recentemente.
</ParamField>

## Parâmetros de query

<ParamField query="depth" type="integer" default="1">
  Quantos níveis de propriedade percorrer em `shareholders`. `1` são só os donos diretos. Máximo `5`. A lista é plana e deduplicada por id da entidade. Empresas aninhadas só entram se `depth` for maior que 1. `relationships` continua a um salto da entidade consultada.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Tamanho da página aplicado **em separado** a `shareholders` e a `relationships`. Máximo `500`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Quantos itens pular em cada array. Aplica-se depois dos filtros de sócios.
</ParamField>

<ParamField query="type" type="string">
  Mantém sócios cujo tipo seja `person` ou `company`. Os vínculos de `relationships` não são filtrados.
</ParamField>

<ParamField query="taxId" type="string">
  Identificador fiscal exato do sócio. Os dígitos são comparados, então `123.456.789-00` coincide com `12345678900`.
</ParamField>

<ParamField query="minRiskScore" type="number">
  `riskScore` mínimo, inclusive. Sócios com `riskScore: null` ficam de fora quando este parâmetro ou `maxRiskScore` é enviado.
</ParamField>

<ParamField query="maxRiskScore" type="number">
  `riskScore` máximo, inclusive.
</ParamField>

<ParamField query="minOwnershipPercentage" type="number">
  Percentual de participação mínimo, inclusive. Sócios sem percentual gravado ficam de fora quando este parâmetro ou `maxOwnershipPercentage` é enviado.
</ParamField>

<ParamField query="maxOwnershipPercentage" type="number">
  Percentual de participação máximo, inclusive.
</ParamField>

Os filtros se combinam com AND. Valem só para `shareholders`, depois de percorrer `depth` e antes de `limit` / `offset`. Uma empresa que não passa no filtro ainda é percorrida quando `depth` é maior que 1, então um dono que passa abaixo dela pode aparecer. `minRiskScore` não pode ser maior que `maxRiskScore`; a mesma regra vale para os limites de percentual (`400`).

## Resposta

`200` com `{ "success": true, "data": { ... } }`.

Vínculos de propriedade usam a direção **sócio = source**, **entidade possuída = target**, e um tipo `shareholder`, `owns` ou `controls`. Esses vão em `shareholders`. Os demais vínculos não apagados em que esta entidade é source ou target vão em `relationships`.

<ResponseField name="entityId" type="string">
  UUID da entidade consultada.
</ResponseField>

<ResponseField name="shareholders" type="array">
  Donos materializados.

  * `id`, `name`, `taxId`, `type`, `riskScore` — a entidade relacionada. `riskScore` é `null` se o sócio não tem score. `taxId` é `null` se a API key não tem `entities:read_sensitive`.
  * `shareholderInfo.percentage` — `metadata.shareholdingPercentage`, ou `null`
  * `shareholderInfo.roles` — `metadata.roles` (array vazio se não houver)
  * `shareholderInfo.isActive` — `metadata.isActive`, ou `null`
</ResponseField>

<ResponseField name="totalShareholders" type="number">
  Sócios que passam nos filtros, antes de `limit` / `offset`.
</ResponseField>

<ResponseField name="relationships" type="array">
  Outras contrapartes materializadas.

  * `id`, `name`, `taxId`, `type` — a entidade relacionada. `taxId` é `null` se a API key não tem `entities:read_sensitive`.
  * `relationshipType` — tipo do vínculo (por exemplo `related_to`)
</ResponseField>

<ResponseField name="totalRelationships" type="number">
  Os demais vínculos, antes de `limit` / `offset`. Os filtros não mudam esse total.
</ResponseField>

Uma entidade sem vínculos responde `200` e os dois arrays vazios.

## Erros

| Status | Código | Quando |
| - | - | - |
| 400 | `INVALID_ENTITY_ID` | `id` não é um UUID |
| 404 | `NOT_FOUND` | Não há entidade viva com esse id ou tax id na sua organização |

## Exemplo

```bash theme={null}
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/shareholders?depth=1" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "success": true,
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "shareholders": [
      {
        "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "João Silva",
        "taxId": "12345678900",
        "type": "person",
        "riskScore": 25,
        "shareholderInfo": {
          "percentage": 60,
          "roles": ["Sócio Administrador"],
          "isActive": true
        }
      }
    ],
    "totalShareholders": 1,
    "relationships": [
      {
        "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "name": "Carlos Lima",
        "taxId": "55566677788",
        "type": "person",
        "relationshipType": "related_to"
      }
    ],
    "totalRelationships": 1
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.