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

# Campos personalizados

> Almacena los datos adicionales de KYC/KYB acordados con Localpayment en atributos, validados según el esquema de campos personalizados de tu comerciante.

Los campos personalizados permiten que tu cuenta de comerciante almacene datos KYC/KYB que el modelo de entidad estándar no incluye, como la actividad comercial, la fuente de fondos, los volúmenes estimados o los identificadores locales. Localpayment define un esquema para tu comerciante y tú envías los valores en `attributes` cuando creas o actualizas una entidad.

## Requisitos previos

* Un esquema de campos personalizados acordado con tu gestor de cuenta y publicado por Localpayment.
* Un token de acceso de Stage. Consulta [Obtener token de acceso](https://docs.localpayment.com/es/reference/get-token.md).

## Cómo funciona

```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["Su gerente de cuenta<br/>Acuerda los campos: claves, tipos, restricciones"]:::lp --> B["Localpayment<br/>Publica la versión N del esquema"]:::lp
    B --> C["Su backend<br/>GET /api/entity/v1/custom-fields/schema"]
    C --> D["Entities API<br/>200: JSON Schema, o 404 si no hay ninguno publicado"]:::lp
    D --> E["Su backend<br/>POST /api/entity/v1/entities con attributes"]
    E --> F["Entities API<br/>201: customFieldSchemaVersion N"]:::lp
    E --> G["Entities API<br/>400 CUSTOM_FIELDS_INVALID<br/>cuando un valor incumple el esquema"]:::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
```

* **Sin esquema publicado:** `attributes` se acepta tal como se envía, y [Obtener esquema de campos personalizados](https://docs.localpayment.com/es/reference/get-custom-fields-schema.md) devuelve 404 `CUSTOM_FIELD_SCHEMA_NOT_FOUND`.
* **Esquema publicado:** la validación es estricta. Las claves desconocidas, las claves obligatorias ausentes, los tipos, longitudes, patrones y rangos incorrectos se rechazan con 400 `CUSTOM_FIELDS_INVALID`. Cada entidad registra el `customFieldSchemaVersion` con el que fue validada.
* **Un esquema por comerciante** se aplica tanto a `INDIVIDUAL` como a `COMPANY`. Los campos que solo tienen sentido para empresas se definen como opcionales.

## Tipos de campo

| Tipo | Restricciones disponibles |
| - | - |
| `STRING` | minLength, maxLength, pattern (sintaxis RE2) |
| `NUMBER` | min, max |
| `DATE` | min, max (YYYY-MM-DD) |
| `ENUM` | Opciones (obligatorias, valores únicos) |
| `BOOLEAN` | Ninguno |
| OBJECT, LIST | Hijos o elementos anidados. LIST admite minItems y maxItems. |

Las claves están en camelCase y comienzan con una letra minúscula (`^[a-z][a-zA-Z0-9_]{0,63}$`). `attributes` puede pesar hasta 64 KB (413 `PAYLOAD_TOO_LARGE`).

## Lee el esquema

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl https://api.stage.localpayment.com/api/entity/v1/custom-fields/schema \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN"
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "reasonForAccountOpening": {
      "type": "string",
      "title": "Reason for account opening",
      "enum": [
        "receive_payments_for_goods_and_services",
        "payroll",
        "other"
      ]
    },
    "sourceOfFundsAndIncome": {
      "type": "string"
    },
    "numberOfEmployees": {
      "type": "string",
      "enum": [
        "1-10",
        "11-50",
        "51-200",
        "200+"
      ]
    },
    "estimatedAnnualRevenueUsd": {
      "type": "string"
    },
    "estimatedMonthlyVolumeUsd": {
      "type": "string"
    },
    "businessActivityDescription": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "countryTaxResidence": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3
    },
    "socialMedia": {
      "type": "string"
    },
    "emailPixKey": {
      "type": "string"
    },
    "percentageOfOwnership": {
      "type": "string"
    },
    "hasControl": {
      "type": "string"
    },
    "documentCountry": {
      "type": "string"
    },
    "countryOfTaxId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

La respuesta predeterminada es un esquema JSON (2020-12). Agrega `?format=definition` para obtener la lista de campos nativa.

## Enviar los valores

Los valores se envían en `attributes` en [Crear una entidad](https://docs.localpayment.com/es/reference/create-entity.md) y [Actualizar una entidad](https://docs.localpayment.com/es/reference/update-entity.md):

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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"
  }
}
```

Un valor fuera del esquema devuelve 400 `CUSTOM_FIELDS_INVALID`, con una entrada por cada campo incorrecto en `details`:

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

Valida `attributes` contra el esquema de tu lado antes de llamar a la API, y asocia cada entrada de `details` con tu formulario para que el usuario pueda corregir el valor.

## Cambiar el esquema

Localpayment publica los cambios de esquema como una nueva versión. Las entidades existentes conservan su `customFieldSchemaVersion`, y las nuevas escrituras se validan contra la última versión publicada. Pide a tu gestor de cuenta que agregue, flexibilice o elimine campos.

> [!WARNING]
>
> Una vez publicado un esquema, cualquier clave que no esté definida en él será rechazada. Coordina los cambios de esquema antes de enviar nuevos campos desde tu integración.

## Próximos pasos

> [card] [Obtener esquema de campos personalizados](https://docs.localpayment.com/es/reference/get-custom-fields-schema.md)
>
> Formatos de respuesta y códigos de error.

> [card] [Compartir información KYB a través de entidades](https://docs.localpayment.com/es/docs/share-kyb-information-through-entities.md)
>
> Los campos personalizados utilizados para los beneficiarios de la cuenta virtual.


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