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

# Gestionar UBO

> Vincula a los beneficiarios finales (UBO, por sus siglas en inglés) de una entidad corporativa, actualiza su propiedad y función, y elimina los vínculos que ya no sean aplicables.

Un UBO es una persona física que posee o controla una empresa. En Entidades, un UBO no es un objeto separado: es un vínculo entre una entidad `COMPANY` y una entidad `INDIVIDUAL`.

## Requisitos previos

* La empresa registrada como entidad `COMPANY`. Consulta [Crear una entidad](https://docs.localpayment.com/es/docs/create-an-entity.md).
* Cada propietario registrado como entidad `INDIVIDUAL`, con sus propios documentos y archivos.
* El `internalId` de la empresa y de cada propietario.

## Flujo

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["1. Cree a cada propietario<br/>POST /api/entity/v1/entities (INDIVIDUAL)"] --> B["2. Cargue sus comprobantes"]
    C["3. Cree la empresa<br/>POST /api/entity/v1/entities (COMPANY)"] --> D["4. Cargue los comprobantes de la empresa"]
    B --> E["5. Vincule a cada propietario<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    D --> E
    E --> F["6. GET /api/entity/v1/entities/{companyId}<br/>uboCount, uboRequirementMet"]
    F --> G["7. Localpayment revisa<br/>la empresa y a cada propietario"]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

El vínculo necesita ambos valores de `internalId`, así que primero crea las entidades. Los propietarios pueden vincularse mientras la empresa aún está en estado `PENDING_KYC`.

## Enlace a un propietario

Vincula a Jane Doe como directora ejecutiva con el 60% de la propiedad:

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f", "ownershipPercentage": 60.0, "controlRole": "CEO"}'
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
  "ownershipPercentage": 60.0,
  "controlRole": "CEO",
  "validFrom": "2024-01-15",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:47Z"
}
```

Vincula a John Doe como socio con el 40%. Envía el rol en mayúsculas; en minúsculas o con mayúsculas y minúsculas mezcladas (`Partner`) se devuelve el error 422 `INVALID_CONTROL_ROLE`:

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01"
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "ownershipPercentage": 40.0,
  "controlRole": "PARTNER",
  "validFrom": "2023-06-01",
  "validTo": null,
  "createdAt": "2024-01-15T17:20:48Z"
}
```

Después de vincular, [Obtener una entidad](https://docs.localpayment.com/es/reference/get-entity.md) de la empresa devuelve `uboCount` y `uboRequirementMet`.

## Normas

| Regla | Comportamiento |
| - | - |
| Tipos | companyId debe ser una entidad COMPANY y personId una entidad INDIVIDUAL (422 INVALID\_ENTITY\_TYPE). |
| Estado de la empresa | No debe estar en CLOSED, BLOCKED ni REJECTED (422 ENTITY\_NOT\_ACTIVE). Mientras esté en IN\_REVIEW, no se pueden crear, modificar ni finalizar vínculos (409 ENTITY\_IN\_REVIEW). |
| Porcentaje | De 0 a 100 con hasta dos decimales (422 INVALID\_PERCENTAGE). Envía `null` cuando se desconozca el porcentaje. |
| Rol | Uno de los códigos de rol enumerados en [Vincular un UBO](https://docs.localpayment.com/es/reference/link-ubo.md), con distinción entre mayúsculas y minúsculas (422 INVALID\_CONTROL\_ROLE). Valores: `LEGAL_REPRESENTATIVE` para el representante legal, `AUTHORIZED_SIGNATORY` para una persona que firma con un poder notarial, y un rol de propietario como `CEO`, `DIRECTOR`, `PARTNER` u `OWNER` (lista completa en las [listas de opciones de los requisitos KYB](https://docs.localpayment.com/es/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md#control-roles)). |
| Validez | validFrom toma por defecto la fecha de hoy. validTo no debe ser anterior a ella (422 INVALID\_VALIDITY\_RANGE). |
| Límites | 50 enlaces activos por empresa (409 UBO\_LIMIT\_EXCEEDED). Un enlace activo por persona y empresa (409 UBO\_ALREADY\_LINKED). |
| Privacidad | Las respuestas de UBO solo contienen identificadores. Lee la información de la persona con Obtener una entidad. |

Error al vincular a la misma persona dos veces:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Conflict",
  "instance": "/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos",
  "code": "UBO_ALREADY_LINKED",
  "correlationId": "acdfa68b-e1da-4764-84df-0a1e949d0939",
  "details": []
}
```

Considera `UBO_ALREADY_LINKED` como un éxito cuando vuelvas a intentar un vínculo, y lee los vínculos actuales con [Listar los UBO de una empresa](https://docs.localpayment.com/es/reference/list-company-ubos.md).

## Mantener los enlaces

* **Cambiar el porcentaje o el rol:** [Actualizar un UBO](https://docs.localpayment.com/es/reference/update-ubo.md). El rol no se puede borrar: cámbialo por otro código, o finaliza el vínculo con [Finalizar un vínculo UBO](https://docs.localpayment.com/es/reference/end-ubo-link.md) y vincula a la persona de nuevo sin `controlRole`.
* **Finalizar una propiedad:** [Finalizar un vínculo UBO](https://docs.localpayment.com/es/reference/end-ubo-link.md) establece `validTo` en la fecha de hoy. El historial se conserva y es visible con `includeEnded=true`.
* **Verlo desde el lado de la persona:** [Listar las empresas de una persona](https://docs.localpayment.com/es/reference/list-person-ubo-companies.md).

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "items": [
    {
      "id": "4584b476-ccc6-4e98-be40-0c5082748e35",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "c1e384f5-ae1c-475e-9e64-a0abe533a96f",
      "ownershipPercentage": 55.5,
      "controlRole": null,
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:20:47Z"
    },
    {
      "id": "2c203b2b-5f92-427d-a75f-92981e2719bf",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
      "ownershipPercentage": 40.0,
      "controlRole": "PARTNER",
      "validFrom": "2023-06-01",
      "validTo": "2024-01-15",
      "createdAt": "2024-01-15T17:20:48Z"
    }
  ]
}
```

> [!WARNING]
>
> Cada propietario es una entidad con su propio KYC, revisado por Localpayment junto con la empresa. `uboRequirementMet` solo indica que hay al menos un propietario vinculado, no que los propietarios estén aprobados.

## Próximos pasos

> [card] [Realiza el seguimiento de las revisiones y corrige los rechazos.](https://docs.localpayment.com/es/docs/track-review-and-fix-rejections.md)
>
> Sigue la reseña de la empresa y de cada propietario.

> [card] [Enlace a una referencia de UBO](https://docs.localpayment.com/es/reference/link-ubo.md)
>
> Todos los campos de solicitud, campos de respuesta y códigos de error.


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