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

Audiências

Lista, consulta, cria, altera e exclui as audiências (segmentos de clientes) do marketplace.

Cinco operações cuidam do cadastro das audiências. Elas só mexem na definição (nome e regra); quem monta o grupo de clientes é a materialização. Todas exigem o módulo CRM ligado e valem para o marketplace inteiro: audiências criadas por sellers não aparecem aqui.

Listar audiências

Devolve todas as audiências do marketplace, da mais nova para a mais antiga, sem paginação. Use para montar a tela de seleção de público de uma campanha.

GET/api/v1/admin/crm/audiencesAdmin

Lista as audiências do marketplace

Sem parâmetros.

Exemplo de requisição

bash

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

Resposta

200Audiências retornadas

json

{
  "audiences": [
    {
      "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
      "name": "Fiéis 90d acima de 500",
      "description": "Clientes com compras válidas nos últimos 90 dias somando mais de R$ 500,00",
      "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-11T20:50:28.586707Z",
      "last_error": null,
      "created_at": "2026-09-10T06:04:48.095503Z",
      "updated_at": "2026-10-11T20:50:28.586707Z"
    }
  ]
}

Quando não há nenhuma audiência, audiences vem como null, não como lista vazia. Trate os dois casos.

Campos da resposta

audiences[].iduuid

Identificador da audiência.

audiences[].namestring

Nome.

audiences[].descriptionstring

Descrição livre; pode ser vazia.

audiences[].ruleobject

A regra, como foi gravada. Veja Regras de audiência.

audiences[].usergroup_iduuid

Grupo de clientes criado pela materialização. Ausente até a primeira vez.

audiences[].is_activeboolean

Se a audiência participa da atualização automática.

audiences[].member_countinteger

Membros na última materialização.

audiences[].last_evaluated_atstring

RFC 3339 em UTC da última materialização. Ausente se nunca rodou.

audiences[].last_errorstring

Motivo da última falha de materialização, ou null. Quando o grupo de clientes de uma audiência desapareceu, a audiência é desativada e este campo explica.

audiences[].created_atstring

RFC 3339 em UTC.

audiences[].updated_atstring

RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`
500	Falha interna	`{"error":"failed to list audiences","detail":"..."}`

Consultar uma audiência

Devolve uma audiência pelo id, no mesmo formato de cada item da lista.

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

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

Resposta

200Audiência retornada

json

{
  "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "name": "Fiéis 90d acima de 500",
  "description": "Clientes com compras válidas nos últimos 90 dias somando mais de R$ 500,00",
  "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-11T20:50:28.586707Z",
  "last_error": null,
  "created_at": "2026-09-10T06:04:48.095503Z",
  "updated_at": "2026-10-11T20:50:28.586707Z"
}

Os campos são os mesmos de cada item da lista acima.

Erros

Status	Quando	Corpo
404	Nenhuma audiência com esse id	`{"error":"audience not found"}`
500	`id` que não é UUID válido (não é 400)	`{"error":"failed to get audience","detail":"o valor \"abc\" não é um uuid válido. ..."}`

O texto de detail volta em português.

Criar uma audiência

Grava uma audiência nova no escopo do marketplace. A regra é validada e ensaiada no banco antes de salvar. A audiência nasce sem membros: member_count é 0 e não há usergroup_id até a primeira materialização.

POST/api/v1/admin/crm/audiencesAdmin

Cria uma audiência

Corpo da requisição

namestringobrigatório

Nome da audiência. Texto vazio é recusado.

descriptionstring

Descrição livre.

ruleobject

Regra em JSON, conforme Regras de audiência. Se omitida, vale a regra vazia, que casa com todos os clientes.

is_activebooleanpadrão: true

Se false, a atualização automática ignora a audiência.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/crm/audiences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes de SP",
    "description": "Endereço em São Paulo",
    "rule": {
      "op": "AND",
      "conditions": [
        { "type": "state", "operator": "in", "values": ["SP"] }
      ]
    }
  }'

Resposta

201Audiência criada

json

{
  "id": "1e42d9ad-7dec-4f89-9b62-995fc42310a5",
  "name": "Clientes de SP",
  "description": "Endereço em São Paulo",
  "rule": { "op": "AND", "conditions": [{ "type": "state", "values": ["SP"], "operator": "in" }] },
  "is_active": true,
  "member_count": 0,
  "last_error": null,
  "created_at": "2026-10-11T21:02:16.835596Z",
  "updated_at": "2026-10-11T21:02:16.835596Z"
}

Os campos são os mesmos da consulta. Note que usergroup_id e last_evaluated_at não aparecem ainda.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	Regra inválida (tipo de condição desconhecido, operador fora da lista, valor do tipo errado)	`{"error":"failed to create audience","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`
500	`name` ausente ou vazio (deveria ser 400, mas hoje é 500)	`{"error":"failed to create audience","detail":"crm segments: name is required"}`

Alterar uma audiência

Atualização parcial: só os campos enviados mudam. Se você enviar rule, ela é validada de novo. Mudar a regra não reconstrói o grupo de clientes na hora; a próxima materialização (automática ou manual) aplica a nova regra.

PUT/api/v1/admin/crm/audiences/{id}Admin

Altera uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição. Envie "" para limpar.

ruleobject

Nova regra, que substitui a anterior por inteiro.

is_activeboolean

Liga ou desliga a atualização automática.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/crm/audiences/1e42d9ad-7dec-4f89-9b62-995fc42310a5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta

200Audiência alterada

json

{
  "id": "1e42d9ad-7dec-4f89-9b62-995fc42310a5",
  "name": "Clientes de SP",
  "description": "Endereço em São Paulo",
  "rule": { "op": "AND", "conditions": [{ "type": "state", "values": ["SP"], "operator": "in" }] },
  "usergroup_id": "be7e577f-2d9a-4ff3-afda-34117d7776ad",
  "is_active": false,
  "member_count": 0,
  "last_evaluated_at": "2026-10-11T21:02:16.9Z",
  "last_error": null,
  "created_at": "2026-10-11T21:02:16.835596Z",
  "updated_at": "2026-10-11T21:05:02.1Z"
}

Se o corpo não tiver nenhum campo conhecido, nada muda e a audiência atual é devolvida como está.

Erros

Status	Quando	Corpo
400	Corpo inválido ou regra inválida	`{"error":"failed to update audience","detail":"..."}`
404	Audiência inexistente	`{"error":"audience not found"}`
500	`id` que não é UUID válido	`{"error":"failed to update audience","detail":"..."}`

Excluir uma audiência

Remove a definição. O grupo de clientes criado pela materialização permanece (com os membros que tinha), porque promoções ou outras telas podem estar apontando para ele. Para removê-lo, use a gestão de grupos de clientes.

DELETE/api/v1/admin/crm/audiences/{id}Admin

Exclui uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/crm/audiences/1e42d9ad-7dec-4f89-9b62-995fc42310a5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Audiência excluída

json

{ "deleted": true }

Erros

Status	Quando	Corpo
404	Audiência inexistente (inclusive repetir o DELETE) ou id que não é UUID	`{"error":"failed to delete audience","detail":"crm segments: audience 1e42d9ad-... not found"}`

Veja também

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

Audiências

Lista, consulta, cria, altera e exclui as audiências (segmentos de clientes) do marketplace.

Listar audiências

Devolve todas as audiências do marketplace, da mais nova para a mais antiga, sem paginação. Use para montar a tela de seleção de público de uma campanha.

GET/api/v1/admin/crm/audiencesAdmin

Lista as audiências do marketplace

Sem parâmetros.

Exemplo de requisição

bash

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

Resposta

200Audiências retornadas

json

{
  "audiences": [
    {
      "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
      "name": "Fiéis 90d acima de 500",
      "description": "Clientes com compras válidas nos últimos 90 dias somando mais de R$ 500,00",
      "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-11T20:50:28.586707Z",
      "last_error": null,
      "created_at": "2026-09-10T06:04:48.095503Z",
      "updated_at": "2026-10-11T20:50:28.586707Z"
    }
  ]
}

Quando não há nenhuma audiência, audiences vem como null, não como lista vazia. Trate os dois casos.

Campos da resposta

audiences[].iduuid

Identificador da audiência.

audiences[].namestring

Nome.

audiences[].descriptionstring

Descrição livre; pode ser vazia.

audiences[].ruleobject

A regra, como foi gravada. Veja Regras de audiência.

audiences[].usergroup_iduuid

Grupo de clientes criado pela materialização. Ausente até a primeira vez.

audiences[].is_activeboolean

Se a audiência participa da atualização automática.

audiences[].member_countinteger

Membros na última materialização.

audiences[].last_evaluated_atstring

RFC 3339 em UTC da última materialização. Ausente se nunca rodou.

audiences[].last_errorstring

Motivo da última falha de materialização, ou null. Quando o grupo de clientes de uma audiência desapareceu, a audiência é desativada e este campo explica.

audiences[].created_atstring

RFC 3339 em UTC.

audiences[].updated_atstring

RFC 3339 em UTC.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Módulo CRM desligado	`{"error":"module_disabled","module":"crm"}`
500	Falha interna	`{"error":"failed to list audiences","detail":"..."}`

Consultar uma audiência

Devolve uma audiência pelo id, no mesmo formato de cada item da lista.

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

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

Resposta

200Audiência retornada

json

{
  "id": "509ae709-de06-478a-8bef-5a4d32c6cfb0",
  "name": "Fiéis 90d acima de 500",
  "description": "Clientes com compras válidas nos últimos 90 dias somando mais de R$ 500,00",
  "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-11T20:50:28.586707Z",
  "last_error": null,
  "created_at": "2026-09-10T06:04:48.095503Z",
  "updated_at": "2026-10-11T20:50:28.586707Z"
}

Os campos são os mesmos de cada item da lista acima.

Erros

Status	Quando	Corpo
404	Nenhuma audiência com esse id	`{"error":"audience not found"}`
500	`id` que não é UUID válido (não é 400)	`{"error":"failed to get audience","detail":"o valor \"abc\" não é um uuid válido. ..."}`

O texto de detail volta em português.

Criar uma audiência

POST/api/v1/admin/crm/audiencesAdmin

Cria uma audiência

Corpo da requisição

namestringobrigatório

Nome da audiência. Texto vazio é recusado.

descriptionstring

Descrição livre.

ruleobject

Regra em JSON, conforme Regras de audiência. Se omitida, vale a regra vazia, que casa com todos os clientes.

is_activebooleanpadrão: true

Se false, a atualização automática ignora a audiência.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/crm/audiences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes de SP",
    "description": "Endereço em São Paulo",
    "rule": {
      "op": "AND",
      "conditions": [
        { "type": "state", "operator": "in", "values": ["SP"] }
      ]
    }
  }'

Resposta

201Audiência criada

json

{
  "id": "1e42d9ad-7dec-4f89-9b62-995fc42310a5",
  "name": "Clientes de SP",
  "description": "Endereço em São Paulo",
  "rule": { "op": "AND", "conditions": [{ "type": "state", "values": ["SP"], "operator": "in" }] },
  "is_active": true,
  "member_count": 0,
  "last_error": null,
  "created_at": "2026-10-11T21:02:16.835596Z",
  "updated_at": "2026-10-11T21:02:16.835596Z"
}

Os campos são os mesmos da consulta. Note que usergroup_id e last_evaluated_at não aparecem ainda.

Erros

Status	Quando	Corpo
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
400	Regra inválida (tipo de condição desconhecido, operador fora da lista, valor do tipo errado)	`{"error":"failed to create audience","detail":"crm segments: regra de audiência inválida: crm segments: unsupported condition type \"foo\""}`
500	`name` ausente ou vazio (deveria ser 400, mas hoje é 500)	`{"error":"failed to create audience","detail":"crm segments: name is required"}`

Alterar uma audiência

PUT/api/v1/admin/crm/audiences/{id}Admin

Altera uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição. Envie "" para limpar.

ruleobject

Nova regra, que substitui a anterior por inteiro.

is_activeboolean

Liga ou desliga a atualização automática.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/crm/audiences/1e42d9ad-7dec-4f89-9b62-995fc42310a5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta

200Audiência alterada

json

{
  "id": "1e42d9ad-7dec-4f89-9b62-995fc42310a5",
  "name": "Clientes de SP",
  "description": "Endereço em São Paulo",
  "rule": { "op": "AND", "conditions": [{ "type": "state", "values": ["SP"], "operator": "in" }] },
  "usergroup_id": "be7e577f-2d9a-4ff3-afda-34117d7776ad",
  "is_active": false,
  "member_count": 0,
  "last_evaluated_at": "2026-10-11T21:02:16.9Z",
  "last_error": null,
  "created_at": "2026-10-11T21:02:16.835596Z",
  "updated_at": "2026-10-11T21:05:02.1Z"
}

Se o corpo não tiver nenhum campo conhecido, nada muda e a audiência atual é devolvida como está.

Erros

Status	Quando	Corpo
400	Corpo inválido ou regra inválida	`{"error":"failed to update audience","detail":"..."}`
404	Audiência inexistente	`{"error":"audience not found"}`
500	`id` que não é UUID válido	`{"error":"failed to update audience","detail":"..."}`

Excluir uma audiência

DELETE/api/v1/admin/crm/audiences/{id}Admin

Exclui uma audiência

Parâmetros de caminho

iduuidobrigatório

Id da audiência.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/crm/audiences/1e42d9ad-7dec-4f89-9b62-995fc42310a5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Audiência excluída

json

{ "deleted": true }

Erros

Status	Quando	Corpo
404	Audiência inexistente (inclusive repetir o DELETE) ou id que não é UUID	`{"error":"failed to delete audience","detail":"crm segments: audience 1e42d9ad-... not found"}`