Entrar

Audiência por produto — quantos clientes compraram um produto ou categoria

GET https://{organization}.myguper.com/api/order/report/by-product/{dateStart}/{dateEnd}

Clientes que compraram um produto numa janela — casados por padrão de nome ou por SKU — a audiência que o construtor QON não expressa, porque ele não tem nenhuma coluna de item, SKU, categoria ou marca. Responde "quem comprou mala acima de $500 neste semestre", "compradores destes SKUs", numa única chamada em vez de paginar centenas de milhares de linhas de item e agrupar no cliente.

Casa por productNameLike (lista de padrões, OR entre eles, case e acento insensível, contains) e/ou skuRefId (exato). Ao menos um é obrigatório. Restrinja por preço unitário (unitPriceMin/unitPriceMax) e por peças (minQuantity, líquido de cancelamento).

price é o preço unitário, líquido de desconto — então unitPriceMin/Max filtram o unitário direto, não price/quantity. É isso que separa um produto de verdade de um brinde promocional de 1 centavo na mesma família. value é SUM(price × qtd líquida) — o gasto nos itens que casaram, em centavos.

Por linha: pieces (quantidade líquida comprada), value, lastDate e matchedPatterns — quais dos seus padrões de productNameLike o cliente casou, pra você mostrar por que cada um está na audiência. A janela e o lastDate são no fuso da org. As linhas são paginadas (e/p); total é o tamanho da audiência.

É só o lado de order — client (id) + métricas. Nome, e-mail, telefone, última loja e grupo de loja moram no register; e também os filtros de "excluir estas listas" e "precisa ter contato". Enriqueça e filtre com as operações do register, e feche o ciclo com register.audience-list.person.create (que recebe os ids dos clientes).

Casar por nome herda a bagunça da nomenclatura do PDV. category/categoryRefId vêm vazios ou inconsistentes em algumas orgs (cloe incluída), então o nome é a chave confiável hoje — mas carrega grafias legadas e padrões de referência externa. Alargue o productNameLike na dúvida, e leia o matchedPatterns pra ver o que de fato pegou.

Try-it values populated from environment ACME (Demo)


Autenticação

Token

Send your user token in the x-guper-authorization header.

Cabeçalhos

Name Type Description
x-guper-authorization * string User token issued by Guper.
Content-Type * string Always `application/json` for endpoints that accept a JSON body.

Parâmetros do caminho

Name Type Description
dateStart * string Início da janela (YYYY-MM-DD), inclusivo. Cortado de order_date no fuso da org.
dateEnd * string Fim da janela (YYYY-MM-DD), inclusivo.

Parâmetros de query

Name Type Description
productNameLike[] array Padrões de nome de produto (contains, OR entre eles, case e acento insensível). Um por valor: productNameLike[]=a&productNameLike[]=b. Obrigatório se não houver skuRefId.
skuRefId[] array Refs externas de SKU, match exato (OR). Um por valor. Obrigatório se não houver productNameLike.
unitPriceMin integer Preço unitário mínimo em centavos (inclusivo), sobre o unitário com desconto (`price`). Use pra excluir brinde promocional.
unitPriceMax integer Preço unitário máximo em centavos (inclusivo).
minQuantity integer Mínimo de peças compradas, líquido de cancelamento. Default 1.
status string Status do pedido contado. Default `completed`. `all` = tudo exceto cancelado.
e integer Registros por página (1-1000). Default 100.
p integer Número da página.

Respostas

{
  "meta": {
    "unit": "cents", "timezone": "America/Mexico_City",
    "filters": {
      "productNameLike": ["EQUIPAJE VERTICAL","EQUIPAJE VIAJE","SET DE VIAJE","MALETA"],
      "skuRefId": [], "unitPriceMin": 50000, "unitPriceMax": null,
      "minQuantity": 1, "status": "completed"
    }
  },
  "rows": [
    { "client": 4134488, "pieces": 5, "value": 958795715, "lastDate": "2026-06-01",
      "matchedPatterns": ["EQUIPAJE VERTICAL","EQUIPAJE VIAJE","SET DE VIAJE"] }
  ],
  "total": 4624,
  "pagination": { "entries": 100, "currentPage": 1, "totalPages": 47, "isInitial": true, "isEnd": false }
}

Relacionados

Copied to clipboard