Eventos

Envie para POST /events cada ocorrência real da operação: uma tentativa de pagamento, uma autenticação, uma atualização de cadastro. O tipo de evento define o contrato; o evento carrega o dado ocorrido.

Vínculo com o tipo de evento

Todo evento informa no atributo type qual tipo de evento ele representa. O atributo é obrigatório.

O valor de type deve ser o ID de um tipo de evento já configurado e ativo na conta.

Se o tipo de evento não existir ou estiver inativo, a API rejeita o envio.

Estrutura mínima de envio

No envio para POST /events, os campos principais são:

type: ID do tipo de evento;
id: identificador único do evento;
attributes: dados do evento conforme os campos configurados no tipo;
timestamp (opcional): data e hora da ocorrência. Sem esse atributo, a plataforma usa o horário do recebimento;
rule.name (opcional): nome da regra a executar sobre este evento. Sem esse atributo, vale a regra padrão do tipo de evento, se houver.

Nomes de campo iniciados por _ ou % são reservados da plataforma. A API rejeita o envio se algum deles aparecer em attributes.

Herança entre eventos com o mesmo `id`

Vários envios podem compartilhar o mesmo id, representando a mesma ocorrência em etapas diferentes: a criação de um pedido e, minutos depois, o seu resultado. Um envio posterior não precisa repetir tudo o que já foi informado.

Cada campo do tipo de evento define se participa dessa herança, pela configuração Herança. Com a herança ativada, um envio que omite o campo recebe o valor deixado pelo envio anterior. Com a herança desativada, o campo vale apenas para o envio que o trouxe.

A herança carrega o evento como ficou gravado, não apenas o que o cliente enviou. Os campos preenchidos por uma regra durante o processamento também são herdados. Os valores herdados valem em toda parte: no evento gravado, nas condições da regra e nas análises.

Enviar o campo com o valor null limpa o valor herdado, e os envios seguintes não o recuperam. Omitir o campo mantém a herança.

A herança tem prazo, configurado no tipo de evento. Passado esse prazo sem novos envios com o mesmo id, a plataforma descarta os valores acumulados e um envio posterior vale exatamente pelo que trouxer.

Validação do envio

A validação do evento segue as configurações do tipo de evento:

campos obrigatórios precisam ser enviados;
tipos de dados precisam estar no formato esperado;
campos desconhecidos podem ser ignorados ou rejeitados, conforme a configuração do tipo de evento.

A validação garante consistência na ingestão e impede que eventos fora do contrato afetem métricas e monitoramentos.

Resposta do envio

A resposta apresenta o id do evento e todos os campos do tipo de evento. Os campos preenchidos por uma regra durante o processamento também aparecem na resposta. Um evento enviado com três campos pode retornar com cinco, se uma regra tiver enriquecido os outros dois.

A plataforma grava os campos reservados no evento, mas não os apresenta na resposta.

Exemplo prático

Você cadastra um tipo de evento com ID transaction.
Define os campos esperados, como amount e status.
Envia um evento para POST /events com type: transaction.
A plataforma valida o payload, executa a regra do tipo de evento (se houver) e processa o evento para uso em análises, métricas e monitoramentos.