Segmentações e funis

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

Pré-visualize o critério

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.

Ajuste e reconte

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.

Salve a segmentação

POST /admin/marketing/segmentations persiste a regra e retorna o id.

Materialize e exporte

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

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
    }
  }'

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):

{
  "id": "01HQ7Z3X4Y8N2K5P6R7T8V9W0X",
  "createdAt": "2026-07-10T12:00:00Z"
}

Contar usuários de um critério

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
    }
  }'

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:

{
  "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

Bati numa rota /tenant/api/v2 e deu 404

Segmentações e funis usam a mesma base das demais páginas: https://apis.cativalab.digital/tenant/api/v2.

A contagem mudou entre o preview e o materialize

É 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.

Preview e users-count criam alguma segmentação?

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.

Quando uso segmentação e quando uso funil?

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.

Recebi 403 nas rotas de marketing

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

Identidade e usuários

O modelo User que as segmentações resolvem e o endpoint canônico para validar credenciais.

Sincronizar membros do CRM

Materialize a lista de um segmento e mantenha o CRM em sincronia com a comunidade.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Segmentação: público-alvo dinâmico

Rotas de segmentação

Do critério à lista exportável

Dimensionar antes de salvar

Criar uma segmentação

Contar usuários de um critério

Funil: a jornada por etapas

Rotas de funil

Segmentação x funil

Erros comuns e dúvidas

Próximos passos

Identidade e usuários

Sincronizar membros do CRM

​Segmentação: público-alvo dinâmico

​Rotas de segmentação

​Do critério à lista exportável

​Dimensionar antes de salvar

​Criar uma segmentação

​Contar usuários de um critério

​Funil: a jornada por etapas

​Rotas de funil

​Segmentação x funil

​Erros comuns e dúvidas

​Próximos passos

Identidade e usuários

Sincronizar membros do CRM

Segmentação: público-alvo dinâmico

Rotas de segmentação

Do critério à lista exportável

Dimensionar antes de salvar

Criar uma segmentação

Contar usuários de um critério

Funil: a jornada por etapas

Rotas de funil

Segmentação x funil

Erros comuns e dúvidas

Próximos passos