Entrar

Produtos mais vendidos

GET https://{organization}.myguper.com/api/order/report/products/{dateStart}/{dateEnd}

A resposta para "o que mais vendeu", "top produtos por receita", "unidades por SKU", numa única chamada — em vez de paginar os itens e agrupar no cliente. Ranqueia os itens vendidos (order_item) por produto, SKU, categoria ou marca, no mesmo recorte do relatório de vendas (org, janela no fuso da org, loja, status).

Por linha: units (quantidade vendida), unitsCanceled, revenue, orders (quantos pedidos incluíram) e lines. As linhas são o top N por receita (limit, default 50); o total cobre todos os itens do período, não só o top.

Quebre por loja ou por tempo numa chamada só. O groupBy aceita lista por vírgula: o 1º token é a dimensão do item (product/sku/category/brand) e você pode somar store e/ou um grão de tempo (day/week/month) — ex. groupBy=product,store, sku,week, product,store,month. Com quebra, o limit pega os top itens do período inteiro e cada linha é uma célula (item × loja × período) — você tem o detalhe por loja ou por semana sem uma chamada por loja. A linha carrega storeId, day (YYYY-MM-DD), week (YYYY-Www, ISO) ou month (YYYY-MM) conforme o caso; célula sem venda não vira linha.

revenue é receita de LINHA — SUM(price × quantity), com price = valor unitário do item (líquido do desconto do item). Não é o total do pedido e não bate com a receita do relatório de vendas: descontos e ajustes de nível-pedido não descem pro price do item, então a soma das linhas roda mais alta (≈+20% medido). Use este para ranking de produto; use o order.report.sales para faturamento. Valores em centavos.

category e brand vêm de ingestão parcial e estão esparsos hoje (poucos % em algumas orgs). O endpoint já está pronto pra eles e vai enchendo conforme a ingestão melhorar — leia o meta.coverage (fração de itens e receita que têm categoria/marca) pra uma quebra que cobre 5% do período não ser lida como o total. Linhas com id null são os itens sem o campo. O order_item não guarda o nome de categoria/marca, só o id e o refId externo.

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 Start of the period (YYYY-MM-DD), inclusive. The day is cut from order_date in the org timezone.
dateEnd * string End of the period (YYYY-MM-DD), inclusive.

Parâmetros de query

Name Type Description
groupBy string Comma list: 1st token = item dimension (`product`/`sku`/`category`/`brand`, default `product`); optional extra tokens break it down by `store` and/or one time grain (`day`/`week`/`month`). E.g. `product,store`, `sku,week`, `product,store,month`. `product`/`sku` work today; `category`/`brand` are sparse (see `meta.coverage`). At most one time grain per call.
store integer Restrict to a single store id.
status string Order status. Default: all except canceled.
limit integer How many top rows by revenue (1-500). Default 50. The `total` always covers everything.

Respostas

{
  "meta": {
    "unit": "cents", "timezone": "Etc/GMT+6",
    "groupBy": "product", "breakdown": [], "limit": 50,
    "filters": { "store": null, "status": "all except canceled (default)" },
    "coverage": {
      "category": { "items": 0.049, "revenue": 0.065 },
      "brand":    { "items": 0.049, "revenue": 0.061 }
    }
  },
  "rows": [
    { "productId": 0, "productName": "I-2 BILLETERA CLOE P25 564 ROSA /FLAP GR",
      "units": 256, "unitsCanceled": 0, "revenue": 122482432, "orders": 115, "lines": 121 }
  ],
  "total": { "units": 60663, "unitsCanceled": 0, "revenue": 6124205576, "orders": 24815, "lines": 56403 }
}

Relacionados

Copied to clipboard