---
title: "Buscar clientes"
method: POST
path: "/api/promotions/customers"
tags: ["Admin API · Promoções"]
---

# Buscar clientes

`POST /api/promotions/customers`

## Request

- Base URL: `https://sualoja.commerce-wake.tech`
- URL: `https://sualoja.commerce-wake.tech/api/promotions/customers`
- Auth: HTTP bearer

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. Use um único
conjunto em `filtersGroup` por busca e confira o resultado antes de salvar.
            
Permissão: **Cadastro de promoções — visualização**.

## Headers

- `x-api-version` '2.0', required

## Request body

- GetPromotionCustomersQuery
  - `promotionId` integer, nullable: Junto com `conditionId`, identifica uma condição de clientes já salva; os clientes já vinculados a ela ficam fora do resultado dos filtros.
  - `conditionId` integer, nullable: `conditionPromotionId` da condição de clientes (de Obter promoção).
  - `linkedCustomers` boolean, nullable: `true`: inclui no resultado os clientes já vinculados à condição informada. `false` sem `filtersGroup`: retorna todos os clientes da loja.
  - `searchSelected` string, nullable: Busca por nome ou e-mail dentro do resultado.
  - `page` integer: Página, de 1 a 9999. Padrão: 1.
  - `limit` integer: Itens por página, de 1 a 100. Padrão: 10.
  - `orderBy` string, nullable: `customerId`, `name` ou `email`, sem diferenciar maiúsculas. Padrão: `customerId`.
  - `orderDirection` integer: 1 crescente, -1 decrescente. Padrão: 1.
  - `customersId` integer[], nullable: Clientes incluídos individualmente, além dos que atenderem aos filtros.
  - `customersId_Neq` integer[], nullable: Clientes removidos do resultado final.
  - `filtersGroup` PromotionCustomersFilters[], nullable: Conjuntos de filtros. Dentro de um conjunto, todos os filtros preenchidos se aplicam. Use um único conjunto por busca.
    - `search` string, nullable: ID, nome, e-mail, CPF ou CNPJ.
    - `customersIdFilter_Neq` integer[], nullable: Clientes desconsiderados neste conjunto.
    - `fieldsGroups` integer[], nullable: IDs de campos de informação cadastral (`fieldId` de GET /api/informationsgroups/fields).
    - `valuesGroups` string[], nullable: Valores aceitos para esses campos (de GET /api/informationsgroups/fields/values).
    - `lastPurchase` PromotionCustomersLastPurchase
      - `purchaseSituation` boolean, nullable: `true` = comprou no período, `false` = não comprou, `null` = ignora o filtro inteiro.
      - `dateFilter` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13
      - `startDate` string, date-time, nullable: Início do período. Sem `dateFilter`, informe as duas datas.
      - `endDate` string, date-time, nullable: Fim do período. Sem `dateFilter`, informe as duas datas.
    - `averagePrice` PromotionCustomersAveragePrice
      - `minValue` number, double, nullable: Ticket médio mínimo.
      - `maxValue` number, double, nullable: Ticket médio máximo.
    - `states` string[], nullable: UFs do endereço residencial (ex.: "SP"), como em `abbreviation` de GET /api/promotions/customers/states.
    - `cities` string[], nullable: Cidades no formato "Cidade - UF", como retornadas por GET /api/promotions/customers/cities. Com cidades e estados no mesmo conjunto, o cliente entra se estiver em uma das cidades ou em um dos estados.
    - `registrationDate` PromotionCustomersRegistrationDate
      - `startDate` string, date-time, nullable: Início da faixa de data de cadastro.
      - `endDate` string, date-time, nullable: Fim da faixa de data de cadastro.

## Response `200`

Página de clientes.

- ListingResponseDTOGetPromotionCustomersQueryDTO
  - `data` GetPromotionCustomersQueryDTO[], nullable: Itens da página.
    - `customerId` integer: ID do cliente.
    - `name` string, nullable: Nome do cliente.
    - `email` string, nullable: E-mail do cliente.
  - `total` integer, nullable: Total informado pela listagem. Nas rotas de apoio de promoções é a quantidade de itens desta página; o total geral fica em `totalGeneral`.
  - `totalGeneral` integer, nullable: Total de itens que atendem aos filtros, em todas as páginas.
  - `totalActive` integer, nullable: Total de itens ativos, quando a listagem informa.
  - `totalInactive` integer, nullable: Total de itens inativos, quando a listagem informa.
  - `totalArchived` integer, nullable: Total de itens arquivados, quando a listagem informa.
  - `limit` integer, nullable: Tamanho de página usado.
  - `page` integer, nullable: Página retornada, começando em 1.
  - `totalPage` integer, nullable: Quantidade de páginas, quando a listagem informa.
  - `message` string, nullable: Observação opcional sobre a listagem (por exemplo, por que veio vazia). Omitida quando nula.

## Other responses

- `400`: Valor fora das faixas ou listas aceitas (`VALIDATION_FAILED`).
- `401`: Token ausente, inválido ou expirado (SESSION_INVALID), ou sem a permissão exigida (UNAUTHORIZED).
- `500`: Erro inesperado. Tente de novo; se persistir, contate o suporte com o traceId.

---

[API](https://skmtc.dev/fbits/apis/admin-api.md) - [All operations](https://skmtc.dev/fbits/apis/admin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/fbits/apis/admin-api/revisions/a37bfd1b0bf3?raw)