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

> Armazene os dados adicionais de KYC/KYB acordados com a Localpayment em atributos, validados em relação ao esquema de campos personalizados do seu comerciante.

Os campos personalizados permitem que sua conta de comerciante armazene dados de KYC/KYB que o modelo de entidade padrão não inclui, como atividade comercial, origem dos fundos, volumes estimados ou identificadores locais. A Localpayment define um esquema para o seu comerciante, e você envia os valores em `attributes` ao criar ou atualizar uma entidade.

## Pré-requisitos

* Um esquema de campos personalizados acordado com o seu gestor de conta e publicado pela Localpayment.
* Um token de acesso do ambiente Stage. Consulte [Obter token de acesso](https://docs.localpayment.com/pt-br/reference/get-token.md).

## Como 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["Seu gerente de conta<br/>Acorda os campos: chaves, tipos, restrições"]:::lp --> B["Localpayment<br/>Publica a versão N do schema"]:::lp
    B --> C["Seu backend<br/>GET /api/entity/v1/custom-fields/schema"]
    C --> D["Entities API<br/>200: JSON Schema, ou 404 se nenhum for publicado"]:::lp
    D --> E["Seu backend<br/>POST /api/entity/v1/entities com attributes"]
    E --> F["Entities API<br/>201: customFieldSchemaVersion N"]:::lp
    E --> G["Entities API<br/>400 CUSTOM_FIELDS_INVALID<br/>quando um valor viola o schema"]:::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
```

* **Nenhum esquema publicado:** `attributes` é aceito como enviado, e [Obter esquema de campos personalizados](https://docs.localpayment.com/pt-br/reference/get-custom-fields-schema.md) retorna 404 `CUSTOM_FIELD_SCHEMA_NOT_FOUND`.
* **Esquema publicado:** a validação é estrita. Chaves desconhecidas, chaves obrigatórias ausentes, tipos, comprimentos, padrões e intervalos incorretos são rejeitados com 400 `CUSTOM_FIELDS_INVALID`. Cada entidade registra o `customFieldSchemaVersion` com o qual foi validada.
* **Um esquema por comerciante** se aplica tanto a `INDIVIDUAL` quanto a `COMPANY`. Os campos que só fazem sentido para empresas são definidos como opcionais.

## Tipos de campo

| Tipo | Restrições disponíveis |
| - | - |
| `STRING` | minLength, maxLength, pattern (sintaxe RE2) |
| `NUMBER` | min, max |
| `DATE` | min, max (YYYY-MM-DD) |
| `ENUM` | options (obrigatórias, valores únicos) |
| `BOOLEAN` | Nenhum |
| OBJECT, LIST | Filhos ou itens aninhados. LIST suporta minItems e maxItems. |

As chaves usam camelCase e começam com uma letra minúscula (`^[a-z][a-zA-Z0-9_]{0,63}$`). `attributes` pode ter até 64 KB (413 `PAYLOAD_TOO_LARGE`).

## Leia o 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
}
```

A resposta padrão é um JSON Schema (2020-12). Adicione `?format=definition` para obter a lista de campos nativa.

## Envie os valores

Os valores trafegam em `attributes` em [Criar uma entidade](https://docs.localpayment.com/pt-br/reference/create-entity.md) e [Atualizar uma entidade](https://docs.localpayment.com/pt-br/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"
  }
}
```

Um valor fora do esquema retorna 400 `CUSTOM_FIELDS_INVALID`, com uma entrada por campo inválido em `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"
    }
  ]
}
```

Valide `attributes` em relação ao esquema do seu lado antes de chamar a API e associe cada entrada de `details` de volta ao seu formulário para que o usuário possa corrigir o valor.

## Alterar o esquema

A Localpayment publica as alterações de esquema como uma nova versão. As entidades existentes mantêm seu `customFieldSchemaVersion`, e as novas gravações são validadas em relação à versão publicada mais recente. Peça ao seu gestor de conta para adicionar, flexibilizar ou remover campos.

> [!WARNING]
>
> Após a publicação de um esquema, qualquer chave não definida nele será rejeitada. Coordene as alterações de esquema antes de enviar novos campos da sua integração.

## Próximos passos

> [card] [Obter esquema de campos personalizados](https://docs.localpayment.com/pt-br/reference/get-custom-fields-schema.md)
>
> Formatos de resposta e códigos de erro.

> [card] [Compartilhar informações KYB por meio de entidades](https://docs.localpayment.com/pt-br/docs/share-kyb-information-through-entities.md)
>
> Os campos personalizados usados para os beneficiários da Conta Virtual.


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