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

# Descripción general de las entidades

> Registra a las personas y empresas con las que trabajas, adjunta su documentación KYC/KYB y sigue el proceso de revisión realizado por Localpayment.

Entidades te permite registrar a las personas (`INDIVIDUAL`) y empresas (`COMPANY`) con las que trabajas, declarar su identidad y sus documentos de respaldo, subir los archivos que los acreditan y seguir el resultado de la revisión KYC/KYB realizada por Localpayment. Entidades se comparte entre payins y payouts: la misma entidad se puede usar en todos los productos de Localpayment.

Esta guía está dirigida a desarrolladores que incorporan clientes, beneficiarios o socios comerciales a través de la API.

> [!NOTE]
>
> Entidades almacena datos de identidad y pruebas, y registra el resultado de la revisión. Tú solicitas la revisión con Solicitar verificación, pero nunca la apruebas: la decide Localpayment Compliance. Entidades no valida los números de documento contra registros gubernamentales y no mantiene saldos.

## Objetos

| Objeto | Qué es | Identificador |
| - | - | - |
| Entidad | Una persona (INDIVIDUAL) o una empresa (COMPANY) que pertenece a tu cuenta de comerciante. Contiene datos KYC, una dirección, atributos personalizados y sus documentos. | internalId (UUID) y su externalId |
| Documento | Un documento declarado como dato: tipo, número, país emisor y vigencia. Admite tantos archivos como sean necesarios. Exactamente un documento por entidad es el principal (el documento de identificación, normalmente el identificador fiscal o el documento de identidad). | documentId |
| Prueba | Un archivo que respalda un documento: FRONT, BACK, SELFIE, DOCUMENT u OTHER. Hasta 10 MB. Cada prueba tiene su propio estado de revisión. | id (proofId) |
| Enlace UBO | La relación entre una COMPANY y un INDIVIDUAL que la posee o la controla, con ownershipPercentage y controlRole. | id (uboId) |
| Esquema de campos personalizados | Los campos adicionales de Localpayment configurados para tu cuenta de comerciante. Los valores se transmiten en los atributos y se validan en función de ellos. | version |

```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 LR
    M["Su cuenta de comercio"] --> S["Esquema de campos personalizados"]
    M --> P["Entidad: INDIVIDUAL"]
    M --> C["Entidad: COMPANY"]
    P --> D1["Documento: CPF (principal)<br/>comprobantes: FRONT, BACK, SELFIE"]
    P --> D2["Documento: PROOF_OF_ADDRESS<br/>comprobante: DOCUMENT"]
    C --> D3["Documento: CNPJ (principal)<br/>comprobante: DOCUMENT"]
    C --> D4["Documento: ARTICLES_OF_INCORPORATION<br/>comprobante: DOCUMENT"]
    C -.- L1(["Vínculo UBO: 60%, CEO"]):::lbl -.-> P
    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
```

## Cómo funciona

Tu integración tiene cinco pasos. El último, `verify`, le indica a Localpayment que la carga está completa e inicia la revisión. Con `verify` termina tu parte de la carga: después no necesitas consultar periódicamente el estado de la entidad. Solo vuelves a actuar sobre la entidad si Localpayment solicita una corrección.

```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 la entidad con su documento principal<br/>POST /api/entity/v1/entities"] --> B["2. Agregue los demás documentos<br/>POST /api/entity/v1/entities/{entityId}/documents"]
    B --> C["3. Cargue los archivos de cada documento<br/>POST /api/entity/v1/documents/{docId}/proofs"]
    C --> Q{"¿Es una empresa?"}
    Q --- L1(["sí"]):::lbl --> D["4. Vincule a los propietarios<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    Q --- L2(["no"]):::lbl --> V
    D --> V["5. Solicite la verificación<br/>POST /api/entity/v1/entities/{entityId}/verify<br/>sobre la empresa, una vez cargado todo"]
    V --> E[/"Localpayment revisa la entidad"/]:::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
```

| Paso | Endpoint | Resultado |
| - | - | - |
| 1 | [Crear una entidad](https://docs.localpayment.com/es/reference/create-entity.md) | Entidad en PENDING\_KYC con su documento principal. La respuesta incluye el ID del documento (documentId) al que se cargan los archivos. |
| 2 | [Agregar un documento](https://docs.localpayment.com/es/reference/add-entity-document.md) | Los demás documentos declarados: documento de identidad, comprobante de domicilio, estatutos sociales, poder notarial. |
| 3 | [Subir una prueba](https://docs.localpayment.com/es/reference/upload-proof.md) | Archivos adjuntos a cada documento, tantos como sean necesarios. documentationStatus cambia de NO\_FILES a PARTIAL y COMPLETE. |
| 4 | [Vincular un UBO](https://docs.localpayment.com/es/reference/link-ubo.md) | Solo para empresas. Crea primero a cada propietario como INDIVIDUAL (pasos 1 a 3) y luego vincúlalo con su porcentaje y su rol de control. La empresa muestra uboCount y uboRequirementMet. |
| 5 | [Solicitar verificación](https://docs.localpayment.com/es/reference/request-entity-verification.md) | 202 Accepted. La entidad pasa a IN\_REVIEW y queda bloqueada hasta que Localpayment la resuelva. |

Si Localpayment necesita una corrección, te indica qué debes corregir: cada archivo rechazado incluye su `verificationReason`. Sube un reemplazo con el mismo `proofType` o corrige los datos y luego llama de nuevo a [Solicitar verificación](https://docs.localpayment.com/es/reference/request-entity-verification.md). Consulta [Seguimiento de la revisión y corrección de rechazos](https://docs.localpayment.com/es/docs/track-review-and-fix-rejections.md).

## Estados de las entidades

```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
    S((Inicio)) --- L1(["Crear una entidad"]):::lbl --> PK[PENDING_KYC]
    PK --- L2(["Solicitar verificación, por usted"]):::lbl --> IR[IN_REVIEW]
    IR --- L3(["corrección solicitada, con motivo"]):::lbl --> PK
    IR --- L4(["aprobada"]):::lbl --> AC[ACTIVE]
    IR --- L5(["rechazada, con motivo"]):::lbl --> RJ[REJECTED]
    AC --- L6(["bloqueada, con motivo"]):::lbl --> BL[BLOCKED]
    BL --- L7(["desbloqueada"]):::lbl --> AC
    PK --- L8(["Cerrar una entidad"]):::lbl --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((Fin))
    class S,E terminal
    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
```

| Estado | Significado | Editable | Establecido por |
| - | - | - | - |
| PENDING\_KYC | Creada o devuelta para su corrección (el motivo está en statusReason). Es posible que aún falten archivos. | Sí | Tú, al crearla. Localpayment Compliance, cuando solicita una corrección. |
| IN\_REVIEW | En revisión por parte de Localpayment. | No. Los datos, documentos, archivos y enlaces UBO están congelados (409 ENTITY\_IN\_REVIEW). | Tú, con Solicitar verificación |
| `ACTIVE` | Aprobada y utilizable por los productos de Localpayment. | Sí | Localpayment Compliance |
| `REJECTED` | La revisión falló. El motivo está en el historial de estados. No se puede volver a enviar. | No | Localpayment Compliance |
| `BLOCKED` | Bloqueada temporalmente. El motivo está en el historial de estados. | No | Localpayment Compliance |
| `CLOSED` | Eliminada lógicamente. Se conserva para auditoría y se puede consultar, pero nunca se puede editar. Final. | No | Tú, con Cerrar una entidad |

«Editable» significa que los datos KYC, los documentos y los archivos aún se pueden modificar. Al editar un documento, sus archivos aprobados vuelven a PENDING. La edición de otros datos de la entidad no modifica una revisión ya registrada.

## Estados de los documentos y las pruebas

Localpayment Compliance establece el estado de cada prueba. El estado de un documento se deriva de sus pruebas y de su vigencia.

| Objeto | Estados | Regla |
| - | - | - |
| Prueba | PENDING, IN\_REVIEW, APPROVED, REJECTED | Establecido por Compliance. Una prueba FRONT, BACK o SELFIE rechazada se reemplaza cargando de nuevo el mismo proofType una vez que la entidad vuelve a PENDING\_KYC. |
| Documento | PENDING, VERIFIED, REJECTED, EXPIRED | VERIFIED cuando todas las pruebas activas están APPROVED. REJECTED cuando alguna prueba activa está REJECTED. EXPIRED cuando expirationDate está en el pasado. De lo contrario, PENDING. |

`documentationStatus` en la entidad resume la cobertura de archivos: `NO_FILES` (ningún documento tiene un archivo), `PARTIAL` (algunos lo tienen) o `COMPLETE` (todos lo tienen). No expresa aprobación.

## Convenciones

| Tema | Convención |
| - | - |
| URL base | Stage [https://api.stage.localpayment.com/api/entity](https://api.stage.localpayment.com/api/entity). Consulta [Claves de API y entornos](https://docs.localpayment.com/es/docs/api-keys-and-environments.md). |
| Autenticación | Token de acceso Bearer ([Obtener token de acceso](https://docs.localpayment.com/es/reference/get-token.md)). Tu cuenta de comerciante se identifica a partir del token. |
| Usuario que actúa | Se obtiene del token de acceso y se almacena para auditoría (uploadedBy, changedBy). No se necesita ningún encabezado adicional. |
| Identificadores | UUID. internalId para entidades, documentId para documentos, id para comprobantes y enlaces UBO. |
| Fechas | YYYY-MM-DD para fechas, ISO 8601 UTC para marcas de tiempo. Países en ISO 3166-1 alpha-3. |
| Concurrencia | Las respuestas de entidades incluyen un encabezado ETag y un campo version. PATCH requiere If-Match. |
| Rastreo | Envía X-Correlation-ID (UUID) e indícalo al soporte. Se devuelve en cada respuesta y error. |
| Errores | application/problem+json con un código de cadena estable. Consulta [Estados de entidad y códigos de error](https://docs.localpayment.com/es/reference/entity-statuses-and-error-codes.md). |
| Notificaciones | No hay webhooks para Entities. No necesitas consultar el estado después de Solicitar verificación; para seguir la revisión, llama a Get KYC Status. |

## Próximos pasos

> [card] [Crear una entidad](https://docs.localpayment.com/es/docs/create-an-entity.md)
>
> Registra a una persona o empresa con su documento principal.

> [card] [Subir documentos y comprobantes](https://docs.localpayment.com/es/docs/upload-documents-and-proofs.md)
>
> Adjunta los archivos que respaldan cada documento.

> [card] [Seguimiento de la revisión y corrección de 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] [Compartir información KYB a través de entidades](https://docs.localpayment.com/es/docs/share-kyb-information-through-entities.md)
>
> Enviar los datos KYB de un beneficiario de una Cuenta Virtual.


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