API legada/Referência completa/API de apps (token vat_)

Relatórios

Quatro relatórios de leitura para BI e painéis externos: resumo de pedidos, vendas por dia, produtos mais vendidos e clientes.

Estes relatórios alimentam painéis de BI e planilhas sem exportar a base inteira. Todos só leem dados, têm o escopo read_analytics e contam pedidos pai (a compra do cliente), não cada sub-pedido de seller. Valores em reais saem em centavos.

Os períodos são sempre fechados nas duas pontas e contados no fuso horário da loja. As janelas de comparação (período anterior e mesmo período do ano passado) vêm prontas no resumo de pedidos.

GET/api/admin/analytics/ordersAutenticada

Resumo de pedidos de um período

Devolve contagens e receita de um período móvel, com a comparação contra o período anterior e contra o ano passado.

Parâmetros de consulta

periodstringpadrão: 30days

today7days30days90daysall

Janela de tempo terminando agora. Outro valor responde 400.

GET/api/admin/analytics/salesAutenticada

Relatório de vendas

Devolve o resumo do intervalo, a série diária e os 10 produtos mais vendidos.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia (entra inteiro), YYYY-MM-DD. Não pode ser anterior a start, e o intervalo não passa de 366 dias.

GET/api/admin/analytics/top-productsAutenticada

Produtos mais vendidos

Ranking por receita no intervalo, só com produtos que tiveram venda.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia, YYYY-MM-DD.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100. Acima de 100 volta a 10, não a 100. Zero, negativo ou texto também dão 10.

GET/api/admin/analytics/customersAutenticada

Estatísticas de clientes

Devolve quantos clientes são novos e quantos já tinham comprado antes, o ticket médio, o valor médio por cliente ao longo da vida e os clientes que mais gastaram.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia, YYYY-MM-DD.

Exemplo de requisição

bash

curl "$BASE_URL/api/admin/analytics/sales?start=2026-09-01&end=2026-09-30" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Resumo de pedidos (analytics/orders)

json

{
  "total_orders": 4,
  "total_revenue": 63853,
  "pending_orders": 2,
  "completed_orders": 1,
  "cancelled_orders": 3,
  "avg_order_value": 15963,
  "unique_customers": 4,
  "period": "7days",
  "previous_total_orders": 4,
  "previous_total_revenue": 428434,
  "previous_avg_order_value": 107109,
  "previous_unique_customers": 1,
  "year_ago_total_orders": 245,
  "year_ago_total_revenue": 15554066,
  "year_ago_avg_order_value": 63486,
  "year_ago_unique_customers": 239
}

200Relatório de vendas (analytics/sales)

json

{
  "stats": {
    "total_orders": 391,
    "total_revenue": 27418842,
    "pending_orders": 36,
    "completed_orders": 191,
    "cancelled_orders": 1,
    "avg_order_value": 70125,
    "unique_customers": 0,
    "period": "2026-09-01 \u2014 2026-09-30",
    "previous_total_orders": 0,
    "previous_total_revenue": 0,
    "previous_avg_order_value": 0,
    "previous_unique_customers": 0,
    "year_ago_total_orders": 0,
    "year_ago_total_revenue": 0,
    "year_ago_avg_order_value": 0,
    "year_ago_unique_customers": 0
  },
  "daily_sales": [
    { "date": "2026-09-01", "orders": 65, "revenue": 4480463 },
    { "date": "2026-09-02", "orders": 65, "revenue": 3833192 }
  ],
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica 900W", "quantity": 9, "revenue": 2691000 }
  ],
  "generated_at": "2026-10-11T21:15:33.368927Z"
}

200Produtos mais vendidos (analytics/top-products)

json

{
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica 900W", "quantity": 9, "revenue": 2691000 },
    { "product_id": "f00b151f-498a-4c27-adfb-774ac5ac6c89", "product_name": "Garrafa Térmica Verde", "quantity": 3, "revenue": 392970 }
  ]
}

200Clientes (analytics/customers)

json

{
  "new_customers": 1,
  "returning_customers": 280,
  "total_customers": 281,
  "avg_order_value": 70142,
  "avg_lifetime_value": 380797,
  "top_customers": [
    {
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "email": "bruno.gomes@example.com",
      "order_count": 26,
      "total_spent": 1229701
    }
  ]
}

Campos da resposta

total_ordersinteger

Pedidos criados no período.

total_revenueinteger

Receita do período, em centavos.

pending_ordersinteger

Pedidos ainda pendentes.

completed_ordersinteger

Pedidos concluídos.

cancelled_ordersinteger

Pedidos cancelados.

avg_order_valueinteger

Ticket médio, em centavos.

unique_customersinteger

Clientes distintos que compraram no período. No relatório de vendas vem 0: use o resumo de pedidos ou as estatísticas de clientes.

periodstring

Período pedido (30days) ou, no relatório de vendas, as duas datas escritas com um travessão no meio.

previous_*integer

Os mesmos números da janela de igual tamanho imediatamente anterior (previous_total_orders, previous_total_revenue, previous_avg_order_value, previous_unique_customers). No relatório de vendas vêm zerados.

year_ago_*integer

Os mesmos números do mesmo intervalo um ano antes (year_ago_total_orders, year_ago_total_revenue, year_ago_avg_order_value, year_ago_unique_customers). No relatório de vendas vêm zerados.

daily_sales[]array

Um item por dia com pedidos: date, orders e revenue (centavos). Dias sem pedido não aparecem.

top_products[]array

product_id, product_name, quantity (unidades vendidas) e revenue (centavos).

generated_atstring

Quando o relatório foi calculado (RFC 3339, UTC).

new_customersinteger

Clientes cuja primeira compra caiu dentro do intervalo.

returning_customersinteger

Clientes que compraram no intervalo e já tinham comprado antes.

total_customersinteger

Soma dos dois grupos.

avg_lifetime_valueinteger

Gasto médio por cliente ao longo da vida, em centavos.

top_customers[]array

Maiores compradores: customer_id, customer_name (pode vir vazio), email, order_count e total_spent (centavos).

Erros

Status	Quando	Corpo
400	`period` fora da lista	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
400	`start` ou `end` ausentes	`{"error":"start and end query parameters are required (format: 2006-01-02)"}`
400	Data mal escrita	`{"error":"invalid start date format; expected YYYY-MM-DD","detail":"..."}`
400	`start` depois de `end`	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 366 dias	`{"error":"date range must not exceed 1 year"}`
401	Sem token de app	`{"error":"app_token_required"}`
403	Sem o escopo `read_analytics`	`{"error":"missing_scope","required":"read_analytics"}`
500	Falha ao calcular	`{"error":"failed to generate sales report","detail":"..."}`

As mensagens de erro voltam em inglês.

Veja também

Relatórios

Quatro relatórios de leitura para BI e painéis externos: resumo de pedidos, vendas por dia, produtos mais vendidos e clientes.

GET/api/admin/analytics/ordersAutenticada

Resumo de pedidos de um período

Devolve contagens e receita de um período móvel, com a comparação contra o período anterior e contra o ano passado.

Parâmetros de consulta

periodstringpadrão: 30days

today7days30days90daysall

Janela de tempo terminando agora. Outro valor responde 400.

GET/api/admin/analytics/salesAutenticada

Relatório de vendas

Devolve o resumo do intervalo, a série diária e os 10 produtos mais vendidos.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia (entra inteiro), YYYY-MM-DD. Não pode ser anterior a start, e o intervalo não passa de 366 dias.

GET/api/admin/analytics/top-productsAutenticada

Produtos mais vendidos

Ranking por receita no intervalo, só com produtos que tiveram venda.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia, YYYY-MM-DD.

limitintegerpadrão: 10

Quantos produtos devolver, de 1 a 100. Acima de 100 volta a 10, não a 100. Zero, negativo ou texto também dão 10.

GET/api/admin/analytics/customersAutenticada

Estatísticas de clientes

Devolve quantos clientes são novos e quantos já tinham comprado antes, o ticket médio, o valor médio por cliente ao longo da vida e os clientes que mais gastaram.

Parâmetros de consulta

startstringobrigatório

Primeiro dia, YYYY-MM-DD.

endstringobrigatório

Último dia, YYYY-MM-DD.

Exemplo de requisição

bash

curl "$BASE_URL/api/admin/analytics/sales?start=2026-09-01&end=2026-09-30" \
  -H "Authorization: Bearer $APP_TOKEN"

Resposta

200Resumo de pedidos (analytics/orders)

json

{
  "total_orders": 4,
  "total_revenue": 63853,
  "pending_orders": 2,
  "completed_orders": 1,
  "cancelled_orders": 3,
  "avg_order_value": 15963,
  "unique_customers": 4,
  "period": "7days",
  "previous_total_orders": 4,
  "previous_total_revenue": 428434,
  "previous_avg_order_value": 107109,
  "previous_unique_customers": 1,
  "year_ago_total_orders": 245,
  "year_ago_total_revenue": 15554066,
  "year_ago_avg_order_value": 63486,
  "year_ago_unique_customers": 239
}

200Relatório de vendas (analytics/sales)

json

{
  "stats": {
    "total_orders": 391,
    "total_revenue": 27418842,
    "pending_orders": 36,
    "completed_orders": 191,
    "cancelled_orders": 1,
    "avg_order_value": 70125,
    "unique_customers": 0,
    "period": "2026-09-01 \u2014 2026-09-30",
    "previous_total_orders": 0,
    "previous_total_revenue": 0,
    "previous_avg_order_value": 0,
    "previous_unique_customers": 0,
    "year_ago_total_orders": 0,
    "year_ago_total_revenue": 0,
    "year_ago_avg_order_value": 0,
    "year_ago_unique_customers": 0
  },
  "daily_sales": [
    { "date": "2026-09-01", "orders": 65, "revenue": 4480463 },
    { "date": "2026-09-02", "orders": 65, "revenue": 3833192 }
  ],
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica 900W", "quantity": 9, "revenue": 2691000 }
  ],
  "generated_at": "2026-10-11T21:15:33.368927Z"
}

200Produtos mais vendidos (analytics/top-products)

json

{
  "top_products": [
    { "product_id": "b02afb3d-4218-40ef-a72f-47beede28d46", "product_name": "Cafeteira Elétrica 900W", "quantity": 9, "revenue": 2691000 },
    { "product_id": "f00b151f-498a-4c27-adfb-774ac5ac6c89", "product_name": "Garrafa Térmica Verde", "quantity": 3, "revenue": 392970 }
  ]
}

200Clientes (analytics/customers)

json

{
  "new_customers": 1,
  "returning_customers": 280,
  "total_customers": 281,
  "avg_order_value": 70142,
  "avg_lifetime_value": 380797,
  "top_customers": [
    {
      "customer_id": "b2495fbb-8e8d-4d18-b370-b30f880bfd71",
      "customer_name": "Bruno Gomes",
      "email": "bruno.gomes@example.com",
      "order_count": 26,
      "total_spent": 1229701
    }
  ]
}

Campos da resposta

total_ordersinteger

Pedidos criados no período.

total_revenueinteger

Receita do período, em centavos.

pending_ordersinteger

Pedidos ainda pendentes.

completed_ordersinteger

Pedidos concluídos.

cancelled_ordersinteger

Pedidos cancelados.

avg_order_valueinteger

Ticket médio, em centavos.

unique_customersinteger

Clientes distintos que compraram no período. No relatório de vendas vem 0: use o resumo de pedidos ou as estatísticas de clientes.

periodstring

Período pedido (30days) ou, no relatório de vendas, as duas datas escritas com um travessão no meio.

previous_*integer

year_ago_*integer

Os mesmos números do mesmo intervalo um ano antes (year_ago_total_orders, year_ago_total_revenue, year_ago_avg_order_value, year_ago_unique_customers). No relatório de vendas vêm zerados.

daily_sales[]array

Um item por dia com pedidos: date, orders e revenue (centavos). Dias sem pedido não aparecem.

top_products[]array

product_id, product_name, quantity (unidades vendidas) e revenue (centavos).

generated_atstring

Quando o relatório foi calculado (RFC 3339, UTC).

new_customersinteger

Clientes cuja primeira compra caiu dentro do intervalo.

returning_customersinteger

Clientes que compraram no intervalo e já tinham comprado antes.

total_customersinteger

Soma dos dois grupos.

avg_lifetime_valueinteger

Gasto médio por cliente ao longo da vida, em centavos.

top_customers[]array

Maiores compradores: customer_id, customer_name (pode vir vazio), email, order_count e total_spent (centavos).

Erros

Status	Quando	Corpo
400	`period` fora da lista	`{"error":"invalid period; valid values: today, 7days, 30days, 90days, all"}`
400	`start` ou `end` ausentes	`{"error":"start and end query parameters are required (format: 2006-01-02)"}`
400	Data mal escrita	`{"error":"invalid start date format; expected YYYY-MM-DD","detail":"..."}`
400	`start` depois de `end`	`{"error":"start date must be before or equal to end date"}`
400	Intervalo maior que 366 dias	`{"error":"date range must not exceed 1 year"}`
401	Sem token de app	`{"error":"app_token_required"}`
403	Sem o escopo `read_analytics`	`{"error":"missing_scope","required":"read_analytics"}`
500	Falha ao calcular	`{"error":"failed to generate sales report","detail":"..."}`

As mensagens de erro voltam em inglês.