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

Audiências

Lista, cria, lê, altera e exclui as audiências do seller.

Listar audiências

Devolve todas as audiências do seu seller, da mais nova para a mais antiga. Não há paginação nem filtros.

GET/api/v1/vendor/crm/audiencesSeller

Listar as audiências do seller

Cabeçalhos

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

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/crm/audiences" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Audiências
json
{
  "audiences": [
    {
      "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
      "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
      "name": "Clientes fiéis dos últimos 90 dias",
      "description": "Compraram mais de R$ 500,00 nos últimos 90 dias",
      "rule": {
        "op": "AND",
        "conditions": [
          {
            "type": "total_spent",
            "operator": "gte",
            "value": 50000,
            "window_days": 90
          }
        ]
      },
      "usergroup_id": "c905980d-d6be-49c6-858e-e2dd7daaf151",
      "is_active": true,
      "member_count": 846,
      "last_evaluated_at": "2026-10-11T21:33:19.003894Z",
      "last_error": null,
      "created_at": "2026-09-10T06:04:48.095503Z",
      "updated_at": "2026-10-11T21:33:19.003894Z"
    }
  ]
}

Campos da resposta

audiencesarray
Audiências, cada uma com os campos de Ler uma audiência. Lista vazia vira null quando não há nenhuma.

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"}
500Falha ao consultar.{"error":"failed to list audiences"}
Lista vazia

Sem nenhuma audiência o campo audiences volta como null, não como []. Trate os dois casos.

Veja também

  • Criar uma audiência
  • Regras de segmentação

Criar uma audiência

Grava uma audiência nova. O servidor compila a regra e testa a consulta no banco antes de gravar: regra que não roda é recusada com 400. A audiência nasce ativa e vazia; chame a materialização para preencher o grupo.

POST/api/v1/vendor/crm/audiencesSeller

Criar uma audiência

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

namestringobrigatório
Nome da audiência.
descriptionstring
Descrição livre.
ruleobject
Regra (ver Regras de segmentação). Omitida, vira um grupo AND sem condições, que casa todos os clientes.
is_activebooleanpadrão: true
Se a audiência nasce ativa.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/crm/audiences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes fiéis dos últimos 90 dias",
  "description": "Compraram mais de R$ 500,00 nos últimos 90 dias",
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  }
}'

Resposta

201Audiência criada
json
{
  "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "name": "Clientes fiéis dos últimos 90 dias",
  "description": "Compraram mais de R$ 500,00 nos últimos 90 dias",
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  },
  "is_active": true,
  "member_count": 0,
  "last_error": null,
  "created_at": "2026-09-10T06:04:48.095503Z",
  "updated_at": "2026-10-11T21:33:19.003894Z"
}

Campos da resposta

iduuid
Id da audiência.
vendor_iduuid
Seller dono da audiência. Sempre o seu seller nestas rotas.
namestring
Nome da audiência.
descriptionstring
Descrição livre.
ruleobject
A regra gravada, no formato de Regras de segmentação.
usergroup_iduuid
Grupo de clientes em que a audiência foi materializada. Ausente até a primeira materialização.
is_activeboolean
false desliga a audiência (a rotina automática deixa de reavaliá-la).
member_countinteger
Quantidade de clientes na última materialização. 0 antes da primeira.
last_evaluated_atstring
RFC 3339. Última reavaliação. Ausente antes da primeira.
last_errorstring
Motivo da última falha ao materializar, em texto para o lojista. null quando não há falha.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.

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"}
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
400Regra inválida: condição desconhecida, operador fora da lista ou valor do tipo errado. A mensagem (detail) está em inglês e cita a condição e o campo.{"error":"failed to create audience","detail":"crm segments: regra de audiência inválida: ..."}
500name vazio ou ausente (deveria ser 400).{"error":"failed to create audience","detail":"crm segments: name is required"}
Regra vazia casa todo mundo

Sem rule, ou com conditions vazio, a audiência alcança todos os clientes ativos. Use a prévia antes de gravar.

Veja também

  • Materializar
  • Regras de segmentação

Ler uma audiência

Devolve uma audiência do seu seller pelo id.

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

Ler uma audiência

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" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Audiência
json
{
  "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "name": "Clientes fiéis dos últimos 90 dias",
  "description": "Compraram mais de R$ 500,00 nos últimos 90 dias",
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  },
  "usergroup_id": "c905980d-d6be-49c6-858e-e2dd7daaf151",
  "is_active": true,
  "member_count": 846,
  "last_evaluated_at": "2026-10-11T21:33:19.003894Z",
  "last_error": null,
  "created_at": "2026-09-10T06:04:48.095503Z",
  "updated_at": "2026-10-11T21:33:19.003894Z"
}

Campos da resposta

iduuid
Id da audiência.
vendor_iduuid
Seller dono da audiência. Sempre o seu seller nestas rotas.
namestring
Nome da audiência.
descriptionstring
Descrição livre.
ruleobject
A regra gravada, no formato de Regras de segmentação.
usergroup_iduuid
Grupo de clientes em que a audiência foi materializada. Ausente até a primeira materialização.
is_activeboolean
false desliga a audiência (a rotina automática deixa de reavaliá-la).
member_countinteger
Quantidade de clientes na última materialização. 0 antes da primeira.
last_evaluated_atstring
RFC 3339. Última reavaliação. Ausente antes da primeira.
last_errorstring
Motivo da última falha ao materializar, em texto para o lojista. null quando não há falha.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.

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"}
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. ..."}

Alterar uma audiência

Atualiza só os campos enviados (alteração parcial, apesar do PUT). Uma rule nova é validada como na criação. A mudança não altera o grupo de clientes: materialize de novo para aplicar.

PUT/api/v1/vendor/crm/audiences/{id}Seller

Alterar uma audiência

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.

Parâmetros de caminho

iduuidobrigatório
Id da audiência.

Corpo da requisição

namestring
Novo nome. Omitido, não muda.
descriptionstring
Nova descrição. "" apaga.
ruleobject
Nova regra. Omitida, não muda.
is_activeboolean
Liga ou desliga a audiência.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "is_active": false
}'

Resposta

200Audiência alterada
json
{
  "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "vendor_id": "7c1f0b52-3a64-4d1e-9a40-5f0c2b6a91d3",
  "name": "Clientes fiéis dos últimos 90 dias",
  "description": "Compraram mais de R$ 500,00 nos últimos 90 dias",
  "rule": {
    "op": "AND",
    "conditions": [
      {
        "type": "total_spent",
        "operator": "gte",
        "value": 50000,
        "window_days": 90
      }
    ]
  },
  "usergroup_id": "c905980d-d6be-49c6-858e-e2dd7daaf151",
  "is_active": false,
  "member_count": 846,
  "last_evaluated_at": "2026-10-11T21:33:19.003894Z",
  "last_error": null,
  "created_at": "2026-09-10T06:04:48.095503Z",
  "updated_at": "2026-10-11T21:33:19.003894Z"
}

Campos da resposta

iduuid
Id da audiência.
vendor_iduuid
Seller dono da audiência. Sempre o seu seller nestas rotas.
namestring
Nome da audiência.
descriptionstring
Descrição livre.
ruleobject
A regra gravada, no formato de Regras de segmentação.
usergroup_iduuid
Grupo de clientes em que a audiência foi materializada. Ausente até a primeira materialização.
is_activeboolean
false desliga a audiência (a rotina automática deixa de reavaliá-la).
member_countinteger
Quantidade de clientes na última materialização. 0 antes da primeira.
last_evaluated_atstring
RFC 3339. Última reavaliação. Ausente antes da primeira.
last_errorstring
Motivo da última falha ao materializar, em texto para o lojista. null quando não há falha.
created_atstring
RFC 3339.
updated_atstring
RFC 3339.

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"}
400Corpo que não é JSON.{"error":"invalid request body","detail":"..."}
400Regra inválida: condição desconhecida, operador fora da lista ou valor do tipo errado. A mensagem (detail) está em inglês e cita a condição e o campo.{"error":"failed to create audience","detail":"crm segments: regra de audiência inválida: ..."}
404A audiência não existe ou pertence a outro seller ou à loja.{"error":"audience not found"}
409A audiência aponta para um grupo de clientes que foi apagado. É preciso reparar antes de voltar a rodar.{"error":"failed to update 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. ..."}
Corpo vazio

Um corpo {} não altera nada e devolve a audiência como está.

Excluir uma audiência

Apaga a definição da audiência. O grupo de clientes que ela criou permanece, para não quebrar o que já usa esse grupo; só o vínculo se desfaz.

DELETE/api/v1/vendor/crm/audiences/{id}Seller

Excluir uma audiência

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 DELETE "$BASE_URL/api/v1/vendor/crm/audiences/$AUDIENCE_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Excluída
json
{
  "deleted": true
}

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.{"error":"failed to delete audience","detail":"crm segments: audience ... not found"}
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. ..."}
Irreversível

Não há como restaurar a audiência. Campanhas que apontavam para ela perdem o público.

Anterior
CRM: audiências e RFM
Próxima
Regras de segmentação
Nesta página
  • Listar audiências
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
  • Criar uma audiência
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
  • Ler uma audiência
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma audiência
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir uma audiência
  • Exemplo de requisição
  • Resposta
  • Erros