Campos

Cadastre os campos de um tipo de evento para definir o contrato de dados aceito em POST /events. Os campos determinam o que a plataforma valida no envio, o que ela ignora e o que fica disponível para métricas e monitoramentos.

Configurações de um campo

Ao cadastrar um campo no painel de administração, você define:

Configuração	O que define
ID do campo	identificador usado no payload da API
Nome e descrição	rótulos exibidos no painel
Tipo de dado	formato esperado para o valor
Tipo de propriedade	como o campo é tratado na modelagem
Obrigatoriedade	se o campo precisa estar presente em todo evento
Herança	se o campo é herdado por envios posteriores com o mesmo `id`
Exibição	como o valor é apresentado no painel
Status	se o campo está ativo ou inativo

O formulário agrupa essas configurações em Comportamento (obrigatoriedade, sensibilidade, herança e status), Formato (precisão, exibição e limites de tamanho) e Permanência.

Tipos de dado

Um campo assume um destes tipos de dado, escolhido na criação:

Tipo de dado	O que armazena	Tipo de propriedade
Texto	texto livre, com tamanho máximo configurável	dimensão ou medição
Lista	um valor entre os itens cadastrados	dimensão ou medição
Número inteiro	número sem casas decimais	medição
Número decimal	número com precisão e escala fixas, indicado para valores monetários	medição
Número de ponto flutuante	número fracionário sem precisão fixa, como um score ou uma taxa	medição
Booleano	verdadeiro ou falso	medição
Data e hora	instante no formato ISO 8601, comparável por período	medição

Observações importantes

Campo de texto tem Tamanho máximo em bytes, de 1 a 1024, com padrão de 48. Valores maiores são rejeitados, ou cortados quando Truncar automaticamente está ativado.
Campo de lista aceita até 100 itens cadastrados, e recusa qualquer valor fora deles. O truncamento não se aplica: um valor cortado deixaria de corresponder ao item.
Em campo decimal, a precisão vai até 12 algarismos e a escala até 4 casas, ambas fixas após a criação.
Em campo de ponto flutuante, as Casas decimais valem apenas para exibição e podem ser alteradas depois.

Sugestões de itens

No cadastro dos itens de um campo de lista, a plataforma apresenta os valores recebidos que ainda não têm item correspondente, considerando o mês corrente e o anterior. A seleção de um valor abre a linha de novo item já preenchida, restando informar o rótulo.

A sugestão deixa de ser exibida quando o item é cadastrado. A sugestão volta caso o item seja removido enquanto o campo continuar a receber o valor. Campos sensíveis não geram sugestões.

Aparência do item

Cada item de um campo de lista aceita uma marca visual, apresentada na coluna de ícone da relação de itens: uma cor, um ícone do catálogo, ou o logo de uma marca, localizado pelo nome ou pelo endereço do site. A marca distingue os itens de relance, por exemplo os emissores ou os meios de pagamento de um campo. A marca é opcional e não participa da validação do valor recebido. A conta usa o mesmo recurso.

Tipo de propriedade: dimensão ou medição

Cada campo também recebe um tipo de propriedade:

dimensão: representa uma característica do evento usada para segmentação;
medição: representa um valor variável usado em consolidações.

A escolha existe apenas nos campos de texto e de lista. Os demais tipos de dado são sempre medição, conforme a tabela acima.

O tipo de propriedade determina quais métricas e monitoramentos podem ser configurados sobre o campo depois.

Herança

Um campo com Herança ativada é herdado por envios posteriores que usem o mesmo id e não informem o campo. Ative a herança nos campos que descrevem a entidade e chegam apenas no primeiro envio, como o cliente ou o estabelecimento. Deixe a herança desativada nos campos que valem somente para o envio que os trouxe, como a etapa ou o código de resposta daquela tentativa.

Desativar a herança passa a valer no envio seguinte, inclusive para os valores já acumulados. O mecanismo completo está descrito em Herança entre eventos com o mesmo id.

Exibição do valor

O painel pode apresentar um campo de forma diferente do valor armazenado. A exibição é apenas visual: o valor gravado, os filtros e as comparações nas regras continuam usando o valor original.

Exibição	Aplica-se a	Resultado
Valor original	qualquer campo	o valor como foi recebido
País (ISO 3166)	texto	nome do país e a bandeira, no lugar do código
Emissor do cartão	número inteiro	nome do emissor, no lugar do identificador
Provedor do ASN	número inteiro	nome do provedor, no lugar do número
Duração	número inteiro	tempo legível, como `3,5s` ou `2d 1h`

A exibição de duração tem uma configuração própria: a unidade de tempo em que o valor é armazenado, entre milissegundos, segundos e minutos. Sem a unidade, 3500 tanto pode ser três segundos e meio quanto quase uma hora. O padrão é milissegundos, a unidade dos campos de permanência.

Rastrear permanência

Marque um campo discreto (lista ou booleano) como rastreável. A plataforma passa a registrar o tempo que cada entidade permanece em cada valor desse campo: a duração de um pedido em pendente, o tempo decorrido de um cadastro em bloqueio.

Ao ativar o rastreamento, a plataforma provisiona dois campos derivados. Os campos derivados funcionam como qualquer outro campo do tipo de evento, inclusive em métricas, filtros e regras:

Campo derivado	Tipo de propriedade	Conteúdo
`<campo> anterior`	dimensão	valor em que a entidade estava antes da troca
`Tempo em <campo> anterior`	medição	duração da permanência encerrada naquela troca

Duas configurações acompanham o rastreamento:

Dimensões de recorte: campos discretos pelos quais as medidas em aberto podem ser segmentadas, como o provedor ou o estabelecimento. Somente esses campos podem ser usados como dimensão em uma métrica de permanência em aberto.
Retenção da permanência: tempo máximo que uma entidade pode permanecer em um valor antes de deixar de ser acompanhada. Configure o prazo do processo: uma entidade que o ultrapassa foi abandonada, não está retida, e contabilizá-la distorce as medidas em aberto. Em branco, vigoram 90 dias, que também é o teto.

Um tipo de evento aceita no máximo 2 campos rastreáveis. Desativar o rastreamento interrompe o registro e preserva os campos derivados e as métricas construídas sobre eles. Reativar o rastreamento reaproveita os mesmos campos.

O rastreamento vale a partir do momento em que é ativado e não reprocessa o histórico. O mesmo se aplica a uma dimensão de recorte adicionada depois: as entidades já abertas seguem sem ela até trocarem de valor.

Validação no envio de eventos

No recebimento de eventos via POST /events, a plataforma aplica o contrato de campos com as seguintes regras:

campos obrigatórios ausentes causam rejeição;
valores fora do tipo esperado causam rejeição;
campos inativos podem continuar no payload, mas seus valores são ignorados;
campos desconhecidos podem ser ignorados ou rejeitados, conforme a configuração do tipo de evento.

Boas práticas para modelar campos

Defina IDs estáveis e semânticos desde o início.
Comece com um conjunto enxuto de campos essenciais.
Use campos de lista quando houver conjunto controlado de valores.
Evite criar campos redundantes para o mesmo conceito.
Revise periodicamente campos sem uso.

Restrições e ciclo de vida

Algumas configurações são estruturais. Planeje essas configurações no momento da criação:

o ID do campo não pode ser alterado após cadastro;
o tipo de dado não pode ser alterado após cadastro;
o tipo de propriedade não pode ser alterado após cadastro;
em campos decimais, precisão e escala ficam fixas após criação;
itens de campo do tipo lista são gerenciados após o campo ser criado;
o tipo de evento possui limite de até 100 campos.

Campos gerenciados pela plataforma, como os provisionados pelo rastreamento de permanência ou pelas regras, não podem ser removidos. O nome e a descrição desses campos aceitam alteração, para que apareçam no painel com a terminologia da sua operação.

A remoção de um campo pode falhar se ele estiver em uso por métricas, por exemplo em dimensões ou agregações.