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

# Compartilhar informações KYB por meio de entidades

> Envie as informações KYB de um subcomerciante por meio da API de Entidades: a empresa, seus proprietários, seu representante legal e seus documentos.

Este guia mostra, chamada por chamada e com solicitações e respostas, como enviar as informações listadas em [Requisitos KYB para Beneficiários de Contas Virtuais](https://docs.localpayment.com/pt-br/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md) usando a API de Entidades. O lugar de cada item em Entities está na coluna How to send it dessa página. Em resumo: a empresa é uma entidade do tipo `COMPANY`, cada pessoa é uma entidade do tipo `INDIVIDUAL` (os proprietários são vinculados à empresa como UBOs), e cada documento é um documento declarado com seus arquivos. Os exemplos usam uma empresa fictícia registrada no Brasil.

## Pré-requisitos

* Este fluxo se aplica a Contas Virtuais no Brasil.
* Um token de acesso do ambiente Stage. Consulte [Obter Token de Acesso](https://docs.localpayment.com/pt-br/reference/get-token.md).
* Um esquema de campos personalizados publicado para o seu comerciante com os campos KYB. Consulte [Campos Personalizados](https://docs.localpayment.com/pt-br/docs/custom-fields.md).
* As informações e documentos da empresa, seus proprietários e seu representante legal. Consulte os [Requisitos KYB para Beneficiários de Contas Virtuais](https://docs.localpayment.com/pt-br/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md).

## 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. Leia o seu schema de campos personalizados<br/>GET /api/entity/v1/custom-fields/schema"]:::lp --> B["2. Crie a empresa<br/>POST /api/entity/v1/entities, type COMPANY<br/>ID fiscal como documento principal, perfil do negócio em attributes"]
    B --> DH["3. Documentos da empresa<br/>um por documento, cada um com seus arquivos"]:::lp
    DH --> D1["ARTICLES_OF_INCORPORATION<br/>mais organograma societário, quando necessário"]
    DH --> D2["PROOF_OF_FUNDS<br/>um arquivo por documento"]
    DH --> D3["OTHER<br/>prova de titularidade, B2C"]
    D1 & D2 & D3 --> PH["4 e 5. Pessoas<br/>um INDIVIDUAL por sócio e para o representante legal<br/>cada um com seu documento de identidade"]:::lp
    PH --> P1["Sócio 1<br/>documento de identidade<br/>FRONT, BACK"]
    PH --> P2["Sócio 2, 3 e assim por diante<br/>mesmas etapas"]
    PH --> P3["Representante legal<br/>mesmas etapas"]
    P1 --> L1["6. Vincule à empresa, sócio 1<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P2 --> L2["6. Vincule à empresa, cada outro sócio<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P3 --> L3["6. Vincule à 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 o envio foi concluído<br/>POST /api/entity/v1/entities/{companyId}/verify"]
    V --> G[/"A Localpayment analisa<br/>a empresa e cada pessoa"/]:::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.** Crie-o como um `INDIVIDUAL` (seu documento de identidade pode ser o documento principal) e vincule-o à empresa com [Link a UBO](https://docs.localpayment.com/pt-br/reference/link-ubo.md): `ownershipPercentage: 0` e `controlRole: LEGAL_REPRESENTATIVE`. Se o representante legal também for proprietário, vincule-o uma única vez, com a sua porcentagem e `controlRole: LEGAL_REPRESENTATIVE`.

## Passo a passo

Execute as chamadas abaixo nesta ordem. Guarde cada `internalId` e `documentId` retornado pela API. Os exemplos enviam apenas o mínimo.

### Leia o esquema dos seus campos personalizados.

`GET /api/entity/v1/custom-fields/schema` retorna os atributos que a sua conta aceita. Trecho com o perfil do negócio:

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

### Criar a empresa

`POST /api/entity/v1/entities`. O número de identificação fiscal é o documento principal, e o perfil do negócio vai em `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"
}
```

A resposta é 201 Created (trecho). O documento principal retorna com seu `documentId` e sem arquivos, o que é esperado: ele não precisa de nenhum.

### Declare os documentos da empresa e faça o upload dos arquivos.

Declare cada documento com `POST /api/entity/v1/entities/{companyId}/documents`. O documento de constituição da empresa traz o número de registro em `id` (no Brasil, o CNPJ):

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

Em seguida, envie um `POST /api/entity/v1/documents/{documentId}/proofs` por arquivo, com `proofType=DOCUMENT` e o arquivo. Resposta (trecho):

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

Declare e faça o upload dos documentos de origem dos fundos e, para `B2C`, do comprovante de titularidade da mesma forma:

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

### Crie cada pessoa

Um `INDIVIDUAL` por proprietário e para o representante legal, com `POST /api/entity/v1/entities`. O documento de identidade pode ser o 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
  }
}
```

A resposta é 201 Created (trecho).

### Faça o upload do documento de identidade de cada pessoa.

Frente e verso vão para o mesmo documento: `POST /api/entity/v1/documents/{documentId}/proofs` com `proofType=FRONT`, e depois com `proofType=BACK` (passaporte: somente `FRONT`). Trecho de `GET /api/entity/v1/documents/{documentId}/proofs` após os dois uploads:

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

### Vincule cada pessoa à empresa

Um `POST /api/entity/v1/entities/{companyId}/ubos` por pessoa. Jane Doe detém 60% e também é a 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 detém 40%, com o cargo em letras maiú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"
    }
  ]
}
```

Guarde o `internalId` da empresa: ele identifica o beneficiário na Localpayment.

### Informe à Localpayment que o upload foi concluído.

Quando a empresa, seus documentos e todas as pessoas estiverem carregados e vinculados, chame `POST /api/entity/v1/entities/{companyId}/verify` na empresa ([Solicitar verificação](https://docs.localpayment.com/pt-br/reference/request-entity-verification.md)). Isso informa à Localpayment que o upload da documentação foi concluído. A resposta é `202 Accepted` (trecho):

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

Enquanto a empresa está `IN_REVIEW`, ela fica bloqueada (409 `ENTITY_IN_REVIEW`). Com `verify`, a sua parte do upload termina: você não precisa consultar o status da entidade depois.

## Lista de verificação

* Todos os documentos que você declarou (constituição da empresa, comprovante de origem dos fundos, documentos de identidade) possuem seus respectivos arquivos. O documento principal de identificação fiscal não precisa de arquivo.
* Cada proprietário está vinculado à empresa com seu `ownershipPercentage`, e o representante legal com `controlRole: LEGAL_REPRESENTATIVE`.
* `attributes.businessProfile` está definido na empresa.
* Depois que tudo foi carregado, você chamou `verify` na empresa.
* Os números de identificação fiscal contêm apenas dígitos, e os nomes correspondem exatamente aos documentos.
* Todos os arquivos estão em formato PDF, PNG, JPG ou JPEG e têm menos de 10 MB.

> [!NOTE]
>
> Após a conclusão da lista de verificação, a Localpayment analisa a empresa e cada pessoa, e informa se algo precisa ser corrigido. Consulte [Acompanhar a Análise e Corrigir Rejeições](https://docs.localpayment.com/pt-br/docs/track-review-and-fix-rejections.md).

## 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)
>
> Siga as instruções da revisão e corrija o que a Localpayment solicitar.

> [card] [Gerenciar UBOs](https://docs.localpayment.com/pt-br/docs/manage-ubos.md)
>
> Atualize ou finalize os links do proprietário.


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