> ## 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.

# Obtener socios materializados

> Lee los socios y el resto de relaciones ya materializados de una entidad, sin volver a ejecutar un enrichment.

## Visión general

Devuelve los **socios y las demás relaciones ya guardados** de una persona o empresa. Es una lectura de `entities` y `entity_relationships`. **No** llama integraciones, **no** materializa filas nuevas y **no** consume créditos de enrichment.

Úselo después de la [creación automática](/es/api-reference/entities/create-automatic) cuando necesite los mismos socios más tarde. `data.shareholders` de ese POST es solo la respuesta del alta (`id`, `name`, `taxId`, `type` de las fichas hijas materializadas en esa corrida). El porcentaje y los roles quedan en la relación y se leen acá en `shareholderInfo`.

Las filas de QSA que nunca se convirtieron en entidades (por ejemplo un documento enmascarado) no entran. Siguen en [Obtener enrichment normalizado](/es/api-reference/enrichment/get-normalized).

Exige el permiso granular **`entities:read`** en la API key (fallback legacy `entities:read`).

## Endpoints

Los dos devuelven el mismo body. La organización sale de la API key.

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

## Autenticación

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

## Parámetros de ruta

<ParamField path="id" type="string">
  UUID de la entidad. Úselo en `GET /entities/{id}/shareholders`.
</ParamField>

<ParamField path="taxId" type="string">
  Identificador fiscal guardado en la entidad (CNPJ, CUIT, etc.). Los dígitos se comparan igual que en [obtener por tax id](/es/api-reference/entities/get). Úselo en `GET /entities/by-tax-id/{taxId}/shareholders`. Si hay varias filas, se usa la creada más recientemente.
</ParamField>

## Parámetros de query

<ParamField query="depth" type="integer" default="1">
  Cuántos niveles de propiedad recorrer en `shareholders`. `1` son solo los dueños directos. Máximo `5`. La lista es plana y se deduplica por id de entidad. Las empresas anidadas se expanden solo si `depth` es mayor que 1. `relationships` sigue siendo un salto desde la entidad consultada.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Tamaño de página aplicado **por separado** a `shareholders` y a `relationships`. Máximo `500`.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Cuántos ítems omitir en cada array. Se aplica después de los filtros de socios.
</ParamField>

<ParamField query="type" type="string">
  Deja solo socios cuyo tipo sea `person` o `company`. Los vínculos de `relationships` no se filtran.
</ParamField>

<ParamField query="taxId" type="string">
  Identificador fiscal exacto del socio. Se comparan los dígitos, así `123.456.789-00` coincide con `12345678900`.
</ParamField>

<ParamField query="minRiskScore" type="number">
  `riskScore` mínimo, inclusive. Los socios con `riskScore: null` quedan fuera si se envía este parámetro o `maxRiskScore`.
</ParamField>

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

<ParamField query="minOwnershipPercentage" type="number">
  Porcentaje de participación mínimo, inclusive. Los socios sin porcentaje guardado quedan fuera si se envía este parámetro o `maxOwnershipPercentage`.
</ParamField>

<ParamField query="maxOwnershipPercentage" type="number">
  Porcentaje de participación máximo, inclusive.
</ParamField>

Los filtros se combinan con AND. Aplican solo a `shareholders`, después de recorrer `depth` y antes de `limit` / `offset`. Una empresa que no cumple el filtro igual se recorre cuando `depth` es mayor que 1, así un dueño que sí cumple debajo de ella puede aparecer. `minRiskScore` no puede ser mayor que `maxRiskScore`; lo mismo vale para los límites de porcentaje (`400`).

## Respuesta

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

Los vínculos de propiedad usan dirección **socio = source**, **entidad poseída = target**, y un tipo `shareholder`, `owns` o `controls`. Esos van en `shareholders`. El resto de vínculos no borrados en los que esta entidad es source o target van en `relationships`.

<ResponseField name="entityId" type="string">
  UUID de la entidad consultada.
</ResponseField>

<ResponseField name="shareholders" type="array">
  Dueños materializados.

  * `id`, `name`, `taxId`, `type`, `riskScore` — la entidad relacionada. `riskScore` es `null` si el socio no tiene score. `taxId` es `null` si la API key no tiene `entities:read_sensitive`.
  * `shareholderInfo.percentage` — `metadata.shareholdingPercentage`, o `null`
  * `shareholderInfo.roles` — `metadata.roles` (array vacío si no hay)
  * `shareholderInfo.isActive` — `metadata.isActive`, o `null`
</ResponseField>

<ResponseField name="totalShareholders" type="number">
  Socios que cumplen los filtros, antes de `limit` / `offset`.
</ResponseField>

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

  * `id`, `name`, `taxId`, `type` — la entidad relacionada. `taxId` es `null` si la API key no tiene `entities:read_sensitive`.
  * `relationshipType` — tipo de vínculo (por ejemplo `related_to`)
</ResponseField>

<ResponseField name="totalRelationships" type="number">
  Los demás vínculos, antes de `limit` / `offset`. Los filtros no cambian este total.
</ResponseField>

Una entidad sin vínculos responde `200` y ambos arrays vacíos.

## Errores

| Estado | Código | Cuándo |
| - | - | - |
| 400 | `INVALID_ENTITY_ID` | `id` no es un UUID |
| 404 | `NOT_FOUND` | No hay una entidad viva con ese id o tax id en tu organización |

## Ejemplo

```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.