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

Ações de audiência

Prévia de uma regra, materialização do grupo de clientes, estatísticas de receita e exportação dos membros em CSV.

Quatro operações trabalham sobre a regra de uma audiência sem alterar sua definição: contar quem uma regra alcança, sincronizar o grupo de clientes, medir o resultado e baixar a lista de contatos.

Prévia de uma regra

Conta quantos clientes uma regra alcança sem salvar nada. Use enquanto o usuário monta a regra, para mostrar "esta regra alcança 4.597 clientes" antes de criar a audiência. A regra é avaliada contra os dados atuais da loja, com o mesmo motor da materialização.

POST/api/v1/admin/crm/audiences/previewAdmin

Conta os clientes que uma regra alcança

Corpo da requisição

ruleobjectobrigatório

Regra em JSON. Veja Regras de audiência. Uma regra sem condições devolve o total de clientes da loja.

Exemplo de requisição

bash

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

Resposta

200Contagem

json

{ "count": 4597 }

Campos da resposta

countinteger

Clientes que casam com a regra neste momento.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Regra inválida	`{"error":"failed to evaluate rule","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`
500	Falha de banco ao contar	`{"error":"failed to evaluate rule","detail":"..."}`

Materializar uma audiência

Sincroniza agora o grupo de clientes da audiência com o resultado atual da regra. Na primeira vez, cria o grupo CRM: <nome> e grava o usergroup_id na audiência. Nas seguintes, adiciona quem passou a casar e remove quem deixou de casar. Devolve o tamanho final.

A plataforma já faz isso sozinha, a cada 15 minutos, para audiências com is_active: true. Chame esta rota quando precisar do grupo atualizado agora (por exemplo, logo antes de disparar uma campanha). Funciona também em audiência inativa.

POST/api/v1/admin/crm/audiences/{id}/materializeAdmin

Sincroniza o grupo de clientes da audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/materialize" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grupo sincronizado

json

{ "audience_id": "509ae709-de06-478a-8bef-5a4d32c6cfb0", "member_count": 846 }

Campos da resposta

audience_iduuid

A audiência sincronizada.

member_countinteger

Membros ativos do grupo depois da sincronização. Também é gravado na audiência, junto de last_evaluated_at, e last_error volta a null.

Erros

Status	Quando	Corpo
404	Audiência inexistente	`{"error":"audience not found"}`
400	A regra gravada não é processável pelo motor	`{"error":"failed to materialize audience","detail":"..."}`
409	O grupo de clientes ligado à audiência foi apagado fora da plataforma. A audiência é desativada e o motivo vai para `last_error`	`{"error":"failed to materialize audience","detail":"..."}`
500	Falha interna	`{"error":"failed to materialize audience","detail":"..."}`

Estatísticas de uma audiência

Resume o tamanho e o desempenho: quantos clientes há agora, quantas campanhas usaram a audiência, quantas mensagens saíram e quanto de receita foi atribuído a elas. A atribuição é a do último toque, a mesma do funil de campanhas.

GET/api/v1/admin/crm/audiences/{id}/statsAdmin

Tamanho e receita atribuída de uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estatísticas

json

{
  "audience_id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "member_count": 846,
  "live_count": 846,
  "campaigns": 0,
  "total_sent": 0,
  "total_converted": 0,
  "attributed_revenue_cents": 0
}

Campos da resposta

audience_iduuid

A audiência.

member_countinteger

Tamanho gravado na última materialização.

live_countinteger

Tamanho recalculado agora pela regra. Se o recálculo falhar, repete member_count.

campaignsinteger

Campanhas do marketplace que usaram esta audiência.

total_sentinteger

Mensagens enviadas (status sent) por essas campanhas.

total_convertedinteger

Pedidos distintos atribuídos a essas campanhas.

attributed_revenue_centsinteger

Receita atribuída, em centavos.

Erros

Status	Quando	Corpo
404	Audiência inexistente (ou id que não é UUID)	`{"error":"audience not found","detail":"..."}`

Exportar membros em CSV

Baixa os clientes que a regra alcança agora, em CSV, para usar em uma ferramenta externa. A lista vem da avaliação ao vivo da regra, então não depende de a audiência ter sido materializada. É enviada em fluxo, linha a linha, e aguenta bases grandes.

GET/api/v1/admin/crm/audiences/{id}/exportAdmin

Exporta os membros da audiência em CSV

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o audiencia.csv

Resposta

200CSV dos membros

text

id,email,name,phone
10770e58-19ab-4f74-9540-ad12ac164dff,aline.almeida@example.com,Aline Almeida,+5541999990000
d6f7bbe2-7a25-4d0a-b11d-7bb906fc2537,bruno.lima@example.com,Bruno Lima,+5531999990001

A resposta é text/csv; charset=utf-8, com Content-Disposition: attachment; filename="audience-<id>.csv" e Cache-Control: no-store. As linhas vêm ordenadas por e-mail.

Colunas do CSV

iduuid

Id do cliente.

emailstring

E-mail; vazio se o cadastro não tiver.

namestring

Nome e sobrenome juntos.

phonestring

Telefone do cadastro; vazio se não tiver.

Erros

Status	Quando	Corpo
404	Audiência inexistente ou id que não é UUID	`{"error":"failed to export audience","detail":"..."}`

Veja também

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

Ações de audiência

Prévia de uma regra, materialização do grupo de clientes, estatísticas de receita e exportação dos membros em CSV.

Prévia de uma regra

POST/api/v1/admin/crm/audiences/previewAdmin

Conta os clientes que uma regra alcança

Corpo da requisição

ruleobjectobrigatório

Regra em JSON. Veja Regras de audiência. Uma regra sem condições devolve o total de clientes da loja.

Exemplo de requisição

bash

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

Resposta

200Contagem

json

{ "count": 4597 }

Campos da resposta

countinteger

Clientes que casam com a regra neste momento.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Regra inválida	`{"error":"failed to evaluate rule","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`
500	Falha de banco ao contar	`{"error":"failed to evaluate rule","detail":"..."}`

Materializar uma audiência

POST/api/v1/admin/crm/audiences/{id}/materializeAdmin

Sincroniza o grupo de clientes da audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Sem corpo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/materialize" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Grupo sincronizado

json

{ "audience_id": "509ae709-de06-478a-8bef-5a4d32c6cfb0", "member_count": 846 }

Campos da resposta

audience_iduuid

A audiência sincronizada.

member_countinteger

Membros ativos do grupo depois da sincronização. Também é gravado na audiência, junto de last_evaluated_at, e last_error volta a null.

Erros

Status	Quando	Corpo
404	Audiência inexistente	`{"error":"audience not found"}`
400	A regra gravada não é processável pelo motor	`{"error":"failed to materialize audience","detail":"..."}`
409	O grupo de clientes ligado à audiência foi apagado fora da plataforma. A audiência é desativada e o motivo vai para `last_error`	`{"error":"failed to materialize audience","detail":"..."}`
500	Falha interna	`{"error":"failed to materialize audience","detail":"..."}`

Estatísticas de uma audiência

GET/api/v1/admin/crm/audiences/{id}/statsAdmin

Tamanho e receita atribuída de uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/stats" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Estatísticas

json

{
  "audience_id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "member_count": 846,
  "live_count": 846,
  "campaigns": 0,
  "total_sent": 0,
  "total_converted": 0,
  "attributed_revenue_cents": 0
}

Campos da resposta

audience_iduuid

A audiência.

member_countinteger

Tamanho gravado na última materialização.

live_countinteger

Tamanho recalculado agora pela regra. Se o recálculo falhar, repete member_count.

campaignsinteger

Campanhas do marketplace que usaram esta audiência.

total_sentinteger

Mensagens enviadas (status sent) por essas campanhas.

total_convertedinteger

Pedidos distintos atribuídos a essas campanhas.

attributed_revenue_centsinteger

Receita atribuída, em centavos.

Erros

Status	Quando	Corpo
404	Audiência inexistente (ou id que não é UUID)	`{"error":"audience not found","detail":"..."}`

Exportar membros em CSV

GET/api/v1/admin/crm/audiences/{id}/exportAdmin

Exporta os membros da audiência em CSV

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/crm/audiences/509ae709-de06-478a-8bef-5a4d32c6cfb0/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o audiencia.csv

Resposta

200CSV dos membros

text

id,email,name,phone
10770e58-19ab-4f74-9540-ad12ac164dff,aline.almeida@example.com,Aline Almeida,+5541999990000
d6f7bbe2-7a25-4d0a-b11d-7bb906fc2537,bruno.lima@example.com,Bruno Lima,+5531999990001

A resposta é text/csv; charset=utf-8, com Content-Disposition: attachment; filename="audience-<id>.csv" e Cache-Control: no-store. As linhas vêm ordenadas por e-mail.

Colunas do CSV

iduuid

Id do cliente.

emailstring

E-mail; vazio se o cadastro não tiver.

namestring

Nome e sobrenome juntos.

phonestring

Telefone do cadastro; vazio se não tiver.

Erros

Status	Quando	Corpo
404	Audiência inexistente ou id que não é UUID	`{"error":"failed to export audience","detail":"..."}`