CRM: audiências e RFM

Uma audiência (também chamada de segmento) é um grupo de clientes definido por uma regra em vez de uma lista fixa de pessoas: "quem comprou mais de R$ 500 nos últimos 90 dias", "quem abandonou o carrinho ontem". A plataforma guarda a regra e a reavalia, então o grupo acompanha os clientes que entram e saem do critério. As audiências são a base de campanhas e jornadas de relacionamento (CRM).

Nesta seção o seller (lojista) cria e gerencia as próprias audiências. Cada seller enxerga só as suas, e as regras que olham pedidos contam apenas os pedidos do próprio seller.

Como funciona

1. Escreva a regra
   Monte o objeto rule com grupos AND/OR e condições (ver Regras de segmentação).
2. Conte com a prévia
   POST /api/v1/vendor/crm/audiences/preview devolve quantos clientes a regra alcança. Nada é gravado.
3. Crie a audiência
   POST /api/v1/vendor/crm/audiences valida a regra de novo e grava. O member_count ainda é 0.
4. Materialize
   POST /api/v1/vendor/crm/audiences/{id}/materialize cria (na primeira vez) o grupo de clientes e sincroniza os membros. Devolve o total.
5. Acompanhe e exporte
   stats mostra tamanho e receita atribuída às campanhas; export baixa os contatos em CSV.

Conceitos-chave

Regra, audiência e grupo de clientes

A regra é o critério. A audiência é a regra com nome, descrição e estado. O grupo de clientes (usergroup) é a lista real de pessoas, criada na materialização. Editar a regra não muda o grupo até a próxima materialização.

Quem entra

Só contas de cliente ativas (não excluídas). As condições de pedido consideram apenas pedidos realizados: cancelados, estornados, falhos, anulados e com chargeback não contam.

Dinheiro, datas e ids

Ids são UUIDs em texto. Datas são RFC 3339. Dinheiro é inteiro em centavos. Veja Ids, dinheiro e datas.

Permissões

Os dados de clientes são sensíveis (a exportação traz e-mail e telefone). As rotas exigem token de seller; o módulo crm precisa estar ligado.

Endpoints

Erros comuns

• Achar que criar já enche o grupo. Depois de criar, o member_count é 0 até você chamar a materialização.
• Mandar dinheiro em reais. "value": 500 significa R$ 5,00. Use 50000 para R$ 500,00.
• Enviar uma lista onde a condição espera um valor só. order_count >= [1,2] é recusado com 400.
• Criar sem name. A plataforma responde 500 em vez de 400 (veja o erro na página de Audiências).
• Usar o id de uma audiência da loja. Audiências do administrador não são visíveis ao seller: a resposta é 404.
• Esperar que o export use a lista materializada. O CSV reavalia a regra na hora; ele não depende da última materialização.

Próximos passos