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

Agendar relatórios

Cria, lista, pausa e remove relatórios que a plataforma gera e envia por e-mail em CSV, todo dia, semana ou mês.

Um relatório agendado é uma receita: tipo de relatório, frequência e lista de e-mails. Uma rotina horária da plataforma procura os agendamentos ativos que venceram, gera o CSV e envia como anexo. Os agendamentos feitos aqui valem para o marketplace inteiro (os de seller são geridos no painel do seller). Todas as rotas desta página exigem o privilégio view_reports.

Listar agendamentos

GET/api/v1/admin/scheduled-reportsAdmin

Lista os agendamentos do marketplace

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamentos

json

{
  "scheduled_reports": [
    {
      "id": 20,
      "name": "Vendas semanais",
      "report_type": "sales",
      "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
      "schedule": "weekly",
      "recipients": [
        "financeiro@example.com"
      ],
      "is_active": true,
      "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "created_at": "2026-10-11T21:05:13"
    }
  ]
}

Campos da resposta

scheduled_reportsarray

Mais recentes primeiro. Só os agendamentos do marketplace, sem os de seller. Lista vazia se não houver nenhum.

scheduled_reports[].idinteger

Id do agendamento. É um inteiro, não um UUID.

scheduled_reports[].namestring

Nome dado ao agendamento.

scheduled_reports[].report_typestring

salescustomersinventorycommissionspaymentscategories

Qual relatório é enviado.

scheduled_reports[].filtersstring

Os filtros guardados, como um texto JSON (não um objeto). Você precisa fazer o parse.

scheduled_reports[].schedulestring

dailyweeklymonthly

Frequência.

scheduled_reports[].recipientsarray

E-mails que recebem o CSV.

scheduled_reports[].last_sent_atstring

Última execução, YYYY-MM-DDTHH:MM:SS. Ausente se nunca rodou.

scheduled_reports[].is_activeboolean

false pausa os envios automáticos.

scheduled_reports[].created_byuuid

Administrador que criou.

scheduled_reports[].created_atstring

Criação, YYYY-MM-DDTHH:MM:SS.

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"]}`
500	Falha ao ler os agendamentos.	`{"error":"failed to list scheduled reports","detail":"..."}`

Criar agendamento

POST/api/v1/admin/scheduled-reportsAdmin

Cria um relatório agendado

Corpo da requisição

namestringobrigatório

Nome do agendamento. Obrigatório.

report_typestringobrigatório

salescustomersinventorycommissionspaymentscategories

Qual relatório enviar. Obrigatório.

schedulestringobrigatório

dailyweeklymonthly

Frequência. Obrigatório. A data do relatório é calculada sozinha: daily envia o dia anterior, weekly os 7 dias anteriores até ontem, monthly o mês fechado anterior.

recipientsarray

E-mails de destino (lista de textos). Os endereços não são validados. Sem destinatário o relatório roda e é registrado, mas nada é enviado.

filtersobject

Filtros do relatório. As datas são ignoradas (o período vem da frequência); na prática só group_by e, no tipo categories, category_id mudam o CSV.

date_fromstring

Ignorado nos agendamentos recorrentes.

date_tostring

Ignorado nos agendamentos recorrentes.

compare_fromstring

Início da comparação. Aceito, mas o CSV enviado por e-mail não tem colunas de comparação.

compare_tostring

Fim da comparação. Igual ao anterior: sem efeito no CSV.

vendor_iduuid

Limita a um seller. Para agendamentos criados pelo admin, o campo vendor_id de nível superior é ignorado, mas este filtro vale e é limpo ao gerar: o envio do admin é sempre do marketplace inteiro.

category_iduuid

Limita a uma categoria. Só tem efeito no tipo categories.

group_bystring

dayweekmonth

Agrupamento da série.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas semanais", "report_type": "sales", "schedule": "weekly", "recipients": ["financeiro@example.com"], "filters": {"group_by": "day"}}'

Resposta

201Agendamento criado

json

{
  "id": 20,
  "name": "Vendas semanais",
  "report_type": "sales",
  "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
  "schedule": "weekly",
  "recipients": [
    "financeiro@example.com"
  ],
  "is_active": true,
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:05:13"
}

Campos da resposta

idinteger

Id do agendamento. É um inteiro, não um UUID.

namestring

Nome dado ao agendamento.

report_typestring

salescustomersinventorycommissionspaymentscategories

Qual relatório é enviado.

filtersstring

Os filtros guardados, como um texto JSON (não um objeto). Você precisa fazer o parse.

schedulestring

dailyweeklymonthly

Frequência.

recipientsarray

E-mails que recebem o CSV.

last_sent_atstring

Última execução, YYYY-MM-DDTHH:MM:SS. Ausente se nunca rodou.

is_activeboolean

false pausa os envios automáticos.

created_byuuid

Administrador que criou.

created_atstring

Criação, YYYY-MM-DDTHH:MM:SS.

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	Corpo não é JSON válido ou `name` vazio.	`{"error":"name is required"}`
500	`report_type` ou `schedule` inválido. Apesar de ser erro do chamador, o status é 500 (o texto traz o valor recusado).	`{"error":"failed to create scheduled report","detail":"invalid report_type: foo"}`

Pausar ou reativar

POST/api/v1/admin/scheduled-reports/{id}/toggleAdmin

Liga ou desliga um agendamento

Parâmetros de caminho

idintegerobrigatório

Id do agendamento (inteiro).

Corpo da requisição

is_activebooleanpadrão: false

true reativa, false pausa. Se omitido, vale false e o agendamento é pausado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-reports/20/toggle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta

200Atualizado

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true quando o comando foi aceito.

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	`id` não é um inteiro, ou corpo inválido.	`{"error":"invalid id"}`

Excluir agendamento

DELETE/api/v1/admin/scheduled-reports/{id}Admin

Remove um agendamento

Parâmetros de caminho

idintegerobrigatório

Id do agendamento (inteiro).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/scheduled-reports/20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Excluído, sem corpo

http

HTTP/1.1 204 No Content

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	`id` não é um inteiro.	`{"error":"invalid id"}`
500	Agendamento não existe (inclusive se já foi excluído). O status é 500, não 404.	`{"error":"failed to delete scheduled report","detail":"scheduled report 20 not found"}`

Veja também

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

Agendar relatórios

Cria, lista, pausa e remove relatórios que a plataforma gera e envia por e-mail em CSV, todo dia, semana ou mês.

Listar agendamentos

GET/api/v1/admin/scheduled-reportsAdmin

Lista os agendamentos do marketplace

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamentos

json

{
  "scheduled_reports": [
    {
      "id": 20,
      "name": "Vendas semanais",
      "report_type": "sales",
      "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
      "schedule": "weekly",
      "recipients": [
        "financeiro@example.com"
      ],
      "is_active": true,
      "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "created_at": "2026-10-11T21:05:13"
    }
  ]
}

Campos da resposta

scheduled_reportsarray

Mais recentes primeiro. Só os agendamentos do marketplace, sem os de seller. Lista vazia se não houver nenhum.

scheduled_reports[].idinteger

Id do agendamento. É um inteiro, não um UUID.

scheduled_reports[].namestring

Nome dado ao agendamento.

scheduled_reports[].report_typestring

salescustomersinventorycommissionspaymentscategories

Qual relatório é enviado.

scheduled_reports[].filtersstring

Os filtros guardados, como um texto JSON (não um objeto). Você precisa fazer o parse.

scheduled_reports[].schedulestring

dailyweeklymonthly

Frequência.

scheduled_reports[].recipientsarray

E-mails que recebem o CSV.

scheduled_reports[].last_sent_atstring

Última execução, YYYY-MM-DDTHH:MM:SS. Ausente se nunca rodou.

scheduled_reports[].is_activeboolean

false pausa os envios automáticos.

scheduled_reports[].created_byuuid

Administrador que criou.

scheduled_reports[].created_atstring

Criação, YYYY-MM-DDTHH:MM:SS.

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"]}`
500	Falha ao ler os agendamentos.	`{"error":"failed to list scheduled reports","detail":"..."}`

Criar agendamento

POST/api/v1/admin/scheduled-reportsAdmin

Cria um relatório agendado

Corpo da requisição

namestringobrigatório

Nome do agendamento. Obrigatório.

report_typestringobrigatório

salescustomersinventorycommissionspaymentscategories

Qual relatório enviar. Obrigatório.

schedulestringobrigatório

dailyweeklymonthly

Frequência. Obrigatório. A data do relatório é calculada sozinha: daily envia o dia anterior, weekly os 7 dias anteriores até ontem, monthly o mês fechado anterior.

recipientsarray

E-mails de destino (lista de textos). Os endereços não são validados. Sem destinatário o relatório roda e é registrado, mas nada é enviado.

filtersobject

Filtros do relatório. As datas são ignoradas (o período vem da frequência); na prática só group_by e, no tipo categories, category_id mudam o CSV.

date_fromstring

Ignorado nos agendamentos recorrentes.

date_tostring

Ignorado nos agendamentos recorrentes.

compare_fromstring

Início da comparação. Aceito, mas o CSV enviado por e-mail não tem colunas de comparação.

compare_tostring

Fim da comparação. Igual ao anterior: sem efeito no CSV.

vendor_iduuid

category_iduuid

Limita a uma categoria. Só tem efeito no tipo categories.

group_bystring

dayweekmonth

Agrupamento da série.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas semanais", "report_type": "sales", "schedule": "weekly", "recipients": ["financeiro@example.com"], "filters": {"group_by": "day"}}'

Resposta

201Agendamento criado

json

{
  "id": 20,
  "name": "Vendas semanais",
  "report_type": "sales",
  "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
  "schedule": "weekly",
  "recipients": [
    "financeiro@example.com"
  ],
  "is_active": true,
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T21:05:13"
}

Campos da resposta

idinteger

Id do agendamento. É um inteiro, não um UUID.

namestring

Nome dado ao agendamento.

report_typestring

salescustomersinventorycommissionspaymentscategories

Qual relatório é enviado.

filtersstring

Os filtros guardados, como um texto JSON (não um objeto). Você precisa fazer o parse.

schedulestring

dailyweeklymonthly

Frequência.

recipientsarray

E-mails que recebem o CSV.

last_sent_atstring

Última execução, YYYY-MM-DDTHH:MM:SS. Ausente se nunca rodou.

is_activeboolean

false pausa os envios automáticos.

created_byuuid

Administrador que criou.

created_atstring

Criação, YYYY-MM-DDTHH:MM:SS.

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	Corpo não é JSON válido ou `name` vazio.	`{"error":"name is required"}`
500	`report_type` ou `schedule` inválido. Apesar de ser erro do chamador, o status é 500 (o texto traz o valor recusado).	`{"error":"failed to create scheduled report","detail":"invalid report_type: foo"}`

Pausar ou reativar

POST/api/v1/admin/scheduled-reports/{id}/toggleAdmin

Liga ou desliga um agendamento

Parâmetros de caminho

idintegerobrigatório

Id do agendamento (inteiro).

Corpo da requisição

is_activebooleanpadrão: false

true reativa, false pausa. Se omitido, vale false e o agendamento é pausado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/scheduled-reports/20/toggle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Resposta

200Atualizado

json

{
  "ok": true
}

Campos da resposta

okboolean

Sempre true quando o comando foi aceito.

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	`id` não é um inteiro, ou corpo inválido.	`{"error":"invalid id"}`

Excluir agendamento

DELETE/api/v1/admin/scheduled-reports/{id}Admin

Remove um agendamento

Parâmetros de caminho

idintegerobrigatório

Id do agendamento (inteiro).

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/scheduled-reports/20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Excluído, sem corpo

http

HTTP/1.1 204 No Content

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	`id` não é um inteiro.	`{"error":"invalid id"}`
500	Agendamento não existe (inclusive se já foi excluído). O status é 500, não 404.	`{"error":"failed to delete scheduled report","detail":"scheduled report 20 not found"}`