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

# Gerenciar UBOs

> Vincule os beneficiários finais (UBOs) de uma entidade empresarial, atualize sua titularidade e função e remova os links que não são mais aplicáveis.

Um UBO é uma pessoa física que possui ou controla uma empresa. Em Entities, um UBO não é um objeto separado: é um vínculo entre uma entidade `COMPANY` e uma entidade `INDIVIDUAL`.

## Pré-requisitos

* A empresa registrada como uma entidade `COMPANY`. Consulte [Criar uma entidade](https://docs.localpayment.com/pt-br/docs/create-an-entity.md).
* Cada proprietário registrado como uma entidade `INDIVIDUAL`, com seus próprios documentos e arquivos.
* O `internalId` da empresa e de cada proprietário.

## Fluxo

```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. Crie cada sócio<br/>POST /api/entity/v1/entities (INDIVIDUAL)"] --> B["2. Envie as provas deles"]
    C["3. Crie a empresa<br/>POST /api/entity/v1/entities (COMPANY)"] --> D["4. Envie as provas da empresa"]
    B --> E["5. Vincule cada sócio<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. A Localpayment analisa<br/>a empresa e cada sócio"]:::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
```

O link precisa de ambos os valores de `internalId`, então crie as entidades primeiro. Os proprietários podem ser vinculados enquanto a empresa ainda estiver `PENDING_KYC`.

## Link para o proprietário

Link para Jane Doe como CEO com 60% de participação acionária:

```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"
}
```

Vincule John Doe como sócio com 40%. Envie a função em letras maiúsculas; minúsculas ou maiúsculas e minúsculas misturadas (`Partner`) retornam 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"
}
```

Após vincular, [Obter uma Entidade](https://docs.localpayment.com/pt-br/reference/get-entity.md) na empresa retorna `uboCount` e `uboRequirementMet`.

## Regras

| Regra | Comportamento |
| - | - |
| Tipos | companyId deve ser COMPANY e personId deve ser INDIVIDUAL (422 INVALID\_ENTITY\_TYPE). |
| Situação da empresa | Não pode ser CLOSED, BLOCKED ou REJECTED (422 ENTITY\_NOT\_ACTIVE). Enquanto estiver IN\_REVIEW, os links não podem ser criados, alterados nem encerrados (409 ENTITY\_IN\_REVIEW). |
| Percentagem | De 0 a 100, com até duas casas decimais (422 INVALID\_PERCENTAGE). Envie `null` quando a porcentagem for desconhecida. |
| Função | Um dos códigos de função listados em [Vincular um UBO](https://docs.localpayment.com/pt-br/reference/link-ubo.md), com distinção entre maiúsculas e minúsculas (422 INVALID\_CONTROL\_ROLE). Valores: `LEGAL_REPRESENTATIVE` para o representante legal, `AUTHORIZED_SIGNATORY` para uma pessoa que assina sob procuração e a função de um proprietário, como `CEO`, `DIRECTOR`, `PARTNER` ou `OWNER` (lista completa nas [listas de opções dos Requisitos de KYB](https://docs.localpayment.com/pt-br/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md#control-roles)). |
| Validade | validFrom tem como valor padrão a data de hoje. validTo não deve precedê-lo (422 INVALID\_VALIDITY\_RANGE). |
| Limites | 50 links ativos por empresa (409 UBO\_LIMIT\_EXCEEDED). Um link ativo por pessoa e empresa (409 UBO\_ALREADY\_LINKED). |
| Privacidade | As respostas do UBO contêm apenas identificadores. Leia a pessoa com "Obter uma Entidade". |

Erro ao vincular a mesma pessoa duas vezes:

```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": []
}
```

Considere `UBO_ALREADY_LINKED` como um sucesso ao tentar novamente um link e leia os links atuais com [Listar UBOs de uma empresa](https://docs.localpayment.com/pt-br/reference/list-company-ubos.md).

## Manter links

* **Alterar a porcentagem ou a função:** [Atualizar um UBO](https://docs.localpayment.com/pt-br/reference/update-ubo.md). A função não pode ser removida: altere-a para outro código ou encerre o link com [Encerrar um vínculo UBO](https://docs.localpayment.com/pt-br/reference/end-ubo-link.md) e vincule a pessoa novamente sem `controlRole`.
* **Encerrar uma propriedade:** [Encerrar um vínculo UBO](https://docs.localpayment.com/pt-br/reference/end-ubo-link.md) define `validTo` como a data atual. O histórico é mantido e fica visível com `includeEnded=true`.
* **Ver pelo lado da pessoa:** [Listar empresas de uma pessoa](https://docs.localpayment.com/pt-br/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 proprietário é uma entidade com seu próprio KYC, analisado pela Localpayment junto com a empresa. `uboRequirementMet` apenas informa que pelo menos um proprietário está vinculado, não que os proprietários estejam aprovados.

## Próximos passos

> [card] [Acompanhe a revisão e corrija as rejeições.](https://docs.localpayment.com/pt-br/docs/track-review-and-fix-rejections.md)
>
> Acompanhe a avaliação da empresa e de cada proprietário.

> [card] [Inclua uma referência UBO](https://docs.localpayment.com/pt-br/reference/link-ubo.md)
>
> Todos os campos de solicitação, campos de resposta e códigos de erro.


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