VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/CRM: audiências e RFM

Materializar e exportar

Sincroniza o grupo de clientes de uma audiência, mostra o tamanho e a receita atribuída a campanhas e exporta os contatos em CSV.

Materializar

Avalia a regra agora e sincroniza o resultado com o grupo de clientes da audiência: quem passou a casar entra, quem deixou de casar sai. Na primeira vez o grupo é criado. Atualiza member_count, last_evaluated_at e limpa last_error. A operação roda numa única transação.

POST/api/v1/vendor/crm/audiences/{id}/materializeSeller

Sincronizar o grupo de clientes

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da audiência.

Exemplo de requisição

Resposta

200Materializada

Campos da resposta

audience_iduuid
Id da audiência.
member_countinteger
Clientes no grupo depois da sincronização.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"vendor profile not found"}
403O módulo crm está desligado nesta loja.{"error":"module_disabled","module":"crm"}
404A audiência não existe ou pertence a outro seller ou à loja.{"error":"audience not found"}
400A regra gravada não é mais executável.{"error":"failed to materialize audience","detail":"..."}
409O grupo de clientes da audiência foi apagado.{"error":"failed to materialize audience","detail":"..."}
500O id não é um UUID válido (a plataforma responde 500 em vez de 400). A mensagem volta em português.{"error":"failed to get audience","detail":"o valor \"xyz\" não é um uuid válido. ..."}
Também roda sozinha

Uma rotina automática reavalia periodicamente as audiências ativas. Chamar esta rota força a atualização imediata, por exemplo logo antes de disparar uma campanha.

Estatísticas

Resume o desempenho da audiência: tamanho guardado, tamanho recalculado agora e o resultado das campanhas do seller que usaram essa audiência.

GET/api/v1/vendor/crm/audiences/{id}/statsSeller

Tamanho e receita atribuída

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da audiência.

Exemplo de requisição

Resposta

200Estatísticas

Campos da resposta

audience_iduuid
Id da audiência.
member_countinteger
Tamanho da última materialização.
live_countinteger
Tamanho recalculado agora. Se o cálculo falhar, repete member_count.
campaignsinteger
Campanhas do seller que usaram a audiência.
total_sentinteger
Mensagens enviadas por essas campanhas.
total_convertedinteger
Pedidos atribuídos às campanhas (última interação).
attributed_revenue_centsinteger
Receita atribuída, em centavos.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"vendor profile not found"}
403O módulo crm está desligado nesta loja.{"error":"module_disabled","module":"crm"}
404A audiência não existe ou pertence a outro seller ou à loja.{"error":"audience not found"}

Exportar contatos

Baixa os clientes que a regra alcança neste momento como arquivo CSV, linha a linha (sem carregar tudo na memória), ordenado por e-mail. A regra é reavaliada na hora; não é preciso materializar antes.

GET/api/v1/vendor/crm/audiences/{id}/exportSeller

Baixar os contatos em CSV

Cabeçalhos

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

Parâmetros de caminho

iduuidobrigatório
Id da audiência.

Exemplo de requisição

Resposta

200Arquivo CSV (`text/csv`, anexo `audience-{id}.csv`)

Colunas do CSV

iduuid
Coluna 1: id do cliente.
emailstring
Coluna 2: e-mail. Vazio se não houver.
namestring
Coluna 3: nome e sobrenome.
phonestring
Coluna 4: telefone. Vazio se não houver.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} / {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
403O cadastro do seller ainda está em análise (só a tela de cadastro funciona até a aprovação).{"error":"vendor_pending_review","message":"..."}
403O usuário tem papel de seller, mas não está ligado a nenhum seller.{"error":"vendor profile not found"}
403O módulo crm está desligado nesta loja.{"error":"module_disabled","module":"crm"}
404Audiência inexistente ou de outro seller (o corpo vem como JSON, mesmo com o cabeçalho de CSV).{"error":"failed to export audience","detail":"audience ... not found"}
Dados pessoais (LGPD)

O arquivo traz e-mail e telefone de clientes. Use só para o fim da campanha e respeite quem não aceitou marketing: filtre por marketing_consent na regra.

Anterior
Regras de segmentação
Próxima
Resumo RFM
Nesta página
  • Materializar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Estatísticas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar contatos
  • Exemplo de requisição
  • Resposta
  • Erros
bash
curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/materialize" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/stats" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o audiencia.csv
json
{
  "audience_id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "member_count": 846
}
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
}
json
id,email,name,phone
10770e58-19ab-4f74-9540-ad12ac164dff,maria.souza@example.com,Maria Souza,+5511987654321