> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos personalizados e metas

> Acompanhe o comportamento dos usuários e as metas de conversão para criar segmentos RFM e enriquecer a linha do tempo dos contatos.

## Visão geral

Os eventos personalizados registram ações dos usuários vindas de sistemas externos (e-commerce, CRM, ferramentas de análise). Eles aparecem na linha do tempo do contato, e as metas deles permitem criar segmentos RFM (Recência, Frequência, Valor monetário).

## Linha do tempo do contato

Todo evento personalizado cria uma entrada na linha do tempo do contato, então você vê o histórico completo das interações de um contato:

![Linha do tempo do contato com eventos personalizados](https://www.notifuse.com/docs/assets/screenshots/custom_event_timeline.png)

Cada evento mostra o seu `event_name` como o tipo da entrada na linha do tempo (por exemplo, "order.completed", "subscription.started"). O campo `properties` guarda o contexto adicional, visível nos detalhes da linha do tempo.

## Tipos de meta

Os segmentos são criados a partir de metas. Cada evento pode acompanhar uma meta:

| Tipo           | Caso de uso                                     | goal_value  |
| -------------- | ----------------------------------------------- | ----------- |
| `purchase`     | Pedidos de e-commerce, pagamentos únicos        | Obrigatório |
| `subscription` | Assinaturas de SaaS, planos de associação       | Obrigatório |
| `lead`         | Formulários de contato, pedidos de demonstração | Opcional    |
| `signup`       | Cadastros de conta                              | Opcional    |
| `booking`      | Agendamentos, consultas                         | Opcional    |
| `trial`        | Ativações de teste gratuito                     | Opcional    |
| `other`        | Eventos de conversão personalizados             | Opcional    |

## Criar segmentos RFM

A análise RFM (Recência, Frequência, Valor monetário) encontra os seus melhores clientes. Use o criador de segmentos com condições de **Meta**:

![Criador de segmentos com uma meta de eventos personalizados](https://www.notifuse.com/docs/assets/screenshots/segment_goals.png)

### Valor monetário: gasto total

Escolha o tipo de meta **Compra** e a agregação **total**, depois defina um valor mínimo para encontrar os clientes que mais gastam.

### Frequência: número de compras

Escolha o tipo de meta **Compra** e a agregação **contagem**, depois defina um número mínimo para encontrar os clientes que compram de novo.

### Recência: atividade recente

Use o filtro de período "nos últimos X dias" para encontrar os clientes com compras recentes.

### Exemplos de segmentos RFM

- **Clientes VIP**: gastaram US$ 1000 ou mais E fizeram 5 pedidos ou mais E compraram nos últimos 60 dias
- **Alto valor em risco**: gastaram US$ 500 ou mais E não compram há 90 dias
- **Novos com alto potencial**: primeira compra acima de US$ 200 nos últimos 30 dias

### Opções de agregação

| Opção    | Descrição                                                  |
| -------- | ---------------------------------------------------------- |
| Total    | Soma de todos os valores da meta (gasto ao longo do tempo) |
| Contagem | Número de eventos (número de pedidos)                      |
| Média    | Valor médio da meta (ticket médio)                         |
| Mínimo   | Menor valor da meta                                        |
| Máximo   | Maior valor da meta                                        |

### Opções de período

| Opção                 | Descrição                       |
| --------------------- | ------------------------------- |
| A qualquer momento    | Todo o histórico                |
| Nos últimos X dias    | Janela móvel                    |
| No intervalo de datas | Período específico              |
| Antes da data         | Corte no histórico              |
| Depois da data        | A partir de uma data específica |

## Registrar eventos

### Evento único

```bash
curl -X POST "https://your-instance.com/api/customEvents.upsert" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "email": "customer@example.com",
    "event_name": "order.completed",
    "external_id": "order_12345",
    "properties": {
      "items": ["Product A", "Product B"],
      "currency": "USD"
    },
    "goal_type": "purchase",
    "goal_value": 149.99
  }'
```

### Importação em lote

Importe até 50 eventos de uma vez:

```bash
curl -X POST "https://your-instance.com/api/customEvents.import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "your_workspace",
    "events": [
      {
        "email": "user1@example.com",
        "event_name": "order.completed",
        "external_id": "order_001",
        "goal_type": "purchase",
        "goal_value": 99.99
      },
      {
        "email": "user2@example.com",
        "event_name": "order.completed",
        "external_id": "order_002",
        "goal_type": "purchase",
        "goal_value": 249.99
      }
    ]
  }'
```

## Formato do nome do evento

Os nomes de eventos precisam estar em minúsculas e usar letras, números, pontos, sublinhados, hífens ou barras:

- `order.completed`
- `subscription/started`
- `form_submit`
- `user-signup`

> [!NOTE]
>
> As metas registradas pela [Web Analytics](https://www.notifuse.com/pt/docs/web-analytics/goals.md) chegam à linha do tempo do contato por uma regra mais restrita: só letras ASCII, números, pontos e barras, e todo o resto (incluindo hífens e caracteres acentuados) é substituído por um sublinhado. Uma meta web chamada `user-signup` chega como `user_signup`. Se você envia o mesmo evento pelos dois caminhos, escolha um nome que passe pelos dois.

## Reembolsos

Use um `goal_value` negativo para os reembolsos, assim os cálculos de LTV continuam corretos:

```json
{
  "email": "customer@example.com",
  "event_name": "order.refunded",
  "external_id": "refund_12345",
  "goal_type": "purchase",
  "goal_value": -50.00
}
```

## Permissões

Os eventos personalizados não têm uma permissão própria: eles dependem de **Contatos**. Registrar ou importar um evento exige **escrita** de Contatos, e ler um evento exige **leitura** de Contatos. Conceder leitura de Contatos, portanto, também dá acesso aos eventos registrados nos seus contatos e à linha do tempo que eles alimentam. Veja [Administradores e chaves API](https://www.notifuse.com/pt/docs/features/admins-api-keys.md).

## Observações

- `customEvents.upsert` cria o contato quando nenhum contato tem aquele email. `customEvents.import` não cria contatos
- Os eventos só são atualizados se `occurred_at` for mais recente que o existente
- Exclusão lógica definindo `deleted_at` (defina como `null` para restaurar)
- Só um evento novo (um novo `external_id`) inicia as automações acionadas pelo nome dele; desde a versão 44.0, uma atualização, uma exclusão lógica ou uma restauração não iniciam
- Veja a [Referência da API](https://www.notifuse.com/docs/api-reference/import-custom-events.md) para a documentação completa dos endpoints
