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

# Criar uma entidade

> O cadastro de uma pessoa física ou jurídica, fornecendo os dados mínimos de KYC (Conheça Seu Cliente) e o documento principal, é o primeiro passo para a integração de clientes (KYC/KYB).

Este guia orienta você no processo de registro de uma pessoa física e jurídica com a opção [Criar uma Entidade](https://docs.localpayment.com/pt-br/reference/create-entity.md). A entidade é criada sem arquivos. Você os carrega na próxima etapa, [Carregar Documentos e Comprovantes](https://docs.localpayment.com/pt-br/docs/upload-documents-and-proofs.md).

## Pré-requisitos

* Um token de acesso do ambiente Stage. Consulte [Obter token de acesso](https://docs.localpayment.com/pt-br/reference/get-token.md).
* O tipo de entidade: `INDIVIDUAL` para uma pessoa natural, `COMPANY` para uma pessoa jurídica.
* O documento de identificação. Para uma pessoa: o número de identificação fiscal (`CPF`, `CUIT`, `RFC`, `CURP`) ou um documento de identidade (`DNI`, `PASSPORT`, `CC`). Para uma empresa: o número de identificação fiscal (`CNPJ`, `CUIT`, `RFC`, `RUC`, `NIT`). Ele se torna o documento principal.
* Um `externalId` estável: sua própria referência, exclusiva por comerciante.
* Se a Localpayment configurou campos personalizados para o seu comerciante, consulte o esquema. Veja [Campos Personalizados](https://docs.localpayment.com/pt-br/docs/custom-fields.md).

## Quais documentos declarar?

Um documento é uma identificação que contém quantos arquivos você precisar, como a frente, o verso e uma selfie de um documento de identidade. Envie o documento de identificação em `document` ao criar a entidade, ela se torna o documento principal. Declare todos os outros documentos com [Adicionar um Documento](https://docs.localpayment.com/pt-br/reference/add-entity-document.md). O par `type` + `id` deve ser único em seu estabelecimento.

| Tipo | Documento principal | Outros documentos |
| - | - | - |
| `INDIVIDUAL` | Número de identificação fiscal ou documento de identidade (CPF, DNI, PASSPORT). Comprovantes: FRONT, BACK, SELFIE. | PROOF\_OF\_ADDRESS e quaisquer outras evidências (PROOF\_OF\_FUNDS, PAYSLIP, OTHER). |
| `COMPANY` | Número de Identificação Fiscal (CNPJ, CUIT, RFC, RUC, NIT). Comprovante: DOCUMENT. | ARTICLES\_OF\_INCORPORATION, PROOF\_OF\_ADDRESS. Os proprietários são registrados como entidades INDIVIDUAL e vinculados com [Manage UBOs](https://docs.localpayment.com/pt-br/docs/manage-ubos.md). |

A lista completa de valores encontra-se em [Tipos de Documento e Prova](https://docs.localpayment.com/pt-br/reference/entity-document-and-proof-types.md).

## Dados mínimos

| Tipo | Requerido pela API | Altamente recomendado |
| - | - | - |
| `INDIVIDUAL` | externalId, type, name, lastname, document | birthdate, nationality, residenceCountry, email, phone, address |
| `COMPANY` | externalId, type, name, document | incorporationCountry, incorporationDate, legalRepresentativeName, website, email, phone, address |

A ausência de dados KYC obrigatórios retorna o código 422 `INCOMPLETE_KYC_DATA`.

## Criar uma pessoa

```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 \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10" \
  -d '{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "birthdate": "1990-01-15",
    "nationality": "BRA",
    "birthCountry": "BRA",
    "residenceCountry": "BRA",
    "isPep": false,
    "email": "jane.doe@example.com",
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999990001"
    },
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310-100",
      "country": "BRA"
    },
    "document": {
      "type": "CPF",
      "id": "00000000000",
      "issuingCountry": "BRA"
    }
  }'
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INDIVIDUAL",
  "status": "PENDING_KYC",
  "name": "Jane",
  "lastname": "Doe",
  "birthdate": "1990-01-15",
  "gender": null,
  "nationality": "BRA",
  "birthCountry": "BRA",
  "residenceCountry": "BRA",
  "occupation": null,
  "isPep": false,
  "incorporationDate": null,
  "incorporationCountry": null,
  "website": null,
  "legalRepresentativeName": null,
  "email": "jane.doe@example.com",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990001"
  },
  "address": {
    "street": "Rua Exemplo",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "number": "123",
    "comment": null,
    "country": "BRA",
    "line2": null,
    "line3": null
  },
  "attributes": null,
  "documentationStatus": "NO_FILES",
  "document": {
    "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
    "entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "type": "CPF",
    "id": "00000000000",
    "issuingCountry": "BRA",
    "issueDate": null,
    "expirationDate": null,
    "isPrimary": true,
    "status": "PENDING",
    "metadata": null,
    "proofs": [],
    "createdAt": "2024-01-15T17:03:10Z",
    "updatedAt": "2024-01-15T17:03:10Z"
  },
  "documents": [],
  "version": 0,
  "createdAt": "2024-01-15T17:03:10Z",
  "updatedAt": "2024-01-15T17:03:10Z",
  "customFieldSchemaVersion": null
}
```

A resposta é 201 Created com o cabeçalho `ETag: "0"`.

Manter `internalId` (a entidade) e `document.documentId` (o documento principal). Os próximos passos exigem ambos.

## Crie uma empresa

Uma empresa com seu número de identificação fiscal como documento principal, um endereço com linhas adicionais e campos personalizados:

```json 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.",
  "incorporationCountry": "BRA",
  "incorporationDate": "2020-01-15",
  "website": "https://www.example.com",
  "email": "test@example.com",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990000"
  },
  "legalRepresentativeName": "Jane Doe",
  "isPep": false,
  "address": {
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "country": "BRA",
    "line2": "Sala 100",
    "line3": "Torre A"
  },
  "document": {
    "type": "CNPJ",
    "id": "00000000000100",
    "issuingCountry": "BRA"
  },
  "attributes": {
    "reasonForAccountOpening": "receive_payments_for_goods_and_services",
    "sourceOfFundsAndIncome": "sales_of_goods_and_services",
    "numberOfEmployees": "11-50",
    "estimatedAnnualRevenueUsd": "1m_to_10m",
    "estimatedMonthlyVolumeUsd": "50000",
    "businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
    "countryTaxResidence": "BRA",
    "socialMedia": "https://www.linkedin.com/company/example",
    "emailPixKey": "test@example.com"
  }
}
```

## Lide com erros na sua integração.

```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import os
import uuid
import requests

BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]

payload = {
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "document": {"type": "CPF", "id": "00000000000", "issuingCountry": "BRA"},
}

response = requests.post(
    f"{BASE_URL}/v1/entities",
    json=payload,
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Correlation-ID": str(uuid.uuid4()),
    },
    timeout=30,
)

if response.status_code == 201:
    entity = response.json()
    entity_id = entity["internalId"]
    primary_document_id = entity["document"]["documentId"]
else:
    problem = response.json()  # application/problem+json
    code = problem.get("code")
    if code == "DUPLICATE_ENTITY":
        # Already registered: look it up with GET /v1/entities?externalId=...
        pass
    elif code in ("VALIDATION_ERROR", "CUSTOM_FIELDS_INVALID"):
        for detail in problem.get("details", []):
            print(f"{detail['field']}: {detail['issue']}")
    else:
        # Quote the correlation id when you contact support
        print(f"{response.status_code} {code} correlationId={problem.get('correlationId')}")
```

## Erros comuns

| Erro | Causa | Correção |
| - | - | - |
| 400 VALIDATION\_ERROR | Propriedade desconhecida, código de país de duas letras, lista de documents em vez de document, ou nenhum document. | Verifique o campo mencionado em cada entrada de details. Mova os dados extras para attributes. |
| 400 CUSTOM\_FIELDS\_INVALID | attributes não atende ao esquema de campos personalizados. | Leia o esquema e corrija o campo mencionado em details. |
| 409 DUPLICATE\_ENTITY | externalId, ou um tipo de documento + id, já está em uso na sua conta de comerciante. | Reutilize a entidade existente. Encontre-a com a opção [Listar Entidades](https://docs.localpayment.com/pt-br/reference/list-entities.md). |
| 422 INCOMPLETE\_KYC\_DATA | Faltam dados mínimos de KYC (Conheça Seu Cliente). | Adicione name e lastname (pessoa) ou name (empresa). |

Exemplo de erro de validação de campos personalizados:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}
```

> [!WARNING]
>
> Um número de identificação fiscal (`CPF`, `CNPJ`, `CUIT`, `RFC`) é um documento, não um campo da entidade. Envie-o em `document`. Os códigos de país devem ser ISO 3166-1 alfa-3 (`BRA`, não `BR`).

## Próximos passos

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

> [card] [Criar uma referência de entidade](https://docs.localpayment.com/pt-br/reference/create-entity.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.