Receita por seller e categoria

Receita do período repartida por seller (lojista) e por categoria de produto.

Em um marketplace, a receita se divide entre vários sellers (lojistas), e cada seller paga uma comissão à loja. revenue-by-vendor mostra essa divisão, com a comissão e o valor líquido de cada um. revenue-by-category mostra o mesmo período repartido por categoria de produto. Ambos exigem um intervalo de datas.

Receita por seller

GET/api/v1/admin/analytics/revenue-by-vendorAdmin

Receita por seller

Parâmetros de consulta

startstringobrigatório

Primeiro dia, formato YYYY-MM-DD, no fuso da loja (America/Sao_Paulo).

endstringobrigatório

Último dia, formato YYYY-MM-DD. O dia inteiro entra no cálculo.

periodstring

all

Só o valor all tem efeito aqui: remove o limite de 366 dias entre start e end. Qualquer outro valor é ignorado.

Exemplo de requisição (seller)

bash

curl "$BASE_URL/api/v1/admin/analytics/revenue-by-vendor?start=2026-09-01&end=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (seller)

200Receita por seller

json

{
  "vendors": [
    {
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "vendor_name": "Loja Seller Teste",
      "order_count": 399,
      "revenue": 27986296,
      "commission_amount": 2968334,
      "net_revenue": 25017962,
      "avg_order_value": 70141,
      "percentage": 10000
    }
  ]
}

Campos da resposta

vendorsarray

Um item por seller com vendas no período.

vendors[].vendor_idstring

Id do seller (UUID).

vendors[].vendor_namestring

Nome do seller.

vendors[].order_countinteger

Sub-pedidos do seller no período.

vendors[].revenueinteger

Receita bruta do seller, em centavos.

vendors[].commission_amountinteger

Comissão cobrada pela loja, em centavos.

vendors[].net_revenueinteger

Receita menos comissão, em centavos.

vendors[].avg_order_valueinteger

Ticket médio do seller, em centavos.

vendors[].percentageinteger

Participação no total, em pontos-base: 2500 = 25,00%, 10000 = 100%.

Erros (seller)

Status	Quando	Corpo
400	Falta `start` ou `end`.	`{"error":"start and end query parameters are required (format: 2006-01-02)"}`
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid start date format; expected YYYY-MM-DD"}`
400	`start` depois de `end`.	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 1 ano sem `period=all`.	`{"error":"date range must not exceed 1 year"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Receita por categoria

GET/api/v1/admin/analytics/revenue-by-categoryAdmin

Receita por categoria

Parâmetros de consulta

startstringobrigatório

Primeiro dia, formato YYYY-MM-DD, no fuso da loja (America/Sao_Paulo).

endstringobrigatório

Último dia, formato YYYY-MM-DD. O dia inteiro entra no cálculo.

periodstring

all

Só o valor all tem efeito aqui: remove o limite de 366 dias entre start e end. Qualquer outro valor é ignorado.

Exemplo de requisição (categoria)

bash

curl "$BASE_URL/api/v1/admin/analytics/revenue-by-category?start=2026-09-01&end=2026-10-10" \
  -H "Authorization: Bearer $TOKEN"

Resposta (categoria)

200Receita por categoria

json

{
  "categories": [
    { "category_id": "uncategorized", "category_name": "Uncategorized", "product_count": 5, "products_sold": 16, "revenue": 2831930, "avg_price": 176996 },
    { "category_id": "54227821-63c2-45f8-aa1c-4dc40e599f8c", "category_name": "Cafeteiras", "product_count": 19, "products_sold": 33, "revenue": 1570670, "avg_price": 47596 }
  ]
}

Campos da resposta

categoriesarray

Uma linha por categoria, da maior para a menor receita.

categories[].category_idstring

Id da categoria (UUID) ou o texto fixo uncategorized para produtos sem categoria.

categories[].category_namestring

Nome da categoria.

categories[].product_countinteger

Produtos distintos vendidos.

categories[].products_soldinteger

Unidades vendidas.

categories[].revenueinteger

Receita da categoria, em centavos.

categories[].avg_priceinteger

Preço médio por unidade, em centavos.

Erros (categoria)

Status	Quando	Corpo
400	Falta `start` ou `end`.	`{"error":"start and end query parameters are required (format: 2006-01-02)"}`
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid start date format; expected YYYY-MM-DD"}`
400	`start` depois de `end`.	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 1 ano sem `period=all`.	`{"error":"date range must not exceed 1 year"}`
401	Sem token, token inválido ou expirado.	`{"error":"missing authorization header"}`
403	O usuário não tem o privilégio exigido.	`{"error":"insufficient privileges","required":"view_reports"}`
403	O módulo está desligado na loja.	`{"error":"module_disabled","module":"analytics"}`
500	Falha ao consultar os dados.	`{"error":"failed to ..."}`

Veja também

Receita por seller e categoria

Receita do período repartida por seller (lojista) e por categoria de produto.