Padrões de tempo

Vendas por dia da semana, crescimento mês a mês e o mapa de calor por dia e hora.

Três rotas para descobrir quando a loja vende. sales-by-day soma pedidos e receita por dia da semana, monthly-growth traz a série mensal e heatmap cruza dia da semana com hora do dia. Dias e horas seguem o fuso da loja (America/Sao_Paulo). sales-by-day e heatmap aceitam from/to ou period; monthly-growth recebe o número de meses.

Por dia da semana

GET/api/v1/admin/analytics/sales-by-dayAdmin

Vendas por dia da semana

Parâmetros de consulta

fromstring

Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.

tostring

Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.

periodstringpadrão: 30days

today7days30days90daysthis_monthlast_monththis_year

Atalho de janela quando from/to não são enviados.

Exemplo de requisição (sales-by-day)

bash

curl "$BASE_URL/api/v1/admin/analytics/sales-by-day?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (sales-by-day)

200Sete dias retornados

json

{
  "days": [
    { "day_index": 0, "order_count": 1, "revenue_centavos": 5266 },
    { "day_index": 1, "order_count": 3, "revenue_centavos": 374956 },
    { "day_index": 2, "order_count": 1, "revenue_centavos": 53478 },
    { "day_index": 3, "order_count": 0, "revenue_centavos": 0 },
    { "day_index": 4, "order_count": 0, "revenue_centavos": 0 },
    { "day_index": 5, "order_count": 1, "revenue_centavos": 13587 },
    { "day_index": 6, "order_count": 2, "revenue_centavos": 45000 }
  ]
}

Campos da resposta

daysarray

Sempre 7 itens, mesmo para dias sem pedidos.

days[].day_indexinteger

0123456

0 domingo, 1 segunda, até 6 sábado.

days[].order_countinteger

Pedidos nesse dia da semana.

days[].revenue_centavosinteger

Receita, em centavos.

Erros (sales-by-day)

Status	Quando	Corpo
400	`period` desconhecido.	`{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}`
400	`from`/`to` mal formatados, `from` depois de `to`, ou mais de 2 anos.	`{"error":"date range must not exceed 2 years"}`
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 ..."}`

Crescimento mensal

GET/api/v1/admin/analytics/monthly-growthAdmin

Pedidos e receita por mês

Parâmetros de consulta

monthsintegerpadrão: 6

Quantos meses mostrar, contando o atual. Menor que 1 vale 6; maior que 36 vale 36.

Exemplo de requisição (monthly-growth)

bash

curl "$BASE_URL/api/v1/admin/analytics/monthly-growth?months=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (monthly-growth)

200Série retornada

json

{
  "months": [
    { "year_month": "2026-09", "order_count": 391, "revenue_centavos": 27418842 },
    { "year_month": "2026-10", "order_count": 4, "revenue_centavos": 63853 }
  ]
}

Campos da resposta

monthsarray

Meses em ordem cronológica.

months[].year_monthstring

Mês, YYYY-MM.

months[].order_countinteger

Pedidos no mês.

months[].revenue_centavosinteger

Receita do mês, em centavos.

Erros (monthly-growth)

Status	Quando	Corpo
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 ..."}`

Mapa de calor

GET/api/v1/admin/analytics/heatmapAdmin

Mapa de calor de vendas por dia e hora

Parâmetros de consulta

fromstring

Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.

tostring

Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.

periodstringpadrão: 30days

today7days30days90daysthis_monthlast_monththis_year

Atalho de janela quando from/to não são enviados.

Exemplo de requisição (heatmap)

bash

curl "$BASE_URL/api/v1/admin/analytics/heatmap?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (heatmap)

200Grade retornada

json

{
  "cells": [
    [
      { "order_count": 0, "revenue_centavos": 0 },
      { "order_count": 0, "revenue_centavos": 0 },
      { "order_count": 1, "revenue_centavos": 5266 }
    ]
  ]
}

Campos da resposta

cellsarray

Matriz de 7 linhas (dia da semana, 0 domingo a 6 sábado) por 24 colunas (hora, 0 a 23). O exemplo corta a matriz para caber; a resposta real traz as 7 linhas de 24 itens.

cells[][].order_countinteger

Pedidos nessa combinação de dia e hora.

cells[][].revenue_centavosinteger

Receita, em centavos.

Erros (heatmap)

Status	Quando	Corpo
400	`period` desconhecido.	`{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}`
400	`from`/`to` mal formatados, `from` depois de `to`, ou mais de 2 anos.	`{"error":"date range must not exceed 2 years"}`
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

API atual/Referência completa/Análises

Padrões de tempo

Vendas por dia da semana, crescimento mês a mês e o mapa de calor por dia e hora.

Por dia da semana

GET/api/v1/admin/analytics/sales-by-dayAdmin

Vendas por dia da semana

Parâmetros de consulta

fromstring

Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.

tostring

Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.

periodstringpadrão: 30days

today7days30days90daysthis_monthlast_monththis_year

Atalho de janela quando from/to não são enviados.

Exemplo de requisição (sales-by-day)

bash

curl "$BASE_URL/api/v1/admin/analytics/sales-by-day?period=90days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (sales-by-day)

200Sete dias retornados

json

{
  "days": [
    { "day_index": 0, "order_count": 1, "revenue_centavos": 5266 },
    { "day_index": 1, "order_count": 3, "revenue_centavos": 374956 },
    { "day_index": 2, "order_count": 1, "revenue_centavos": 53478 },
    { "day_index": 3, "order_count": 0, "revenue_centavos": 0 },
    { "day_index": 4, "order_count": 0, "revenue_centavos": 0 },
    { "day_index": 5, "order_count": 1, "revenue_centavos": 13587 },
    { "day_index": 6, "order_count": 2, "revenue_centavos": 45000 }
  ]
}

Campos da resposta

daysarray

Sempre 7 itens, mesmo para dias sem pedidos.

days[].day_indexinteger

0123456

0 domingo, 1 segunda, até 6 sábado.

days[].order_countinteger

Pedidos nesse dia da semana.

days[].revenue_centavosinteger

Receita, em centavos.

Erros (sales-by-day)

Status	Quando	Corpo
400	`period` desconhecido.	`{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}`
400	`from`/`to` mal formatados, `from` depois de `to`, ou mais de 2 anos.	`{"error":"date range must not exceed 2 years"}`
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 ..."}`

Crescimento mensal

GET/api/v1/admin/analytics/monthly-growthAdmin

Pedidos e receita por mês

Parâmetros de consulta

monthsintegerpadrão: 6

Quantos meses mostrar, contando o atual. Menor que 1 vale 6; maior que 36 vale 36.

Exemplo de requisição (monthly-growth)

bash

curl "$BASE_URL/api/v1/admin/analytics/monthly-growth?months=2" \
  -H "Authorization: Bearer $TOKEN"

Resposta (monthly-growth)

200Série retornada

json

{
  "months": [
    { "year_month": "2026-09", "order_count": 391, "revenue_centavos": 27418842 },
    { "year_month": "2026-10", "order_count": 4, "revenue_centavos": 63853 }
  ]
}

Campos da resposta

monthsarray

Meses em ordem cronológica.

months[].year_monthstring

Mês, YYYY-MM.

months[].order_countinteger

Pedidos no mês.

months[].revenue_centavosinteger

Receita do mês, em centavos.

Erros (monthly-growth)

Status	Quando	Corpo
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 ..."}`

Mapa de calor

GET/api/v1/admin/analytics/heatmapAdmin

Mapa de calor de vendas por dia e hora

Parâmetros de consulta

fromstring

Primeiro dia, YYYY-MM-DD. Só vale se to também vier; tem precedência sobre period.

tostring

Último dia, YYYY-MM-DD (o dia inteiro entra). Intervalo máximo de 2 anos.

periodstringpadrão: 30days

today7days30days90daysthis_monthlast_monththis_year

Atalho de janela quando from/to não são enviados.

Exemplo de requisição (heatmap)

bash

curl "$BASE_URL/api/v1/admin/analytics/heatmap?period=30days" \
  -H "Authorization: Bearer $TOKEN"

Resposta (heatmap)

200Grade retornada

json

{
  "cells": [
    [
      { "order_count": 0, "revenue_centavos": 0 },
      { "order_count": 0, "revenue_centavos": 0 },
      { "order_count": 1, "revenue_centavos": 5266 }
    ]
  ]
}

Campos da resposta

cellsarray

Matriz de 7 linhas (dia da semana, 0 domingo a 6 sábado) por 24 colunas (hora, 0 a 23). O exemplo corta a matriz para caber; a resposta real traz as 7 linhas de 24 itens.

cells[][].order_countinteger

Pedidos nessa combinação de dia e hora.

cells[][].revenue_centavosinteger

Receita, em centavos.

Erros (heatmap)

Status	Quando	Corpo
400	`period` desconhecido.	`{"error":"invalid period; valid: today, 7days, 30days, 90days, this_month, last_month, this_year"}`
400	`from`/`to` mal formatados, `from` depois de `to`, ou mais de 2 anos.	`{"error":"date range must not exceed 2 years"}`
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 ..."}`