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

bash

curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/materialize" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Materializada

json

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

Campos da resposta

audience_iduuid

Id da audiência.

member_countinteger

Clientes no grupo depois da sincronização.

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"}`
404	A audiência não existe ou pertence a outro seller ou à loja.	`{"error":"audience not found"}`
400	A regra gravada não é mais executável.	`{"error":"failed to materialize audience","detail":"..."}`
409	O grupo de clientes da audiência foi apagado.	`{"error":"failed to materialize audience","detail":"..."}`
500	O `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. ..."}`

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

bash

curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/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

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

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"}`
404	A 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

bash

curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o audiencia.csv

Resposta

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

json

id,email,name,phone
10770e58-19ab-4f74-9540-ad12ac164dff,maria.souza@example.com,Maria Souza,+5511987654321

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

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"}`
404	Audiê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"}`

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

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

bash

curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/materialize" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Materializada

json

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

Campos da resposta

audience_iduuid

Id da audiência.

member_countinteger

Clientes no grupo depois da sincronização.

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"}`
404	A audiência não existe ou pertence a outro seller ou à loja.	`{"error":"audience not found"}`
400	A regra gravada não é mais executável.	`{"error":"failed to materialize audience","detail":"..."}`
409	O grupo de clientes da audiência foi apagado.	`{"error":"failed to materialize audience","detail":"..."}`
500	O `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. ..."}`

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

bash

curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/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

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

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"}`
404	A audiência não existe ou pertence a outro seller ou à loja.	`{"error":"audience not found"}`

Exportar contatos

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

bash

curl "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID/export" \
  -H "Authorization: Bearer $TOKEN" \
  -o audiencia.csv

Resposta

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

json

id,email,name,phone
10770e58-19ab-4f74-9540-ad12ac164dff,maria.souza@example.com,Maria Souza,+5511987654321

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

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"}`
404	Audiê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"}`