CRM, audiências

Uma audiência (também chamada de segmento) é um grupo de clientes definido por uma regra em vez de uma lista fixa de pessoas. Em vez de dizer "estes 800 clientes", você diz "quem comprou mais de R$ 500,00 nos últimos 90 dias" e a plataforma encontra quem se encaixa, agora e depois. É a base das campanhas de e-mail, WhatsApp e SMS do módulo CRM.

As rotas desta seção são as do administrador da loja: as audiências criadas aqui valem para o marketplace inteiro. O lojista (seller) tem uma versão espelhada no painel dele, que enxerga só os próprios pedidos.

Como funciona

Ciclo de vida de uma audiência

1. Teste a regra com a prévia

   POST /crm/audiences/preview devolve só o número de clientes que casam. Não grava nada. Ajuste a regra até o número fazer sentido.

2. Crie a audiência

   POST /crm/audiences grava nome, descrição e regra. A regra é validada contra o banco antes de salvar: se ela não puder rodar, a criação é recusada.

3. Materialize

   A materialização cria (na primeira vez) um grupo de clientes chamado CRM: <nome da audiência> e sincroniza os membros: entra quem passou a casar, sai quem deixou de casar. É esse grupo que as campanhas e as promoções usam. Para audiências ativas, a plataforma refaz isso sozinha a cada 15 minutos; use POST /crm/audiences/{id}/materialize para forçar na hora.

4. Acompanhe

   GET /crm/audiences/{id}/stats mostra o tamanho atual e a receita atribuída às campanhas que usaram a audiência. GET /crm/audiences/{id}/export baixa os membros em CSV.

Campos de uma audiência

Conceitos importantes

Escopo do administrador

No escopo do administrador, as condições de compra olham os pedidos pai (o pedido do cliente, não os sub-pedidos por seller), para que um carrinho com três sellers não conte como três compras. Pedidos cancelados, reembolsados, com falha, anulados ou com chargeback não contam para valor gasto, número de pedidos nem recência. A única exceção é a condição order_status, cujo objetivo é justamente filtrar por status.

Audiência não é a lista de e-mails

A audiência é a definição. Os membros ficam no grupo de clientes (usergroup_id) depois da materialização. Excluir a audiência não apaga esse grupo, para não quebrar promoções ou outras telas que já apontem para ele.

Consentimento de marketing

A regra não filtra consentimento sozinha. Para campanhas, acrescente a condição marketing_consent com true, senão a audiência inclui clientes que nunca aceitaram receber mensagens.

Endpoints

Erros comuns

1. Esperar membros logo após criar. A criação só grava a definição. Chame a materialização ou espere o ciclo de 15 minutos; antes disso member_count é 0 e usergroup_id não existe.
2. Enviar valores em reais. order_total, predicted_clv e min_total_cents usam centavos. 500 significa R$ 5,00.
3. Passar lista onde cabe um valor só, ou o contrário. value aceita um valor ou uma lista (["SP","RJ"] vira "qualquer um destes"); listas dentro de listas são recusadas.
4. Usar um {id} que não é UUID. GET/PUT com abc devolvem 500 com a explicação em detail, e não 400. Valide o id antes.
5. Esquecer o módulo. 403 module_disabled quer dizer que o CRM não está ligado nessa loja.
6. Tratar o PUT como substituição total. Ele é parcial: só os campos enviados mudam. Para limpar a regra, envie uma regra vazia explícita ({"op":"AND","conditions":[]}), o que casa com todos os clientes.
7. Confiar em member_count como número vivo. Ele é o da última materialização. O número atual está em live_count nas estatísticas.

Próximos passos