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

Indicadores do CRM

Distribuição da base de clientes por segmento RFM e verificação de SPF, DKIM e DMARC do domínio de envio.

Duas leituras de apoio ao marketing: quem são seus clientes (segmentos RFM) e se seus e-mails chegam (autenticação do domínio). Nenhuma das duas altera dados.

Resumo RFM

RFM é uma técnica clássica de CRM que classifica cada cliente por três perguntas: há quanto tempo comprou (Recência), quantas vezes comprou (Frequência) e quanto gastou (Monetário). A plataforma dá a cada cliente uma nota de 1 a 5 em cada eixo (divide a base em cinco faixas de mesmo tamanho; 5 é o melhor) e traduz as notas de recência e frequência em um dos 11 rótulos abaixo. Só entram clientes com pelo menos um pedido válido (cancelados, reembolsados, com falha, anulados e com chargeback não contam), e os pedidos considerados são os pedidos pai do marketplace.

Esta rota devolve quantos clientes há em cada rótulo, com a receita e a média de pedidos. É a base do gráfico de barras de segmentos e ajuda a escolher o valor da condição rfm_segment em uma regra de audiência.

GET/api/v1/admin/crm/rfm/summaryAdmin

Distribuição de clientes por segmento RFM

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/rfm/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Distribuição por segmento

json

{
  "total_customers": 7186,
  "segments": [
    { "segment": "champions", "customers": 2057, "revenue_cents": 1863039837, "avg_orders": 13.45 },
    { "segment": "loyal", "customers": 30, "revenue_cents": 16654613, "avg_orders": 7.57 },
    { "segment": "potential_loyalist", "customers": 580, "revenue_cents": 72796471, "avg_orders": 1.98 }
  ]
}

A lista real traz sempre os 11 segmentos, na ordem da tabela abaixo; o exemplo mostra só três.

Campos da resposta

total_customersinteger

Clientes com pedido válido (soma de todos os segmentos).

segmentsarray

Um item por segmento, sempre os 11, na mesma ordem. Segmento sem clientes vem com zeros.

segments[].segmentstring

championsloyalpotential_loyalistnew_customerspromisingneed_attentionat_riskcant_losehibernatingabout_to_sleeplost

Rótulo do segmento.

segments[].customersinteger

Clientes no segmento.

segments[].revenue_centsinteger

Soma do valor dos pedidos desses clientes, em centavos.

segments[].avg_ordersnumber

Média de pedidos por cliente do segmento.

Os 11 segmentos

Avaliados na ordem da tabela; o primeiro que casa vale. R é a nota de recência e F a de frequência.

Segmento	Regra (R e F)	Leitura
`champions`	R ≥ 4 e F ≥ 4	Compraram há pouco e compram sempre.
`loyal`	R ≥ 3 e F ≥ 4	Compram com frequência.
`potential_loyalist`	R ≥ 4 e F ≥ 2	Recentes, com mais de uma compra.
`new_customers`	R ≥ 4 e F = 1	Primeira compra recente.
`promising`	R = 3 e F = 1	Compra única, nem tão recente.
`need_attention`	R = 3 e F de 2 a 3	Esfriando.
`cant_lose`	R ≤ 2 e F = 5	Eram os melhores e sumiram.
`at_risk`	R ≤ 2 e F ≥ 3	Compravam bem e pararam.
`hibernating`	R ≤ 2 e F = 2	Poucas compras, antigas.
`about_to_sleep`	R = 2 e F = 1	Uma compra, já antiga.
`lost`	demais casos	Compra única e muito antiga.

Erros

Status	Quando	Corpo
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`
500	Falha ao calcular	`{"error":"failed to compute RFM summary","detail":"..."}`

Verificar entregabilidade do e-mail

Para um e-mail de marketing chegar à caixa de entrada, o domínio remetente precisa publicar três registros DNS do tipo TXT: SPF (lista quem pode enviar em nome do domínio), DKIM (chave que prova que a mensagem não foi alterada) e DMARC (política do que fazer quando SPF ou DKIM falham). Esta rota consulta o DNS do domínio informado, confere os três e devolve recomendações. Use antes de ligar uma campanha de e-mail.

A consulta é feita na hora, pelo DNS público, e não grava nada. Falha de DNS não vira erro HTTP: o mecanismo vem com ok: false e o motivo em detail.

GET/api/v1/admin/crm/deliverabilityAdmin

Confere SPF, DKIM e DMARC de um domínio

Parâmetros de consulta

domainstringobrigatório

Domínio remetente, como minhaloja.com.br. Espaços nas pontas são removidos e o texto vai para minúsculas.

selectorstringpadrão: default

Seletor DKIM: o prefixo de <seletor>._domainkey.<domínio>. Seu provedor de e-mail informa o seletor correto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/deliverability?domain=minhaloja.com.br&selector=default" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de entregabilidade

json

{
  "domain": "minhaloja.com.br",
  "dkim_selector": "default",
  "spf": { "ok": true, "record": "v=spf1 include:_spf.exemplo.com ~all", "detail": "registro SPF encontrado" },
  "dkim": { "ok": false, "record": "", "detail": "nenhum registro DKIM em default._domainkey.minhaloja.com.br" },
  "dmarc": { "ok": false, "record": "", "detail": "nenhum registro v=DMARC1 em _dmarc.minhaloja.com.br" },
  "recommendations": [
    "Publique a chave DKIM em default._domainkey.minhaloja.com.br (geralmente fornecida pelo provedor de e-mail) e assine as mensagens.",
    "Publique uma política DMARC (TXT \"v=DMARC1; p=none; rua=mailto:dmarc@minhaloja.com.br\") em _dmarc.minhaloja.com.br e evolua p=none → quarantine → reject."
  ],
  "limitations": [
    "IP warm-up não é aplicável: o envio usa o provedor por-tenant (Resend/SMTP/SNS), que controla o pool de IP e a reputação. Não há IP de envio dedicado da Venddor para aquecer."
  ]
}

Campos da resposta

domainstring

Domínio consultado, normalizado.

dkim_selectorstring

Seletor usado (default quando você não enviou).

spfobject

Resultado do SPF: procura um TXT que comece com v=spf1 no próprio domínio.

dkimobject

Resultado do DKIM: procura em <seletor>._domainkey.<domínio> um TXT com v=DKIM1 ou uma chave p=.

dmarcobject

Resultado do DMARC: procura em _dmarc.<domínio> um TXT que comece com v=DMARC1.

spf.okboolean

true quando o registro foi encontrado. O mesmo vale para dkim.ok e dmarc.ok.

spf.recordstring

Texto do registro encontrado; vazio quando não há.

spf.detailstring

Frase em português com o resultado ou o erro de consulta.

recommendationsarray

Lista de ações em português, uma por mecanismo ausente. Se os três existem, vem uma única frase de acompanhamento.

limitationsarray

Avisos fixos. Hoje: o envio usa o provedor configurado na loja, então não existe IP dedicado para aquecer.

Erros

Status	Quando	Corpo
400	`domain` ausente ou vazio	`{"error":"domain query parameter is required"}`
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`

Veja também

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

Indicadores do CRM

Distribuição da base de clientes por segmento RFM e verificação de SPF, DKIM e DMARC do domínio de envio.

Duas leituras de apoio ao marketing: quem são seus clientes (segmentos RFM) e se seus e-mails chegam (autenticação do domínio). Nenhuma das duas altera dados.

Resumo RFM

GET/api/v1/admin/crm/rfm/summaryAdmin

Distribuição de clientes por segmento RFM

Sem parâmetros.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/rfm/summary" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Distribuição por segmento

json

{
  "total_customers": 7186,
  "segments": [
    { "segment": "champions", "customers": 2057, "revenue_cents": 1863039837, "avg_orders": 13.45 },
    { "segment": "loyal", "customers": 30, "revenue_cents": 16654613, "avg_orders": 7.57 },
    { "segment": "potential_loyalist", "customers": 580, "revenue_cents": 72796471, "avg_orders": 1.98 }
  ]
}

A lista real traz sempre os 11 segmentos, na ordem da tabela abaixo; o exemplo mostra só três.

Campos da resposta

total_customersinteger

Clientes com pedido válido (soma de todos os segmentos).

segmentsarray

Um item por segmento, sempre os 11, na mesma ordem. Segmento sem clientes vem com zeros.

segments[].segmentstring

championsloyalpotential_loyalistnew_customerspromisingneed_attentionat_riskcant_losehibernatingabout_to_sleeplost

Rótulo do segmento.

segments[].customersinteger

Clientes no segmento.

segments[].revenue_centsinteger

Soma do valor dos pedidos desses clientes, em centavos.

segments[].avg_ordersnumber

Média de pedidos por cliente do segmento.

Os 11 segmentos

Avaliados na ordem da tabela; o primeiro que casa vale. R é a nota de recência e F a de frequência.

Segmento	Regra (R e F)	Leitura
`champions`	R ≥ 4 e F ≥ 4	Compraram há pouco e compram sempre.
`loyal`	R ≥ 3 e F ≥ 4	Compram com frequência.
`potential_loyalist`	R ≥ 4 e F ≥ 2	Recentes, com mais de uma compra.
`new_customers`	R ≥ 4 e F = 1	Primeira compra recente.
`promising`	R = 3 e F = 1	Compra única, nem tão recente.
`need_attention`	R = 3 e F de 2 a 3	Esfriando.
`cant_lose`	R ≤ 2 e F = 5	Eram os melhores e sumiram.
`at_risk`	R ≤ 2 e F ≥ 3	Compravam bem e pararam.
`hibernating`	R ≤ 2 e F = 2	Poucas compras, antigas.
`about_to_sleep`	R = 2 e F = 1	Uma compra, já antiga.
`lost`	demais casos	Compra única e muito antiga.

Erros

Status	Quando	Corpo
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`
500	Falha ao calcular	`{"error":"failed to compute RFM summary","detail":"..."}`

Verificar entregabilidade do e-mail

A consulta é feita na hora, pelo DNS público, e não grava nada. Falha de DNS não vira erro HTTP: o mecanismo vem com ok: false e o motivo em detail.

GET/api/v1/admin/crm/deliverabilityAdmin

Confere SPF, DKIM e DMARC de um domínio

Parâmetros de consulta

domainstringobrigatório

Domínio remetente, como minhaloja.com.br. Espaços nas pontas são removidos e o texto vai para minúsculas.

selectorstringpadrão: default

Seletor DKIM: o prefixo de <seletor>._domainkey.<domínio>. Seu provedor de e-mail informa o seletor correto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/deliverability?domain=minhaloja.com.br&selector=default" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Relatório de entregabilidade

json

{
  "domain": "minhaloja.com.br",
  "dkim_selector": "default",
  "spf": { "ok": true, "record": "v=spf1 include:_spf.exemplo.com ~all", "detail": "registro SPF encontrado" },
  "dkim": { "ok": false, "record": "", "detail": "nenhum registro DKIM em default._domainkey.minhaloja.com.br" },
  "dmarc": { "ok": false, "record": "", "detail": "nenhum registro v=DMARC1 em _dmarc.minhaloja.com.br" },
  "recommendations": [
    "Publique a chave DKIM em default._domainkey.minhaloja.com.br (geralmente fornecida pelo provedor de e-mail) e assine as mensagens.",
    "Publique uma política DMARC (TXT \"v=DMARC1; p=none; rua=mailto:dmarc@minhaloja.com.br\") em _dmarc.minhaloja.com.br e evolua p=none → quarantine → reject."
  ],
  "limitations": [
    "IP warm-up não é aplicável: o envio usa o provedor por-tenant (Resend/SMTP/SNS), que controla o pool de IP e a reputação. Não há IP de envio dedicado da Venddor para aquecer."
  ]
}

Campos da resposta

domainstring

Domínio consultado, normalizado.

dkim_selectorstring

Seletor usado (default quando você não enviou).

spfobject

Resultado do SPF: procura um TXT que comece com v=spf1 no próprio domínio.

dkimobject

Resultado do DKIM: procura em <seletor>._domainkey.<domínio> um TXT com v=DKIM1 ou uma chave p=.

dmarcobject

Resultado do DMARC: procura em _dmarc.<domínio> um TXT que comece com v=DMARC1.

spf.okboolean

true quando o registro foi encontrado. O mesmo vale para dkim.ok e dmarc.ok.

spf.recordstring

Texto do registro encontrado; vazio quando não há.

spf.detailstring

Frase em português com o resultado ou o erro de consulta.

recommendationsarray

Lista de ações em português, uma por mecanismo ausente. Se os três existem, vem uma única frase de acompanhamento.

limitationsarray

Avisos fixos. Hoje: o envio usa o provedor configurado na loja, então não existe IP dedicado para aquecer.

Erros

Status	Quando	Corpo
400	`domain` ausente ou vazio	`{"error":"domain query parameter is required"}`
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`