Tipos de evento

Tipo de evento é a estrutura que define o contrato de dados de um evento na plataforma.

Na prática, ele descreve como um evento deve ser estruturado, quais dados são relevantes para análise e como esses dados podem ser monitorados ao longo do tempo.

Por exemplo, você pode configurar tipos de evento para transação financeira (transaction), autenticação de usuário (user_authentication) ou marcos logísticos de entrega (logistics_delivery_event).

Diferença entre tipo de evento e evento

  • tipo de evento: é o modelo de dados e regras de validação.
  • evento: é a ocorrência real enviada para a API, seguindo o modelo do tipo de evento.

Todo evento sempre pertence a um tipo de evento previamente configurado.

Na API POST /events, isso acontece pelo atributo type do evento, que deve informar o ID do tipo de evento cadastrado. Se o tipo informado não existir ou estiver inativo, o envio é rejeitado.

O que o tipo de evento resolve

Com tipo de evento, a integração deixa de depender de endpoints rígidos por domínio específico (como pagamentos) e passa a seguir um modelo mais flexível:

  • você define o tipo de evento de acordo com o seu contexto de negócio;
  • envia eventos padronizados para o endpoint POST /events;
  • evolui o modelo com menor acoplamento entre produto e integração.

Componentes principais

Um tipo de evento normalmente contempla:

  • campos: estrutura do evento (por exemplo: identificadores, valores, status e atributos de contexto);
  • métricas: agregações e indicadores derivados dos eventos recebidos;
  • monitoramentos: regras e visões para acompanhamento operacional, risco e performance.

Essa combinação permite modelar diferentes fluxos de negócio sem criar um endpoint específico para cada novo caso de uso.

Campos

Os campos definem o contrato de dados do tipo de evento. Consulte Campos para detalhes sobre configuração, tipos de dado e regras de validação.

Relação com a API /events

Depois que um tipo de evento é definido, cada ocorrência é enviada para POST /events seguindo o contrato correspondente.

Esse padrão favorece:

  • padronização de ingestão de dados;
  • evolução contínua da modelagem;
  • reaproveitamento de métricas e monitoramentos entre cenários.

Boas práticas

  • Use nomes claros e estáveis para os tipos de evento.
  • Evite tipos genéricos demais, sem semântica de negócio.
  • Trate mudanças de contrato com versionamento planejado.
  • Documente obrigatoriedade e formato de cada campo para o time de integração.

Índice