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

# Compartir información KYB a través de entidades

> Envía la información KYB de un subcomerciante con la API de Entidades: la empresa, sus propietarios, su representante legal y sus documentos.

Esta guía muestra, llamada por llamada y con solicitudes y respuestas, cómo enviar la información indicada en los [Requisitos KYB para Beneficiarios de Cuentas Virtuales](https://docs.localpayment.com/es/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md) mediante la API de Entidades. Dónde va cada elemento en Entidades se indica en la columna Cómo enviarlo de esa página. En resumen: la empresa es una entidad de tipo `COMPANY`, cada persona es una entidad de tipo `INDIVIDUAL` (los propietarios se vinculan a la empresa como UBO) y cada documento es un documento declarado con sus archivos. Los ejemplos usan una empresa ficticia registrada en Brasil.

## Requisitos previos

* Este flujo se aplica a las Cuentas virtuales en Brasil.
* Un token de acceso de etapa. Consulta [Obtener token de acceso](https://docs.localpayment.com/es/reference/get-token.md).
* Un esquema de campos personalizados publicado para tu comerciante con los campos KYB. Consulta [Campos personalizados](https://docs.localpayment.com/es/docs/custom-fields.md).
* La información y los documentos de la empresa, sus propietarios y su representante legal. Consulta los [Requisitos KYB para Beneficiarios de Cuentas Virtuales](https://docs.localpayment.com/es/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md).

## 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. Lea su esquema de campos personalizados<br/>GET /api/entity/v1/custom-fields/schema"]:::lp --> B["2. Cree la empresa<br/>POST /api/entity/v1/entities, type COMPANY<br/>identificación fiscal como documento principal, perfil del negocio en attributes"]
    B --> DH["3. Documentos de la empresa<br/>uno por documento, cada uno con sus archivos"]:::lp
    DH --> D1["ARTICLES_OF_INCORPORATION<br/>más organigrama de propiedad cuando sea necesario"]
    DH --> D2["PROOF_OF_FUNDS<br/>un archivo por documento"]
    DH --> D3["OTHER<br/>comprobante de titularidad, B2C"]
    D1 & D2 & D3 --> PH["4 y 5. Personas<br/>un INDIVIDUAL por propietario y por el representante legal<br/>cada uno con su documento de identidad"]:::lp
    PH --> P1["Propietario 1<br/>documento de identidad<br/>FRONT, BACK"]
    PH --> P2["Propietario 2, 3, etc.<br/>mismos pasos"]
    PH --> P3["Representante legal<br/>mismos pasos"]
    P1 --> L1["6. Vincule a la empresa, propietario 1<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P2 --> L2["6. Vincule a la empresa, a cada otro propietario<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P3 --> L3["6. Vincule a la empresa, representante legal<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage 0, controlRole LEGAL_REPRESENTATIVE"]
    L1 & L2 & L3 --> V["7. Avise a Localpayment que la carga está completa<br/>POST /api/entity/v1/entities/{companyId}/verify"]
    V --> G[/"Localpayment revisa<br/>la empresa y a cada persona"/]:::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
```

> [!NOTE]
>
> **Representante legal.** Créalo como un `INDIVIDUAL` (su documento de identidad puede ser el documento principal) y vincúlalo a la empresa con [Vincular un UBO](https://docs.localpayment.com/es/reference/link-ubo.md): `ownershipPercentage: 0` y `controlRole: LEGAL_REPRESENTATIVE`. Si el representante legal también es propietario, vincúlalo una sola vez, con su porcentaje y `controlRole: LEGAL_REPRESENTATIVE`.

## Paso a paso

Ejecuta las llamadas siguientes en este orden. Conserva cada `internalId` y `documentId` que devuelva la API. Los ejemplos envían solo lo mínimo.

### Lee el esquema de tus campos personalizados.

`GET /api/entity/v1/custom-fields/schema` devuelve los atributos que acepta tu cuenta. Extracto con el perfil comercial:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "businessProfile": {
    "type": "string",
    "enum": [
      "MARKETPLACE",
      "B2C",
      "B2B"
    ]
  }
}
```

### Crear la empresa

`POST /api/entity/v1/entities`. El número de identificación fiscal es el documento principal, y el perfil comercial va en `attributes`:

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "COMPANY",
  "name": "Example Company S.A.",
  "residenceCountry": "BRA",
  "document": {
    "type": "CNPJ",
    "id": "00000000000100",
    "issuingCountry": "BRA"
  },
  "website": "https://www.example.com",
  "attributes": {
    "businessProfile": "B2C"
  }
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "COMPANY",
  "status": "PENDING_KYC",
  "name": "Example Company S.A.",
  "residenceCountry": "BRA",
  "website": "https://www.example.com",
  "attributes": {
    "businessProfile": "B2C"
  },
  "documentationStatus": "NO_FILES"
}
```

La respuesta es 201 Created (extracto). El documento principal se devuelve con su `documentId` y sin archivos, lo cual es lo esperado: no los necesitas.

### Declara los documentos de la empresa y sube sus archivos.

Declara cada documento con `POST /api/entity/v1/entities/{companyId}/documents`. El documento de constitución lleva el número de registro en `id` (en Brasil, el CNPJ):

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "ARTICLES_OF_INCORPORATION",
  "id": "00000000000100",
  "issuingCountry": "BRA"
}
```

Luego envía un `POST /api/entity/v1/documents/{documentId}/proofs` por archivo, con `proofType=DOCUMENT` y el archivo. Respuesta (extracto):

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "4653bc4d-7df4-41c4-b8ef-60e7a3a378bb",
  "documentId": "84f3b6db-7b74-4def-968d-cbb5bf90cab7",
  "proofType": "DOCUMENT",
  "fileName": "certificate_of_incorporation.pdf",
  "mimeType": "application/pdf",
  "verificationStatus": "PENDING",
  "status": "CURRENT"
}
```

Declara y carga de la misma forma los documentos del origen de los fondos y, para `B2C`, el comprobante de titularidad:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "type": "PROOF_OF_FUNDS",
    "id": "SALES-2024-Q1",
    "issuingCountry": "BRA"
  },
  {
    "type": "OTHER",
    "id": "DOMAIN-example",
    "issuingCountry": "BRA"
  }
]
```

### Crea cada persona

Un `INDIVIDUAL` por cada propietario y para el representante legal, con `POST /api/entity/v1/entities`. El documento de identidad puede ser el documento principal:

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INDIVIDUAL",
  "name": "Jane",
  "lastname": "Doe",
  "residenceCountry": "BRA",
  "document": {
    "type": "NATIONAL_ID",
    "id": "000000000",
    "issuingCountry": "BRA"
  }
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "type": "INDIVIDUAL",
  "status": "PENDING_KYC",
  "document": {
    "documentId": "e6d636a0-362c-4e17-9ac9-5451d56ed393",
    "type": "NATIONAL_ID",
    "id": "000000000",
    "issuingCountry": "BRA",
    "isPrimary": true
  }
}
```

La respuesta es 201 Created (extracto).

### Carga el documento de identidad de cada persona

El anverso y el reverso van al mismo documento: `POST /api/entity/v1/documents/{documentId}/proofs` con `proofType=FRONT`, y luego con `proofType=BACK` (pasaporte: solo `FRONT`). Extracto de `GET /api/entity/v1/documents/{documentId}/proofs` después de ambas cargas:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "id": "d577e8e5-ef53-43b8-aaa3-b97ca202949a",
    "proofType": "FRONT",
    "fileName": "id_front.jpg",
    "verificationStatus": "PENDING",
    "status": "CURRENT"
  },
  {
    "id": "21e6e46d-e047-4f19-88f4-175132839e04",
    "proofType": "BACK",
    "fileName": "id_back.jpg",
    "verificationStatus": "PENDING",
    "status": "CURRENT"
  }
]
```

### Vincula a cada persona con la empresa

Un `POST /api/entity/v1/entities/{companyId}/ubos` por persona. Jane Doe posee el 60 % y además es la representante legal:

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "ownershipPercentage": 60,
  "controlRole": "LEGAL_REPRESENTATIVE"
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "37325b16-514f-40f5-afca-a2acd201f629",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "ownershipPercentage": 60.0,
  "controlRole": "LEGAL_REPRESENTATIVE",
  "validFrom": "2024-01-15",
  "validTo": null,
  "createdAt": "2024-01-15T17:04:17Z"
}
```

John Doe posee el 40 %, con el rol en mayúsculas:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "c0b9c624-7777-4f6c-a4c5-57ef00f895c2",
  "ownershipPercentage": 40,
  "controlRole": "PARTNER"
}
```

`GET /api/entity/v1/entities/{companyId}/ubos` lista ambos:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "items": [
    {
      "id": "37325b16-514f-40f5-afca-a2acd201f629",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
      "ownershipPercentage": 60.0,
      "controlRole": "LEGAL_REPRESENTATIVE",
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:04:17Z"
    },
    {
      "id": "848b821f-1ebb-42cf-b4c1-634b5db579e6",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "c0b9c624-7777-4f6c-a4c5-57ef00f895c2",
      "ownershipPercentage": 40.0,
      "controlRole": "PARTNER",
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:04:18Z"
    }
  ]
}
```

Conserva el `internalId` de la empresa: identifica al beneficiario en Localpayment.

### Notifica a Localpayment que la carga se ha completado.

Cuando la empresa, sus documentos y todas las personas estén cargados y vinculados, llama a `POST /api/entity/v1/entities/{companyId}/verify` sobre la empresa ([Solicitar verificación](https://docs.localpayment.com/es/reference/request-entity-verification.md)). Esto informa a Localpayment de que la carga de la documentación está completa. La respuesta es `202 Accepted` (extracto):

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "COMPANY",
  "status": "IN_REVIEW",
  "updatedAt": "2024-01-15T17:05:00Z"
}
```

Mientras la empresa está en `IN_REVIEW`, queda bloqueada (409 `ENTITY_IN_REVIEW`). Con `verify` termina tu parte de la carga: no necesitas consultar el estado de la entidad después.

## Lista de verificación

* Cada documento que tú declaraste (constitución de la empresa, origen de los fondos, documentos de identidad) tiene su archivo. Un documento de identificación fiscal principal no necesita archivo.
* Cada propietario está vinculado a la empresa con su `ownershipPercentage`, y el representante legal con `controlRole: LEGAL_REPRESENTATIVE`.
* `attributes.businessProfile` está establecido en la empresa.
* Una vez cargado todo, llamaste a `verify` sobre la empresa.
* Los números de identificación fiscal contienen solo dígitos, y los nombres coinciden exactamente con los documentos.
* Todos los archivos son PDF, PNG, JPG o JPEG y pesan menos de 10 MB.

> [!NOTE]
>
> Una vez completada la lista de verificación, Localpayment revisa la empresa y a cada persona, e indica si hay algo que corregir. Consulta [Seguimiento de la revisión y Corrección de rechazos](https://docs.localpayment.com/es/docs/track-review-and-fix-rejections.md).

## 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 las instrucciones de la revisión y corrige lo que te pida Localpayment.

> [card] [Gestionar UBO](https://docs.localpayment.com/es/docs/manage-ubos.md)
>
> Actualizar o eliminar los enlaces del propietario.


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