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

# Crear una entidad

> Registrar a una persona o empresa con sus datos KYC mínimos y su documento principal, el primer paso de un proceso de incorporación KYC/KYB.

Esta guía te muestra cómo registrar una persona y una empresa con [Crear una entidad](https://docs.localpayment.com/es/reference/create-entity.md). La entidad se crea sin archivos. Los subirás en el siguiente paso, [Subir documentos y comprobantes](https://docs.localpayment.com/es/docs/upload-documents-and-proofs.md).

## Requisitos previos

* Un token de acceso de Stage. Consulta [Obtener token de acceso](https://docs.localpayment.com/es/reference/get-token.md).
* El tipo de entidad: `INDIVIDUAL` para una persona natural, `COMPANY` para una entidad legal.
* El documento de identificación. Para una persona: el identificador fiscal (`CPF`, `CUIT`, `RFC`, `CURP`) o un documento de identidad (`DNI`, `PASSPORT`, `CC`). Para una empresa: el número de identificación fiscal (`CNPJ`, `CUIT`, `RFC`, `RUC`, `NIT`). Se convierte en el documento principal.
* Un `externalId` estable: tu propia referencia, única por comerciante.
* Si Localpayment configuró campos personalizados para tu comerciante, consulta el esquema. Consulta [Campos personalizados](https://docs.localpayment.com/es/docs/custom-fields.md).

## ¿Qué documentos declarar?

Un documento es un identificador que contiene tantos archivos como necesites, como el anverso, el reverso y la selfie de un documento de identidad. Envía el documento de identificación en `document` cuando crees la entidad: se convierte en el documento principal. Declara todos los demás documentos con [Agregar un documento](https://docs.localpayment.com/es/reference/add-entity-document.md). El par `type` + `id` debe ser único en tu comerciante.

| Tipo | Documento principal | Otros documentos |
| - | - | - |
| `INDIVIDUAL` | Identificación fiscal o documento de identidad (CPF, DNI, PASSPORT). Comprobantes: FRONT, BACK, SELFIE. | PROOF\_OF\_ADDRESS y cualquier otra evidencia (PROOF\_OF\_FUNDS, PAYSLIP, OTHER). |
| `COMPANY` | Identificación fiscal (CNPJ, CUIT, RFC, RUC, NIT). Comprobante: DOCUMENT. | ARTICLES\_OF\_INCORPORATION, PROOF\_OF\_ADDRESS. Los propietarios se registran como entidades INDIVIDUAL y se vinculan con [Gestionar UBO](https://docs.localpayment.com/es/docs/manage-ubos.md). |

La lista completa de valores se encuentra en [Tipos de documentos y pruebas](https://docs.localpayment.com/es/reference/entity-document-and-proof-types.md).

## Datos mínimos

| Tipo | Requerido por la API | Muy recomendable |
| - | - | - |
| `INDIVIDUAL` | externalId, type, name, lastname, document | birthdate, nationality, residenceCountry, email, phone, address |
| `COMPANY` | externalId, type, name, document | incorporationCountry, incorporationDate, legalRepresentativeName, website, email, phone, address |

Si faltan los datos KYC obligatorios, se devuelve el código 422 `INCOMPLETE_KYC_DATA`.

## Crea una persona

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

La respuesta es 201 Creado con el encabezado `ETag: "0"`.

Mantener `internalId` (la entidad) y `document.documentId` (el documento principal). Los siguientes pasos necesitan ambos.

## Crear una empresa

Una empresa con su número de identificación fiscal como documento principal, una dirección con líneas adicionales y 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"
  }
}
```

## Gestiona los errores en tu integración

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

## Errores comunes

| Error | Causa | Solución |
| - | - | - |
| 400 VALIDATION\_ERROR | Propiedad desconocida, código de país de dos letras, una lista de documentos en lugar de un documento o ningún documento. | Verifica el campo especificado en cada entrada de detalles. Mueve los datos adicionales a los atributos. |
| 400 CUSTOM\_FIELDS\_INVALID | Los atributos no cumplen con el esquema de campos personalizados. | Lee el esquema y corrige el campo mencionado en los detalles. |
| 409 DUPLICATE\_ENTITY | externalId, o un tipo de documento + id, ya se utiliza en tu comercio. | Reutiliza la entidad existente. Búscala con [Listar entidades](https://docs.localpayment.com/es/reference/list-entities.md). |
| 422 INCOMPLETE\_KYC\_DATA | Faltan datos mínimos de KYC. | Indica el nombre y apellido (persona) o el nombre (empresa). |

Ejemplo de error de validación 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]
>
> Un número de identificación fiscal (`CPF`, `CNPJ`, `CUIT`, `RFC`) es un documento, no un campo de la entidad. Envíalo en `document`. Los códigos de país deben ser ISO 3166-1 alfa-3 (`BRA`, no `BR`).

## Próximos pasos

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

> [card] [Crear una referencia de entidad](https://docs.localpayment.com/es/reference/create-entity.md)
>
> Todos los campos de solicitud, campos de respuesta y códigos de error.


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