---
title: 'Campos Personalizados (Metadados)'
description: 'Guarde qualquer informação extra em chave/valor no cliente — além dos campos nativos — e preencha por formulário de captura, pela tela do cliente ou pela API.'
---

# Campos Personalizados (Metadados)

Os clientes da Guper têm um conjunto de **campos nativos** (nome, e-mail, telefone,
documento, aniversário, gênero…). Os **campos personalizados** deixam você guardar
*qualquer outra coisa* que precise sobre um cliente como **metadados** livres em
chave/valor — por exemplo `shirt_size`, `loja_favorita` ou `aniversario_filho`.

Cada cliente tem **um valor por chave**. Os valores são texto; um número ou uma data
é reconhecido automaticamente (útil para relatórios futuros).

## Onde os campos personalizados aparecem

Os metadados de cada cliente aparecem na página **Customer 360**, no card
**Metadados**. É ali que você os consulta e — com permissão de edição — os altera
manualmente.

## Três formas de preencher

### 1. Capturar com um formulário de Data Capture

Ao montar um formulário de **Data Capture** (Configurações → Captura de Dados →
Formulários), cada campo tem um switch **"Salvar como metadado"**:

1. Adicione um campo (ex.: nome `shirt_size`, rótulo *Tamanho da camisa*).
2. Ligue **Salvar como metadado**.
3. Opcionalmente defina a **Chave do metadado** — a chave de armazenamento. Se
   deixar em branco, o nome do campo é usado. Ela é normalizada automaticamente
   para minúsculas com underscores (ex.: *Tamanho da Camisa* → `tamanho_da_camisa`).
4. Salve o formulário.

A partir daí, toda submissão desse formulário grava o valor capturado nos metadados
do cliente.

> O **campo identificador** do formulário (o que identifica o cliente, geralmente
> e-mail ou telefone) **não** pode virar metadado — ele sempre mapeia para o campo
> nativo.

### 2. Editar na tela do Customer 360

Abra um cliente, encontre o card **Metadados** e clique no **lápis**. Você pode:

- editar o valor de uma chave existente,
- **Adicionar** uma nova linha chave/valor,
- **remover** uma linha (apaga aquele valor para este cliente),

e clicar em **Salvar**. Chaves novas que você digitar aqui são criadas
automaticamente.

### 3. Gravar pela API

Desenvolvedores podem ler e gravar metadados direto:

- `GET /api/register/customer/{id}/metadata` — o mapa de metadados do cliente.
- `PUT /api/register/customer/{id}/metadata` — upsert de um objeto
  `{ "chave": "valor" }` (envie `null` ou `""` para apagar uma chave).

O mapa também vem embutido como `metadata` no `GET /api/register/customer/{id}`.
Veja a referência da API para detalhes.

## Gerenciando suas chaves (Configurações → Geral → Campos personalizados)

As chaves são **criadas automaticamente** na primeira vez que um valor é gravado, então
normalmente não há nada a configurar. A tela **Configurações → Geral → Campos personalizados**
lista todas as chaves que sua organização usa e permite:

- dar um **rótulo amigável** a uma chave (clareza interna),
- **excluir** uma chave — o que também **remove aquele valor de todos os clientes**.

> Excluir uma chave é permanente e afeta todos os clientes. Use apenas para limpar
> chaves criadas por engano.

## Bom saber

- **Nomes de chave** são normalizados para `a–z`, `0–9` e `_` (máx. 64 caracteres).
  *Tamanho da Camisa* e `tamanho_da_camisa` são a mesma chave.
- Uma chave **não pode reutilizar o nome de um campo nativo** (como `email` ou
  `gender`).
- **Um valor por chave** por cliente. Para manter histórico ou múltiplos valores,
  modele-os como chaves separadas.
- **Segmentação:** filtrar audiências por campos personalizados ainda não está
  disponível — está planejado para uma versão futura.
