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

# Visão geral das entidades

> Cadastre as pessoas e empresas com quem você trabalha, anexe os comprovantes KYC/KYB delas e acompanhe a análise realizada pela Localpayment.

Entidades permite que você registre as pessoas (`INDIVIDUAL`) e empresas (`COMPANY`) com quem você trabalha, declare a identidade deles e os documentos comprobatórios, faça o upload dos arquivos que os comprovem e acompanhe o resultado da análise KYC/KYB realizada pela Localpayment. A entidade é compartilhada entre recebimentos e pagamentos: a mesma entidade pode ser usada em todos os produtos da Localpayment.

Este guia destina-se a desenvolvedores que integram clientes, beneficiários ou parceiros comerciais por meio da API.

> [!NOTE]
>
> Entidades armazena dados de identidade e comprovantes e registra o resultado da análise. Você solicita a análise com Solicitar verificação, mas nunca a aprova: quem decide é a Conformidade da Localpayment. Entidades não valida números de documentos em registros governamentais e não mantém saldos.

## Objetos

| Objeto | O que é isso? | Identificador |
| - | - | - |
| Entidade | Uma pessoa (INDIVIDUAL) ou uma empresa (COMPANY) associada à sua conta comercial. Contém dados KYC, endereço, atributos personalizados e seus documentos. | internalId (UUID) e seu externalId |
| Documento | Um documento declarado como dados: tipo, número, país emissor e validade. Contém quantos arquivos forem necessários. Exatamente um documento por entidade é primário (o documento de identificação, geralmente o número de identificação fiscal ou carteira de identidade). | documentId |
| Prova | Um arquivo que suporta um documento: FRONT, BACK, SELFIE, DOCUMENT ou OTHER. Até 10 MB. Cada comprovante tem seu próprio status de análise. | id (proofId) |
| Link UBO | A relação entre uma COMPANY e um INDIVIDUAL que a possui ou controla, com ownershipPercentage e controlRole. | id (uboId) |
| Esquema de campos personalizados | Os campos adicionais configurados pela Localpayment para o seu comerciante. Os valores são transmitidos em attributes e validados em relação a eles. | 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["Sua conta de lojista"] --> S["Schema de campos personalizados"]
    M --> P["Entidade: INDIVIDUAL"]
    M --> C["Entidade: COMPANY"]
    P --> D1["Documento: CPF (principal)<br/>provas: FRONT, BACK, SELFIE"]
    P --> D2["Documento: PROOF_OF_ADDRESS<br/>prova: DOCUMENT"]
    C --> D3["Documento: CNPJ (principal)<br/>prova: DOCUMENT"]
    C --> D4["Documento: ARTICLES_OF_INCORPORATION<br/>prova: 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
```

## Como funciona

Sua integração tem cinco etapas. A última, `verify`, informa à Localpayment que o upload foi concluído e inicia a análise. Com `verify`, a sua parte do upload termina: você não precisa consultar o status da entidade depois disso. Você só volta a agir sobre a entidade se a Localpayment solicitar uma correção.

```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 a entidade com o documento principal<br/>POST /api/entity/v1/entities"] --> B["2. Adicione os demais documentos<br/>POST /api/entity/v1/entities/{entityId}/documents"]
    B --> C["3. Envie os arquivos de cada documento<br/>POST /api/entity/v1/documents/{docId}/proofs"]
    C --> Q{"É uma empresa?"}
    Q --- L1(["sim"]):::lbl --> D["4. Vincule os sócios<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    Q --- L2(["não"]):::lbl --> V
    D --> V["5. Solicite a verificação<br/>POST /api/entity/v1/entities/{entityId}/verify<br/>na empresa, quando tudo estiver carregado"]
    V --> E[/"A Localpayment analisa a entidade"/]:::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
```

| Etapa | Endpoint | Resultado |
| - | - | - |
| 1 | [Criar uma entidade](https://docs.localpayment.com/pt-br/reference/create-entity.md) | Entidade em PENDING\_KYC com seu documento principal. A resposta contém o documentId para o qual você envia os arquivos. |
| 2 | [Adicionar um documento](https://docs.localpayment.com/pt-br/reference/add-entity-document.md) | Os demais documentos declarados foram: documento de identidade, comprovante de endereço, contrato social e procuração. |
| 3 | [Enviar comprovante](https://docs.localpayment.com/pt-br/reference/upload-proof.md) | Arquivos anexados a cada documento, quantos forem necessários. O documentationStatus muda de NO\_FILES para PARTIAL e COMPLETE. |
| 4 | [Vincule um UBO](https://docs.localpayment.com/pt-br/reference/link-ubo.md) | Apenas para empresas. Crie cada proprietário primeiro como um INDIVIDUAL (passos 1 a 3) e, em seguida, vincule-o à sua porcentagem e função de controle. A empresa mostra uboCount e uboRequirementMet. |
| 5 | [Solicitar verificação](https://docs.localpayment.com/pt-br/reference/request-entity-verification.md) | 202 Accepted. A entidade passa para IN\_REVIEW e fica bloqueada até que a Localpayment a resolva. |

Se a Localpayment precisar de uma correção, ela indica o que deve ser corrigido: cada arquivo rejeitado contém seu `verificationReason`. Envie uma substituição com o mesmo `proofType` ou corrija os dados e, em seguida, chame [Solicitar verificação](https://docs.localpayment.com/pt-br/reference/request-entity-verification.md) novamente. Consulte [Acompanhe a revisão e corrija as rejeições](https://docs.localpayment.com/pt-br/docs/track-review-and-fix-rejections.md).

## Status das 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((Início)) --- L1(["Criar uma entidade"]):::lbl --> PK[PENDING_KYC]
    PK --- L2(["Solicitar verificação, por você"]):::lbl --> IR[IN_REVIEW]
    IR --- L3(["correção solicitada, com motivo"]):::lbl --> PK
    IR --- L4(["aprovada"]):::lbl --> AC[ACTIVE]
    IR --- L5(["rejeitada, com motivo"]):::lbl --> RJ[REJECTED]
    AC --- L6(["bloqueada, com motivo"]):::lbl --> BL[BLOCKED]
    BL --- L7(["desbloqueada"]):::lbl --> AC
    PK --- L8(["Encerrar uma entidade"]):::lbl --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((Fim))
    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
```

| Status | Significado | Editável | Definido por |
| - | - | - | - |
| PENDING\_KYC | Criado ou devolvido para correção (o motivo está em statusReason). Arquivos ainda podem estar faltando. | Sim | Você, na criação. Conformidade da Localpayment, quando solicita uma correção. |
| IN\_REVIEW | Em análise pela Localpayment. | Não. Dados, documentos, arquivos e links UBO ficam congelados (409 ENTITY\_IN\_REVIEW). | Você, com Solicitar verificação |
| `ACTIVE` | Aprovado e utilizável pelos produtos Localpayment. | Sim | Conformidade da Localpayment |
| `REJECTED` | A revisão falhou. O motivo está no histórico de status. Não é possível reenviar. | Não | Conformidade da Localpayment |
| `BLOCKED` | Temporariamente bloqueado. O motivo está no histórico de status. | Não | Conformidade da Localpayment |
| `CLOSED` | Excluído logicamente. Mantido para fins de auditoria e leitura, mas nunca editável. Final. | Não | Você, com Fechar uma entidade |

"Editável" significa que os dados, documentos e arquivos KYC ainda podem ser alterados. Editar um documento redefine seus arquivos aprovados para PENDING. Editar outros dados da entidade não altera uma revisão já registrada.

## Status dos documentos e comprovantes

O Localpayment Compliance define o status de cada comprovante. O status de um documento é derivado de seus comprovantes e de sua validade.

| Objeto | Status | Regra |
| - | - | - |
| Prova | PENDING, IN\_REVIEW, APPROVED, REJECTED | Definido pela Conformidade. Um FRONT, BACK ou SELFIE rejeitado é substituído pelo envio do mesmo proofType novamente, assim que a entidade retornar ao status PENDING\_KYC. |
| Documento | PENDING, VERIFIED, REJECTED, EXPIRED | VERIFIED quando todos os comprovantes ativos forem APPROVED. REJECTED quando qualquer comprovante ativo for REJECTED. EXPIRED quando a expirationDate já tiver passado. Caso contrário, PENDING. |

`documentationStatus` na entidade resume a cobertura de arquivos: `NO_FILES` (nenhum documento possui arquivo), `PARTIAL` (alguns possuem) ou `COMPLETE` (todos possuem). Não expressa aprovação.

## Convenções

| Tópico | Convenção |
| - | - |
| URL base | Stage [https://api.stage.localpayment.com/api/entity](https://api.stage.localpayment.com/api/entity). Consulte as [chaves e ambientes da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md). |
| Autenticação | Token de acesso do portador ([Obter Token de Acesso](https://docs.localpayment.com/pt-br/reference/get-token.md)). Sua conta comercial é resolvida a partir do token. |
| Usuário em exercício | Extraído do token de acesso e armazenado para auditoria (uploadedBy, changedBy). Nenhum cabeçalho adicional é necessário. |
| Identificadores | UUIDs. internalId para entidades, documentId para documentos, id para comprovantes e links UBO. |
| Datas | Formato AAAA-MM-DD para datas, ISO 8601 UTC para registros de data e hora. Países em ISO 3166-1 alfa-3. |
| Concorrência | As respostas das entidades contêm um cabeçalho ETag e um campo de versão. O método PATCH requer uma correspondência condicional (If-Match). |
| Rastreamento | Envie o X-Correlation-ID (UUID) e cite-o para o suporte. Ele é exibido em todas as respostas e erros. |
| Erros | application/problem+json com um código de string estável. Consulte [Status de Entidade e Códigos de Erro](https://docs.localpayment.com/pt-br/reference/entity-statuses-and-error-codes.md). |
| Notificações | Não há webhooks para Entidades. Você não precisa consultar o status após Solicitar verificação; para acompanhar a análise, chame Get KYC Status. |

## Próximos passos

> [card] [Criar uma entidade](https://docs.localpayment.com/pt-br/docs/create-an-entity.md)
>
> Cadastre uma pessoa física ou jurídica com seu documento principal.

> [card] [Carregar documentos e comprovantes](https://docs.localpayment.com/pt-br/docs/upload-documents-and-proofs.md)
>
> Anexe os arquivos que comprovam cada documento.

> [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 análise e corrija o que a Localpayment solicitar.

> [card] [Compartilhar informações KYB por meio de entidades](https://docs.localpayment.com/pt-br/docs/share-kyb-information-through-entities.md)
>
> Enviar os dados KYB de um beneficiário de Conta Virtual.


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