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 |
O formulário agrupa essas configurações em Comportamento (obrigatoriedade, sensibilidade e herança), 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 |
| Categoria do estabelecimento (MCC) | texto, número inteiro | código e nome da categoria, como 5411 · Supermercados e mercearias |
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.
Na exibição de MCC, os códigos de 3000 a 3999 apresentam o nome da marca, e um código desconhecido aparece como foi recebido. O filtro de Explorar localiza o código pelo número ou pelo nome da categoria, inclusive um código que o campo ainda não recebeu. A exibição de MCC não é oferecida para campos sensíveis.
Um campo de data e hora é exibido no formato local, como 09/10/2026 18:40:35, no fuso horário configurado na conta. Filtros, exportações e a API usam o formato ISO 8601.
Rastrear permanência
Marque um campo discreto (lista ou booleano) como rastreável. Um campo sensível não pode ser rastreável: a seção Permanência não é exibida para ele, e marcar como sensível um campo rastreável é recusado. 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 desativados podem continuar no payload, mas seus valores são ignorados, exceto quando o tipo de evento rejeita campos desconhecidos;
- campos desconhecidos podem ser ignorados ou rejeitados, conforme a configuração do tipo de evento. Quando o tipo de evento rejeita campos desconhecidos, um campo desativado também causa rejeição.
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 é recusada pelas mesmas utilizações que bloqueiam a desativação.
Desativar um campo
Para interromper o armazenamento de um campo sem perder o histórico, desative o campo. As ações Desativar e Ativar estão no menu do campo, na lista de campos e na página do campo.
Ao desativar um campo, a plataforma deixa de armazenar o campo nos novos eventos, e o campo deixa de aparecer em Explorar e nas exportações. Os valores já armazenados são mantidos e voltam a aparecer quando o campo é ativado novamente. Se o tipo de evento rejeitar campos desconhecidos, a API passará a rejeitar os eventos que ainda enviarem o campo desativado.
Ativar volta a armazenar o campo nos novos eventos. A ativação é recusada se o tamanho máximo dos campos ativos, somado ao do campo, passar de 2.048 bytes nas dimensões ou nas medições. A recusa pode ocorrer quando campos criados depois da desativação ocupam o espaço disponível.
Os campos do sistema, iniciados por _, e o campo id não podem ser desativados.
Utilizações
A desativação e a remoção de um campo são recusadas enquanto algum recurso depender do campo. A recusa informa que o campo está em uso e abre a aba Utilizações. Dependem de um campo:
- as métricas e as suas agregações;
- os monitoramentos;
- a versão ativa e a versão em observação (shadow) de uma regra;
- a versão ativa e a versão em observação de uma análise, por meio de uma célula;
- o rastreamento de permanência, inclusive o uso do campo como dimensão de recorte.
Os rascunhos não são considerados, porque um rascunho não executa nada.
A aba Utilizações, na página do campo, lista esses recursos nas colunas Nome, Recurso e Contexto. O contexto indica como o recurso usa o campo: Dimensão, Medição, Filtro, Condição, Ação ou Permanência. A aba apresenta a quantidade de utilizações, assim como a aba Itens de um campo de lista.