API atual/Referência completa/CRM: audiências e RFM

Regras de segmentação

Como escrever a regra de uma audiência, todas as condições aceitas e a prévia que conta os clientes sem gravar.

Como a regra é escrita

Uma regra é uma árvore. O nó raiz é um grupo com op (AND ou OR, padrão AND) e uma lista conditions. Cada item da lista é uma condição (tem type) ou outro grupo (tem conditions). Qualquer nó aceita "not": true para inverter o resultado.

json

{
  "op": "AND",
  "conditions": [
    { "type": "total_spent", "operator": "gte", "value": 50000, "window_days": 90 },
    {
      "op": "OR",
      "conditions": [
        { "type": "state", "operator": "in", "values": ["SP", "RJ"] },
        { "type": "marketing_consent", "value": true }
      ]
    }
  ]
}

Campos de uma condição:

Campos de uma condição

typestringobrigatório

Qual critério avaliar (tabela abaixo). Também são aceitos os apelidos do painel: purchased_product, purchased_category, total_spent, customer_group e first_purchase.

operatorstring

Operador em palavras: gte, lte, gt, lt, eq, is, purchased, includes, any_of (pertence), not_purchased, excludes, none_of, is_not, neq (não pertence). Vence op quando os dois vêm.

opstring

Operador em símbolos: =, >=, <=, >, <, in, not_in, between, contains. Condições de comparação aceitam =, >=, <=, >, <; as de lista aceitam in e not_in.

valueany

Valor único (número, texto, booleano) ou, nas condições de lista, um valor ou uma lista. Uma lista com um elemento vale como o elemento.

valuesarray

Lista de valores, para as condições de lista.

window_daysinteger

Só considera pedidos dos últimos N dias (condições de pedido).

window_hoursinteger

Janela em horas das condições de comportamento. Padrão 24. O apelido hours também vale.

min_total_centsinteger

Só para abandoned_cart: valor mínimo do carrinho, em centavos.

notboolean

true inverte a condição ou o grupo.

Condições disponíveis

`type`	O que avalia	`value`
`bought_product`	Comprou (ou não) certos produtos	ids de produto (uuid); `in`/`not_in`; aceita `window_days`
`bought_category`	Comprou (ou não) em certas categorias	ids de categoria (uuid); `in`/`not_in`; `window_days`
`order_status`	Tem pedido (ou não) em certos status	letra do status ou nome (`C`, `completed`...); `in`/`not_in`; `window_days`
`usergroup`	Está (ou não) em certos grupos de clientes	ids de grupo (uuid); `in`/`not_in`
`state`, `city`, `district`, `country`	Endereço cadastrado	textos; `in`/`not_in`/`contains`
`language`	Idioma do cadastro	`pt-BR`...; `in`/`not_in`/`contains`
`email`	E-mail	texto; `=`/`in`/`not_in`/`contains`
`order_date`	Tem pedido em um intervalo de datas	datas ISO; `gte`, `lte` ou `between` (duas datas)
`marketing_consent`	Aceitou receber marketing	`true` (padrão) ou `false`
`order_total`	Soma dos pedidos, em centavos	inteiro; `=`, `>=`, `<=`, `>`, `<`; `window_days`
`order_count`	Quantidade de pedidos	inteiro; comparação; `window_days`
`last_purchase_days`	Dias desde a última compra	inteiro; comparação
`first_order`	Tem exatamente um pedido	sem valor; `window_days`
`viewed_no_purchase`	Viu um produto e não o comprou depois	`window_hours`
`wishlist_no_purchase`	Pôs na lista de desejos e não comprou depois	`window_hours`
`abandoned_cart`	Tem carrinho abandonado ainda não recuperado	`window_hours`, `min_total_cents`
`rfm_segment`	Segmento RFM do cliente	um ou mais rótulos de Resumo RFM; `in`/`not_in`
`loyalty_tier`	Nível no programa de fidelidade	ids de nível; `in`/`not_in`
`nps_score`	Nota da última resposta de NPS	inteiro; comparação; `window_hours` opcional
`referrals_rewarded`	Indicações já recompensadas	inteiro; comparação; `window_hours` opcional
`acquisition_channel`	Canal da primeira compra	nomes de canal; `in`/`not_in`
`churn_risk`	Risco de abandono previsto, de 0 a 1	número; comparação
`predicted_clv`	Valor futuro previsto (12 meses), em centavos	inteiro; comparação
`next_order_days`	Dias previstos até o próximo pedido	inteiro; comparação

As condições de previsão (churn_risk, predicted_clv, next_order_days) usam o último cálculo ainda válido do cliente e deixam de fora quem não tem previsão.

Contar os clientes de uma regra

Calcula quantos clientes a regra alcança agora, sem criar nem alterar nada. É a forma segura de testar uma regra antes de gravá-la ou de usá-la em uma campanha.

POST/api/v1/vendor/crm/audiences/previewSeller

Contar os clientes de uma regra

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

ruleobject

A regra a testar, no formato descrito acima. Sem rule (ou com conditions vazio) a contagem é a de todos os clientes ativos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  }
}'

Resposta

200Contagem

json

{
  "count": 3743
}

Campos da resposta

countinteger

Clientes que a regra alcança neste momento.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"vendor profile not found"}`
403	O módulo `crm` está desligado nesta loja.	`{"error":"module_disabled","module":"crm"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Regra que o motor não executa.	`{"error":"failed to evaluate rule","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`

Veja também

API atual/Referência completa/CRM: audiências e RFM

Regras de segmentação

Como escrever a regra de uma audiência, todas as condições aceitas e a prévia que conta os clientes sem gravar.

Como a regra é escrita

json

{
  "op": "AND",
  "conditions": [
    { "type": "total_spent", "operator": "gte", "value": 50000, "window_days": 90 },
    {
      "op": "OR",
      "conditions": [
        { "type": "state", "operator": "in", "values": ["SP", "RJ"] },
        { "type": "marketing_consent", "value": true }
      ]
    }
  ]
}

Campos de uma condição:

Campos de uma condição

typestringobrigatório

Qual critério avaliar (tabela abaixo). Também são aceitos os apelidos do painel: purchased_product, purchased_category, total_spent, customer_group e first_purchase.

operatorstring

opstring

Operador em símbolos: =, >=, <=, >, <, in, not_in, between, contains. Condições de comparação aceitam =, >=, <=, >, <; as de lista aceitam in e not_in.

valueany

Valor único (número, texto, booleano) ou, nas condições de lista, um valor ou uma lista. Uma lista com um elemento vale como o elemento.

valuesarray

Lista de valores, para as condições de lista.

window_daysinteger

Só considera pedidos dos últimos N dias (condições de pedido).

window_hoursinteger

Janela em horas das condições de comportamento. Padrão 24. O apelido hours também vale.

min_total_centsinteger

Só para abandoned_cart: valor mínimo do carrinho, em centavos.

notboolean

true inverte a condição ou o grupo.

Condições disponíveis

`type`	O que avalia	`value`
`bought_product`	Comprou (ou não) certos produtos	ids de produto (uuid); `in`/`not_in`; aceita `window_days`
`bought_category`	Comprou (ou não) em certas categorias	ids de categoria (uuid); `in`/`not_in`; `window_days`
`order_status`	Tem pedido (ou não) em certos status	letra do status ou nome (`C`, `completed`...); `in`/`not_in`; `window_days`
`usergroup`	Está (ou não) em certos grupos de clientes	ids de grupo (uuid); `in`/`not_in`
`state`, `city`, `district`, `country`	Endereço cadastrado	textos; `in`/`not_in`/`contains`
`language`	Idioma do cadastro	`pt-BR`...; `in`/`not_in`/`contains`
`email`	E-mail	texto; `=`/`in`/`not_in`/`contains`
`order_date`	Tem pedido em um intervalo de datas	datas ISO; `gte`, `lte` ou `between` (duas datas)
`marketing_consent`	Aceitou receber marketing	`true` (padrão) ou `false`
`order_total`	Soma dos pedidos, em centavos	inteiro; `=`, `>=`, `<=`, `>`, `<`; `window_days`
`order_count`	Quantidade de pedidos	inteiro; comparação; `window_days`
`last_purchase_days`	Dias desde a última compra	inteiro; comparação
`first_order`	Tem exatamente um pedido	sem valor; `window_days`
`viewed_no_purchase`	Viu um produto e não o comprou depois	`window_hours`
`wishlist_no_purchase`	Pôs na lista de desejos e não comprou depois	`window_hours`
`abandoned_cart`	Tem carrinho abandonado ainda não recuperado	`window_hours`, `min_total_cents`
`rfm_segment`	Segmento RFM do cliente	um ou mais rótulos de Resumo RFM; `in`/`not_in`
`loyalty_tier`	Nível no programa de fidelidade	ids de nível; `in`/`not_in`
`nps_score`	Nota da última resposta de NPS	inteiro; comparação; `window_hours` opcional
`referrals_rewarded`	Indicações já recompensadas	inteiro; comparação; `window_hours` opcional
`acquisition_channel`	Canal da primeira compra	nomes de canal; `in`/`not_in`
`churn_risk`	Risco de abandono previsto, de 0 a 1	número; comparação
`predicted_clv`	Valor futuro previsto (12 meses), em centavos	inteiro; comparação
`next_order_days`	Dias previstos até o próximo pedido	inteiro; comparação

As condições de previsão (churn_risk, predicted_clv, next_order_days) usam o último cálculo ainda válido do cliente e deixam de fora quem não tem previsão.

Contar os clientes de uma regra

Calcula quantos clientes a regra alcança agora, sem criar nem alterar nada. É a forma segura de testar uma regra antes de gravá-la ou de usá-la em uma campanha.

POST/api/v1/vendor/crm/audiences/previewSeller

Contar os clientes de uma regra

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um usuário do painel do seller (lojista), obtido no login (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

ruleobject

A regra a testar, no formato descrito acima. Sem rule (ou com conditions vazio) a contagem é a de todos os clientes ativos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  }
}'

Resposta

200Contagem

json

{
  "count": 3743
}

Campos da resposta

countinteger

Clientes que a regra alcança neste momento.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
403	O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).	`{"error":"vendor_pending_review","message":"..."}`
403	O usuário tem papel de seller, mas não está ligado a nenhum seller.	`{"error":"vendor profile not found"}`
403	O módulo `crm` está desligado nesta loja.	`{"error":"module_disabled","module":"crm"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	Regra que o motor não executa.	`{"error":"failed to evaluate rule","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`