> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bukiopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar Campo Personalizado

> Cria um campo que o cliente preenche no checkout, como o Player ID de uma recarga, e vincula a produtos ou categorias.

Cria um campo que o cliente preenche antes de pagar, por exemplo o **Player ID** de uma recarga de Free Fire. O campo aparece no checkout da loja e no carrinho do bot do Discord, e o valor fica gravado no pedido.

**Método:** `POST /api/v1/stores/me/custom-fields`

**Autenticação:** Obrigatória. Inclua o header `Authorization: Bearer sk_live_sua_api_key`. A chave precisa ter a permissão **Tudo** (`*`).

<Tip>
  O campo costuma ser criado uma vez só. Se preferir, crie pelo painel, em **Configurações › Visão geral**, no card **Campos extras**, e use a API só para listar os campos e enviar os valores no pedido.
</Tip>

## Parâmetros do corpo

<ParamField body="label" type="string" required>
  Nome do campo exibido ao cliente, até 60 caracteres. Exemplo: `Player ID`.
</ParamField>

<ParamField body="type" type="string" default="TEXT">
  `TEXT`, `NUMBER`, `EMAIL` ou `ROBLOX` (nome de usuário do Roblox).
</ParamField>

<ParamField body="required" type="boolean" default="false">
  Com `true`, o pedido não é criado sem o valor do campo.
</ParamField>

<ParamField body="products" type="string[]">
  UUIDs dos produtos em que o campo aparece.
</ParamField>

<ParamField body="categories" type="string[]">
  UUIDs das categorias: o campo aparece em todos os produtos delas.
</ParamField>

<ParamField body="allProducts" type="boolean" default="false">
  Com `true`, o campo aparece em todos os produtos da loja.
</ParamField>

<ParamField body="placeholder" type="string">
  Texto de exemplo dentro do campo, até 120 caracteres.
</ParamField>

<ParamField body="min" type="number">
  Mínimo aceito no formulário da loja (tamanho do texto ou valor do número).
</ParamField>

<ParamField body="max" type="number">
  Máximo aceito no formulário da loja. Não pode ser menor que `min`.
</ParamField>

<ParamField body="position" type="number" default="0">
  Ordem do campo no formulário, do menor para o maior.
</ParamField>

<Note>
  Informe ao menos um entre `products`, `categories` ou `allProducts: true`. Sem nenhum deles, o campo não aparece em produto nenhum.
</Note>

## Exemplo de requisição

Campo **Player ID** obrigatório em um produto de recarga:

```bash theme={null}
curl -X POST 'https://api.bukiopay.com/api/v1/stores/me/custom-fields' \
  --header 'Authorization: Bearer sk_live_sua_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "Player ID",
    "type": "NUMBER",
    "placeholder": "Seu ID no Free Fire",
    "required": true,
    "products": ["c3b4168f-d732-44ed-8c67-6080cec06b09"]
  }'
```

## Resposta

Status `201 Created`.

```json theme={null}
{
  "customField": {
    "id": "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b",
    "label": "Player ID",
    "type": "NUMBER",
    "placeholder": "Seu ID no Free Fire",
    "required": true,
    "allProducts": false,
    "products": ["c3b4168f-d732-44ed-8c67-6080cec06b09"],
    "categories": [],
    "min": null,
    "max": null,
    "position": 0
  }
}
```

Guarde o `id`: é a chave do valor que o cliente informa em [Criar Pedido](/api-reference/orders/create).

## Enviar o valor no pedido

Em `POST /api/v1/orders`, envie os valores em `customFields`, com o `id` do campo como chave:

```json theme={null}
{
  "customerName": "Maria Silva",
  "customerEmail": "maria@exemplo.com",
  "paymentMethod": "PIX",
  "items": [{ "productId": "c3b4168f-d732-44ed-8c67-6080cec06b09", "quantity": 1 }],
  "customFields": {
    "6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b": "123456789"
  }
}
```

Sem um campo obrigatório do produto, a API responde `400` com a mensagem `O campo "Player ID" é obrigatório.` e o pedido não é criado. O valor fica gravado no pedido e aparece no painel e nos detalhes da venda.

## Erros comuns

| Status | Mensagem | Causa |
| - | - | - |
| `400` | Informe o nome do campo (label). | `label` ausente ou vazio. |
| `400` | Tipo inválido. Use: TEXT, NUMBER, EMAIL, ROBLOX. | `type` fora da lista. |
| `400` | O valor máximo não pode ser menor que o mínimo. | `max` menor que `min`. |
| `403` | Esta chave não pode usar esta rota... | A chave não tem a permissão **Tudo**. |


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