--- title: "Salva um evento de analytics" method: POST path: "/v3/configuracoes/analytics" tags: ["Analytics"] --- # Salva um evento de analytics `POST /v3/configuracoes/analytics` ## Request - Base URL: `https://integracao.cvcrm.com.br/api` - URL: `https://integracao.cvcrm.com.br/api/v3/configuracoes/analytics` - Auth: HTTP bearer > 🔒 **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)](https://desenvolvedor.cvcrm.com.br/docs/como-autenticar-nas-apis-do-cv-crm-com-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**: | Campo | Regra | Exemplo | |---|---|---| | `nomeEvento` | **Funcionalidade + Tela** onde o evento acontece | `Atendimento Administração`, `Automações Listagem` | | `descricaoEvento` | **O que aconteceu**, em substantivo, com texto fixo | `Criação de uma tarefa do atendimento` | | `subFuncionalidade` | **A parte da tela** onde está o gesto rastreado: botão, painel, card, seção | `Tarefa do Atendimento`, `Card da Automação` | 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 | nomeEvento | acao | descricaoEvento | subFuncionalidade | |---|---|---|---| | `Atendimento Administração` | `finalizou` | `Encerramento de uma tarefa do atendimento` | `Tarefa do Atendimento` | | `Automações Listagem` | `ativou` | `Ativação de uma automação` | `Card da Automação` | | `Automações Editor` | `cadastrou` | `Inclusão de um gatilho` | `Painel de Gatilhos` | | `Login Autenticação` | `logou` | `Login realizado pela API` | `API de Autenticação` | ## 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 `__` (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`. ## Request body - object - `nomeEvento` string, required: Funcionalidade + Tela onde o evento acontece. - `descricaoEvento` string, required: O que aconteceu, em substantivo e com texto fixo (sem dado dinâmico). Junto com `acao`, identifica o evento dentro da tela. - `acao` 'cadastrou' | 'editou' | 'excluiu' | 'visualizou' | 'finalizou' | 'cancelou' | 'listou' | 'mouseover' | 'click' | 'restaurou' | 'acessou' | 'arrastou_tela' | 'baixou' | 'agendou' | 'enviou' | 'ativou' | 'desativou' | 'executou' | 'bloqueou' | 'reenviou' | 'logou', required: Verbo da ação, em conjunto fechado. - `modulo` 'gestao_de_reserva' | 'gestao_de_lead' | 'gestao_de_repasse' | 'gestao_de_comissao' | 'gestao_de_simulacao' | 'gestao_de_atendimento' | 'gestao_de_login' | 'gestao_de_assistencia_tecnica' | 'gestao_de_agendamento' | 'gestao_de_empreendimento' | 'gestao_de_usuario_administrativo' | 'gestao_comunicador' | 'gestao_de_precadastro' | 'indicadores_configuracoes' | 'gestao_usuarios_imobiliarias' | 'gestao_imobiliarias' | 'gestao_corretores' | 'gestao_contratos' | 'gestao_subworkflows' | 'gestao_caixa_entrada' | 'gestao_filas_distribuicao_leads' | 'gestao_agenda' | 'configuracoes_comerciais' | 'nova_gestao_de_contratos' | 'gestao_de_automacoes' | 'gestao_de_murais' | 'gestao_de_pesquisas' | 'gestao_de_mailing' | 'gestao_de_banners' | 'gestao_de_trajetoria_cliente' | 'gestao_de_patrimonio_afetacao', required: Módulo de gestão - `solucao` 'gerenciar' | 'integrar' | 'prospectar' | 'relacionar' | 'vender' | 'automatizar' | 'mobile' | 'outras', required: Solução relacionada - `funcionalidade` 'empreendimento' | 'pessoa' | 'corretor' | 'correspondente' | 'mapa_disponibilidade' | 'usuario_administrativo' | 'repasses' | 'lead' | 'pre_cadastro' | 'fila_distribuicao_lead' | 'campanha_ativacao' | 'atendimento' | 'agendamento' | 'assistencia_tecnica' | 'comunicador' | 'pesquisa' | 'portal_cliente' | 'reserva' | 'comissao' | 'simulacao' | 'login' | 'logoff' | 'menu' | 'chat_do_suporte' | 'configuracoes' | 'indicadores' | 'cadastro' | 'busca' | 'notificacoes' | 'avaliacao_app' | 'contas_login' | 'fique_por_dentro' | 'usuarios_imobiliarias' | 'imobiliarias' | 'contratos' | 'subworkflow' | 'caixa_entrada' | 'agenda' | 'configuracoes_comerciais' | 'nova_gestao_de_contratos' | 'automacao' | 'template' | 'mural' | 'mailing' | 'banner' | 'trajetoria_cliente' | 'webphone' | 'patrimonio_afetacao', required: Funcionalidade do evento - `idFuncionalidade` union: ID da funcionalidade (inteiro ou texto de até 100 caracteres) - integer - string - `subFuncionalidade` string: Parte da tela onde está o gesto rastreado (botão, painel, card, seção). Opcional, mas recomendado. - `outrosDados` object: Recortes livres do evento, gravados como JSON (chave → valor escalar). Não envie dado de negócio sensível. Até 20 chaves de até 50 caracteres; valor texto (até 255 caracteres), número, booleano ou nulo. - `indice1` string: Identificador do dado 1 - `indice2` string: Identificador do dado 2 ## Response `200` Evento salvo com sucesso - ApiSuccess - `success` boolean - `data` object, nullable ## Other responses - `400`: Falha na validação (campo obrigatório, enum, tamanho ou formato de outrosDados) - `500`: Erro inesperado (`erro_inesperado`) --- [API](https://skmtc.dev/cvcrm/apis/servi-os-internos-do-construtor-de-vendas.md) - [All operations](https://skmtc.dev/cvcrm/apis/servi-os-internos-do-construtor-de-vendas/llms.txt) - [OpenAPI document](https://skmtc.dev/cvcrm/apis/servi-os-internos-do-construtor-de-vendas/revisions/9f2fd517acbb?raw)