Apoio às condições

Endpoints auxiliares para montar e conferir condições que envolvem clientes, localização e categorias.

Buscar clientes

POST /api/promotions/customers

Permissão: Cadastro de promoções — visualização

Pesquisa clientes da loja por filtros combináveis. Use-o para pré-visualizar quem será atingido pela condição de clientes específicos: o objeto de filtro enviado aqui é o mesmo que vai dentro da condição.

Corpo da requisição

Todos os campos são opcionais. Valores fora das faixas e listas acima retornam 400 (VALIDATION_FAILED). Os clientes informados em customersId entram no resultado mesmo que já estejam vinculados à condição.

Conjunto de filtros (filtersGroup[])

🚧

Faixas precisam dos dois limites

Em averagePrice, registrationDate e nas datas de lastPurchase (sem dateFilter), informe os dois limites ou nenhum. Com só um dos limites, o filtro não funciona como esperado (em geral não encontra nenhum cliente). Para “a partir de R$ 300”, use um máximo bem acima de qualquer ticket médio possível: o ticket médio considera todos os pedidos do cliente e pode passar do maior valor de Faixa de valor de pedidos.

Exemplo

{
  "customersId": [501],
  "filtersGroup": [
    {
      "lastPurchase": { "purchaseSituation": true, "dateFilter": 5 },
      "averagePrice": { "minValue": 300, "maxValue": 1000000 },
      "states": ["SP", "RJ"]
    }
  ],
  "page": 1, "limit": 10, "orderBy": "name", "orderDirection": 1
}

Clientes de SP ou RJ que compraram nos últimos 6 meses com ticket médio a partir de R$ 300, mais o cliente 501.

Resposta 200

{
  "data": [ { "customerId": 501, "name": "Maria Souza", "email": "[email protected]" } ],
  "total": 842, "totalGeneral": 15230, "page": 1, "limit": 10
}

total é a quantidade de clientes que atendem à busca; totalGeneral, o total de clientes da loja. Resultados idênticos podem vir de cache por até 5 minutos.

Estados

GET /api/promotions/customers/states

Permissão: Cadastro de promoções — visualização

Lista os estados brasileiros. Use stateId na condição de estado (argumento 9) e abbreviation no filtro states da busca de clientes.

{ "data": [ { "stateId": 25, "name": "São Paulo", "abbreviation": "SP" } ] }

Cidades

GET /api/promotions/customers/cities

Permissão: Cadastro de promoções — visualização

Lista as cidades presentes nos endereços cadastrados na loja, no formato aceito pelo filtro cities.

{ "data": [ { "city": "Campinas - SP" } ] }

Faixa de valor de pedidos

GET /api/promotions/customers/averagePurchasePrice

Permissão: Cadastro de promoções — visualização

Retorna o menor e o maior valor de pedido da loja, em reais inteiros. Pedidos cancelados e em algumas outras situações não entram. Útil para definir a faixa de averagePrice.

{ "data": { "minValue": 12, "maxValue": 8450 } }

Clientes de uma condição

GET /api/promotions/{promotionId}/conditions/{conditionPromotionId}/customers

Permissão: Cadastro de promoções — visualização

Lista os clientes vinculados a uma condição de clientes específicos já salva. Um conditionPromotionId desatualizado (anterior ao último PUT) retorna lista vazia, não 404.

{ "data": [ { "customerId": 501, "name": "Maria Souza", "email": "[email protected]" } ], "total": 1, "totalGeneral": 842, "page": 1, "limit": 50 }

Categorias de uma condição

GET /api/promotions/{promotionId}/conditions/{conditionPromotionId}/categories

Permissão: Cadastro de promoções — visualização

Lista, com nome e situação, as categorias usadas por uma condição de categoria (subgrupos 10, 21, 22 e 23).

{ "data": [ { "categoryId": 15, "name": "Camisetas", "active": true } ], "total": 1, "totalGeneral": 2, "page": 1, "limit": 10 }

Categorias de um desconto

GET /api/promotions/{promotionId}/actions/{discountPromotionId}/categories

Permissão: Cadastro de promoções — visualização

Mesma resposta do endpoint anterior, para descontos aplicados a categorias: percentual em categorias e preço fixo por quantidade em categorias. Informe o discountPromotionId obtido em Obter promoção. Aceita search, page e limit (1 a 100, padrão 10).

Permissão de divulgação

POST /api/promotions/disclosure-permission

Permissão: Cadastro de promoções — visualização

Informa se um conjunto de condições permite selos e textos de divulgação. Se alguma condição não permitir, envie stamps e disclosure vazios na promoção.

{ "conditions": [ { "conditionGroup": 1, "conditionSubGroup": 1, "logicOperator": { "id": 1, "arguments": [ { "id": 7, "values": ["true"] } ] } } ] }

Resposta 200

{ "data": { "allowsDisclosure": false } }