VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
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

Resposta

200Arquivo CSV

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

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403O token não é de um usuário administrador.{"error":"admin access required"}
403O usuário é administrador, mas não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_reports"]}
400from ou to ausente.{"error":"from and to query parameters are required (format: 2006-01-02)"}
400Data fora do formato YYYY-MM-DD.{"error":"invalid from date format; expected YYYY-MM-DD","detail":"parsing time ..."}
400from depois de to.{"error":"from date must be before or equal to to date"}
400Intervalo maior que um ano.{"error":"date range must not exceed 1 year"}
400type ausente.{"error":"type query parameter is required (vendor, category, daily, customers, shipping)"}
200type 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"}
Tipo inválido volta 200

Valide type do seu lado. Se enviar um valor fora da lista, a plataforma responde 200 com o JSON de erro no corpo (e três bytes de BOM na frente), e um cliente que só olha o status vai gravar um arquivo ".csv" com uma mensagem de erro dentro.

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

Resposta

200Arquivo CSV

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

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

Diferente da exportação por dimensão, esta monta o arquivo inteiro na memória antes de responder. Se algo falhar no meio, você recebe 500 e não um CSV truncado com status 200. A ausência de from/to não dá erro nesta rota: a janela padrão são os últimos 30 dias, e o nome do arquivo sai sem as datas.

Veja também

  • Relatórios por dimensão
  • Relatórios avançados de vendas
  • Relatórios agendados
Anterior
Relatórios por dimensão
Próxima
Relatórios avançados de vendas
Nesta página
  • Exportar relatórios por dimensão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Exportar relatórios avançados
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
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
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
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
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