🔒 Autenticação necessária

Esta API utiliza Bearer Token no header Authorization. Consulte o tutorial completo antes de fazer sua primeira chamada: Como autenticar nas APIs do CV CRM (v3+ — Bearer Token)

Registra um evento de uso do produto. O evento é gravado no ClickHouse (tabela analytics_eventos) e repassado ao Mixpanel.

Taxonomia dos eventos

Três campos descrevem o que aconteceu e onde:

Os demais campos classificam o evento em dimensões fechadas (enums): acao (o verbo), solucao → modulo → funcionalidade (a hierarquia do produto) e idFuncionalidade (o registro afetado, quando houver).

Regras

• Na mesma tela, quem identifica o evento é acao + descricaoEvento. Dois eventos com o mesmo nomeEvento, a mesma acao e a mesma descricaoEvento viram um só nos relatórios.
• descricaoEvento não leva dado dinâmico (nome de registro, e-mail, id, mensagem de erro). Texto variável espalha o mesmo evento em centenas de linhas e pode carregar dado pessoal.
• Valor de conjunto fechado vai em subFuncionalidade, não em outrosDados. No ClickHouse o sub é coluna própria (agrupável e indexada); outrosDados vira JSON.
• outrosDados é para recortes livres (origem, tipo, totalEtapas...). Não envie dado de negócio sensível — nome de cliente, de empreendimento ou termo digitado em busca.
• Evento que acontece em mais de uma tela sai com o nomeEvento da tela em que ocorreu, não com um nome genérico.
• Backend e frontend medem coisas diferentes. O frontend registra a intenção (o usuário clicou); o backend registra o fato persistido, sob a tela de administração da funcionalidade (Automações Administração). Lidos em sequência dão a conversão; somados, contam duas vezes.

Exemplos

Identificação do usuário

O usuário não é enviado no corpo: vem do token da requisição. O evento é gravado com user_id no formato <ambiente>_<painel>_<idusuario> (ex.: cliente_gestor_42), o mesmo distinct_id do Mixpanel. É por ele que se conta o MAU (usuários distintos com ao menos um evento no mês) — não há eventos de início e fim de sessão nem chamada de identify.

{
  "nomeEvento": "Automações Listagem",
  "descricaoEvento": "Ativação de uma automação",
  "subFuncionalidade": "Card da Automação",
  "outrosDados": {
    "origem": "template",
    "totalEtapas": 4
  }
}