> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt
> Use this file to discover all available pages before exploring further.
# Segmentações e funis
> Público-alvo dinâmico por critérios e jornadas por etapas na API da Cativa.
Segmentações e funis são as ferramentas de marketing da Cativa para descrever **quem** é o seu público e **em que ponto da jornada** cada pessoa está. Esta página explica os dois conceitos e as rotas públicas que você usa para dimensionar, materializar e automatizar em cima deles.
Pense numa segmentação como uma **playlist inteligente**: você define a regra ("músicas de rock dos anos 90") e a lista se atualiza sozinha conforme entram e saem faixas que se encaixam. Você não arrasta cada música na mão; descreve o critério e a plataforma resolve quem está dentro a cada momento.
Segmentações e funis usam a mesma base das demais páginas: `https://apis.cativalab.digital/tenant/api/v2`. São rotas administrativas (`/admin/marketing/...`), então exigem uma API Key com escopo de admin. A autenticação é a mesma: `Authorization: Bearer cativa_live_...`.
## Segmentação: público-alvo dinâmico
Uma **segmentação** é um público-alvo definido por **critérios** (badges, atividade, cadastro, etc.), não uma lista estática de IDs. Você descreve a regra uma vez e a plataforma **resolve em tempo real** quem cai no segmento. Quando um usuário ganha um badge ou volta a ficar ativo, ele entra ou sai do segmento sem você tocar em nada.
Isso é útil para:
* **Comunicação direcionada**: disparar um email ou push só para quem se encaixa.
* **Exportar para o seu CRM**: materializar a lista de usuários do segmento e sincronizar para HubSpot, RD Station, etc.
* **Dimensionar antes de agir**: saber quantas pessoas o critério atinge antes de salvar ou disparar.
### Rotas de segmentação
| Método | Rota | Para quê |
| -------- | -------------------------------------------- | --------------------------------------------------------- |
| `GET` | `/admin/marketing/segmentations` | Listar segmentações |
| `POST` | `/admin/marketing/segmentations` | Criar segmentação |
| `GET` | `/admin/marketing/segmentations/{id}` | Detalhar uma segmentação |
| `PUT` | `/admin/marketing/segmentations/{id}` | Atualizar critérios |
| `DELETE` | `/admin/marketing/segmentations/{id}` | Remover segmentação |
| `GET` | `/admin/marketing/segmentations/{id}/users` | Materializar a lista de usuários do segmento |
| `POST` | `/admin/marketing/segmentations/users-count` | Contar usuários que caem num critério |
| `POST` | `/admin/marketing/segmentations/preview` | Pré-visualizar o resultado de um critério antes de salvar |
O `{id}` é um ULID (ex: `01HQ7Z3X4Y8N2K5P6R7T8V9W0X`).
### Do critério à lista exportável
`POST /admin/marketing/segmentations/preview` (ou `users-count`) manda o critério no corpo e devolve tamanho e amostra do público, sem persistir nada.
Refine o critério (mais um badge, janela de atividade diferente) e repita o preview até o público bater com o que você espera.
`POST /admin/marketing/segmentations` persiste a regra e retorna o `id`.
`GET /admin/marketing/segmentations/{id}/users` resolve a lista completa em tempo real, para paginar e sincronizar ao seu CRM ou alimentar um disparo.
### Dimensionar antes de salvar
Use `preview` e `users-count` para **testar um critério sem criar nada**. Mande o critério no corpo e veja o tamanho e a amostra do público antes de comprometer. Depois de validado, `POST /segmentations` persiste a regra e `{id}/users` materializa a lista completa (por exemplo, para paginar e exportar ao seu CRM ou alimentar um disparo de comunicação).
### Criar uma segmentação
```bash cURL theme={null}
curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/marketing/segmentations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Premium ativos",
"criteria": {
"badgeIds": ["01HQBADGE0000000000PREMIUM"],
"activeInLastDays": 30
}
}'
```
```js Node theme={null}
const res = await fetch(
'https://apis.cativalab.digital/tenant/api/v2/admin/marketing/segmentations',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CATIVA_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Premium ativos',
criteria: {
badgeIds: ['01HQBADGE0000000000PREMIUM'],
activeInLastDays: 30
}
})
}
);
const segmentation = await res.json();
```
Resposta ilustrativa da criação (o schema autoritativo fica na API Reference, tag **Segmentation**):
```json theme={null}
{
"id": "01HQ7Z3X4Y8N2K5P6R7T8V9W0X",
"createdAt": "2026-07-10T12:00:00Z"
}
```
### Contar usuários de um critério
```bash cURL theme={null}
curl -X POST https://apis.cativalab.digital/tenant/api/v2/admin/marketing/segmentations/users-count \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"criteria": {
"badgeIds": ["01HQBADGE0000000000PREMIUM"],
"activeInLastDays": 30
}
}'
```
```js Node theme={null}
const res = await fetch(
'https://apis.cativalab.digital/tenant/api/v2/admin/marketing/segmentations/users-count',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.CATIVA_API_KEY}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
criteria: {
badgeIds: ['01HQBADGE0000000000PREMIUM'],
activeInLastDays: 30
}
})
}
);
const { count } = await res.json();
```
Resposta ilustrativa (o schema autoritativo fica na API Reference, tag **Segmentation**). `count` é o tamanho do público que casa com o critério **agora**:
```json theme={null}
{
"count": 342
}
```
Os nomes e tipos exatos de cada campo de resposta (contagem, amostra de usuários, formato do critério) estão na API Reference, sob a tag **Segmentation**. Não assuma o shape do corpo a partir dos exemplos acima: consulte o contrato publicado por endpoint.
## Funil: a jornada por etapas
Um **funil** modela a jornada do usuário em **etapas** ordenadas (por exemplo: visitou, cadastrou, comprou, engajou). Diferente da segmentação, que responde "quem se encaixa neste critério agora", o funil responde "quantas pessoas estão em cada passo" e onde a jornada perde gente.
Use `step-count` para obter a **contagem de usuários por etapa** e enxergar a conversão de um passo para o próximo.
### Rotas de funil
| Método | Rota | Para quê |
| -------- | ------------------------------------- | ------------------------------ |
| `GET` | `/admin/marketing/funnels` | Listar funis |
| `POST` | `/admin/marketing/funnels` | Criar funil |
| `GET` | `/admin/marketing/funnels/{id}` | Detalhar um funil |
| `PUT` | `/admin/marketing/funnels/{id}` | Atualizar etapas |
| `DELETE` | `/admin/marketing/funnels/{id}` | Remover funil |
| `GET` | `/admin/marketing/funnels/step-count` | Contagem de usuários por etapa |
O contrato de cada resposta de funil (definição de etapas, contagem por passo) está na API Reference, sob a tag **Funnel**. Consulte o endpoint publicado em vez de inferir os campos.
## Segmentação x funil
| | Segmentação | Funil |
| ---------------- | ---------------------------------------- | ----------------------------------------- |
| **Pergunta** | Quem se encaixa neste critério agora? | Em que passo da jornada cada pessoa está? |
| **Forma** | Um conjunto resolvido em tempo real | Etapas ordenadas com contagem por passo |
| **Saída típica** | Lista de usuários (`{id}/users`) | Contagem por etapa (`step-count`) |
| **Uso** | Comunicação direcionada, export para CRM | Medir conversão e onde a jornada vaza |
Os dois se complementam: você pode dimensionar um público com `users-count`, materializá-lo com `{id}/users`, e acompanhar como esse público avança pelas etapas do funil ao longo do tempo.
## Erros comuns e dúvidas
Segmentações e funis usam a mesma base das demais páginas: `https://apis.cativalab.digital/tenant/api/v2`.
É esperado. A segmentação é **resolvida em tempo real**: entre um passo e outro, alguém pode ter ganhado um badge ou voltado a ficar ativo e entrado (ou saído) do segmento. `count` é uma foto do momento da chamada, não um número congelado.
Não. Ambos só **dimensionam** um critério enviado no corpo, sem persistir nada. Quem cria a regra é o `POST /segmentations`. Use preview à vontade para calibrar antes de salvar.
Segmentação responde "quem se encaixa neste critério agora" (saída: lista de usuários). Funil responde "em que passo da jornada cada pessoa está" (saída: contagem por etapa via `step-count`). Um mede público, o outro mede conversão.
As rotas `/admin/marketing/...` exigem uma API Key com escopo administrativo. Confira o header `Authorization: Bearer cativa_live_...` e o escopo da chave. Nunca exponha a chave no frontend.
## Próximos passos
O modelo `User` que as segmentações resolvem e o endpoint canônico para validar credenciais.
Materialize a lista de um segmento e mantenha o CRM em sincronia com a comunidade.