API atual/Referência completa/Relatórios e painel

Exportar em CSV

Baixa relatórios como arquivo CSV pronto para planilha, com cabeçalhos em português ou inglês.

Duas rotas de exportação: a dos relatórios por dimensão (/admin/reports/export) e a dos relatórios avançados (/admin/advanced-reports/export). Cada uma aceita tipos de relatório diferentes. Os cabeçalhos das colunas seguem o Accept-Language: com en na frente, saem em inglês; em qualquer outro caso, em português. O nome do arquivo vem em Content-Disposition.

Exportar relatórios por dimensão

GET/api/v1/admin/reports/exportAdmin

CSV dos relatórios por dimensão

Parâmetros de consulta

fromstringobrigatório

Início do período, YYYY-MM-DD, inclusive. Obrigatório.

tostringobrigatório

Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

typestringobrigatório

vendorcategorydailycustomersshipping

Qual relatório exportar. Obrigatório.

Cabeçalhos

Accept-Languagestring

en ou en-US gera cabeçalhos em inglês; ausente ou outro idioma, português.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/reports/export?type=daily&from=2026-09-01&to=2026-09-03" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept-Language: pt-BR" \
  -o relatorio.csv

Resposta

200Arquivo CSV

text

Data;Pedidos;Receita (R$);Valor Médio (R$)
2026-09-01;65;44804,63;689,30
2026-09-02;65;38331,92;589,72
2026-09-03;66;47597,89;721,18

Campos da resposta

Content-Typeheader

text/csv; charset=utf-8.

Content-Dispositionheader

attachment; filename="relatorio-daily-2026-09-01-2026-09-03.csv" (o prefixo muda para report- no idioma inglês).

A resposta não é JSON: é um arquivo CSV em UTF-8 com BOM, separador ; (padrão do Excel em português) e valores monetários com vírgula decimal (449,00), em reais, não em centavos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["view_reports"]}`
400	`from` ou `to` ausente.	`{"error":"from and to query parameters are required (format: 2006-01-02)"}`
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}`
400	`from` depois de `to`.	`{"error":"from date must be before or equal to to date"}`
400	Intervalo maior que um ano.	`{"error":"date range must not exceed 1 year"}`
400	`type` ausente.	`{"error":"type query parameter is required (vendor, category, daily, customers, shipping)"}`
200	`type` desconhecido: o cabeçalho de sucesso já foi enviado, então o status é 200 e o corpo é um JSON de erro precedido de BOM.	`{"error":"invalid report type; valid values: vendor, category, daily, customers, shipping"}`

Exportar relatórios avançados

GET/api/v1/admin/advanced-reports/exportAdmin

CSV dos relatórios avançados

Parâmetros de consulta

typestringobrigatório

salescustomersinventorycommissionspaymentscategories

Qual relatório exportar. Obrigatório.

fromstring

Início, YYYY-MM-DD. Padrão: 30 dias atrás. Em inventory define só a janela usada para contar unidades vendidas.

tostring

Fim, YYYY-MM-DD. Padrão: hoje. Em inventory define só a janela de unidades vendidas.

compare_fromstring

Início da comparação (só sales).

compare_tostring

Fim da comparação (só sales).

vendor_iduuid

Limita ao seller.

category_iduuid

Limita à categoria. Só o relatório categories aplica o filtro; os outros tipos o ignoram.

group_bystringpadrão: day

dayweekmonth

Agrupamento da série: por dia, semana ou mês.

Cabeçalhos

Accept-Languagestring

en gera cabeçalhos em inglês; padrão português.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/advanced-reports/export?type=sales&from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN" \
  -o vendas.csv

Resposta

200Arquivo CSV

text

Data;Receita (R$);Pedidos;Valor Médio (R$)
2026-10-09;135,87;1;135,87
2026-10-10;450,00;2;225,00

Resumo
Receita Total;638,53
Total de Pedidos;4
Valor Médio;159,63
Pedidos Concluídos;0
Pedidos Cancelados;3

Campos da resposta

Content-Lengthheader

O arquivo é montado por inteiro antes de enviar, então o tamanho vem no cabeçalho.

A resposta não é JSON: é um arquivo CSV em UTF-8 com BOM, separador ; (padrão do Excel em português) e valores monetários com vírgula decimal (449,00), em reais, não em centavos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["view_reports"]}`
400	`type` ausente.	`{"error":"type query parameter is required"}`
400	`type` fora da lista. Aqui o erro é um 400 de verdade, antes de qualquer byte do arquivo.	`{"error":"invalid report type"}`
500	Falha ao montar o relatório.	`{"error":"failed to generate report","detail":"..."}`

Veja também

API atual/Referência completa/Relatórios e painel

Exportar em CSV

Baixa relatórios como arquivo CSV pronto para planilha, com cabeçalhos em português ou inglês.

Exportar relatórios por dimensão

GET/api/v1/admin/reports/exportAdmin

CSV dos relatórios por dimensão

Parâmetros de consulta

fromstringobrigatório

Início do período, YYYY-MM-DD, inclusive. Obrigatório.

tostringobrigatório

Fim do período, YYYY-MM-DD, inclusive (o dia inteiro entra). Obrigatório. Não pode ser antes de from e o intervalo não pode passar de 366 dias.

typestringobrigatório

vendorcategorydailycustomersshipping

Qual relatório exportar. Obrigatório.

Cabeçalhos

Accept-Languagestring

en ou en-US gera cabeçalhos em inglês; ausente ou outro idioma, português.

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/admin/reports/export?type=daily&from=2026-09-01&to=2026-09-03" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept-Language: pt-BR" \
  -o relatorio.csv

Resposta

200Arquivo CSV

text

Data;Pedidos;Receita (R$);Valor Médio (R$)
2026-09-01;65;44804,63;689,30
2026-09-02;65;38331,92;589,72
2026-09-03;66;47597,89;721,18

Campos da resposta

Content-Typeheader

text/csv; charset=utf-8.

Content-Dispositionheader

attachment; filename="relatorio-daily-2026-09-01-2026-09-03.csv" (o prefixo muda para report- no idioma inglês).

A resposta não é JSON: é um arquivo CSV em UTF-8 com BOM, separador ; (padrão do Excel em português) e valores monetários com vírgula decimal (449,00), em reais, não em centavos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["view_reports"]}`
400	`from` ou `to` ausente.	`{"error":"from and to query parameters are required (format: 2006-01-02)"}`
400	Data fora do formato `YYYY-MM-DD`.	`{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}`
400	`from` depois de `to`.	`{"error":"from date must be before or equal to to date"}`
400	Intervalo maior que um ano.	`{"error":"date range must not exceed 1 year"}`
400	`type` ausente.	`{"error":"type query parameter is required (vendor, category, daily, customers, shipping)"}`
200	`type` desconhecido: o cabeçalho de sucesso já foi enviado, então o status é 200 e o corpo é um JSON de erro precedido de BOM.	`{"error":"invalid report type; valid values: vendor, category, daily, customers, shipping"}`

Exportar relatórios avançados

GET/api/v1/admin/advanced-reports/exportAdmin

CSV dos relatórios avançados

Parâmetros de consulta

typestringobrigatório

salescustomersinventorycommissionspaymentscategories

Qual relatório exportar. Obrigatório.

fromstring

Início, YYYY-MM-DD. Padrão: 30 dias atrás. Em inventory define só a janela usada para contar unidades vendidas.

tostring

Fim, YYYY-MM-DD. Padrão: hoje. Em inventory define só a janela de unidades vendidas.

compare_fromstring

Início da comparação (só sales).

compare_tostring

Fim da comparação (só sales).

vendor_iduuid

Limita ao seller.

category_iduuid

Limita à categoria. Só o relatório categories aplica o filtro; os outros tipos o ignoram.

group_bystringpadrão: day

dayweekmonth

Agrupamento da série: por dia, semana ou mês.

Cabeçalhos

Accept-Languagestring

en gera cabeçalhos em inglês; padrão português.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/advanced-reports/export?type=sales&from=2026-10-01&to=2026-10-11" \
  -H "Authorization: Bearer $TOKEN" \
  -o vendas.csv

Resposta

200Arquivo CSV

text

Data;Receita (R$);Pedidos;Valor Médio (R$)
2026-10-09;135,87;1;135,87
2026-10-10;450,00;2;225,00

Resumo
Receita Total;638,53
Total de Pedidos;4
Valor Médio;159,63
Pedidos Concluídos;0
Pedidos Cancelados;3

Campos da resposta

Content-Lengthheader

O arquivo é montado por inteiro antes de enviar, então o tamanho vem no cabeçalho.

A resposta não é JSON: é um arquivo CSV em UTF-8 com BOM, separador ; (padrão do Excel em português) e valores monetários com vírgula decimal (449,00), em reais, não em centavos.

Erros

Status	Quando	Exemplo de corpo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário administrador.	`{"error":"admin access required"}`
403	O usuário é administrador, mas não tem o privilégio exigido.	`{"error":"insufficient privileges","privilege_required_any":["view_reports"]}`
400	`type` ausente.	`{"error":"type query parameter is required"}`
400	`type` fora da lista. Aqui o erro é um 400 de verdade, antes de qualquer byte do arquivo.	`{"error":"invalid report type"}`
500	Falha ao montar o relatório.	`{"error":"failed to generate report","detail":"..."}`