VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Indicadores e relatórios

Relatórios agendados

Cria, lista, liga/desliga e apaga os envios automáticos de relatório por e-mail do seller.

Um relatório agendado envia, por e-mail, um CSV do período recém-encerrado, em frequência fixa: diário (o dia anterior), semanal (os 7 dias até ontem) ou mensal (o mês anterior inteiro). Cada agendamento pertence ao seller que o criou e o CSV só contém dados dele. O envio roda de hora em hora na plataforma, então o e-mail chega no horário cheio seguinte à elegibilidade, não numa hora escolhida. Exige o privilégio de ajustes do seller.

Listar agendamentos

Devolve todos os agendamentos do seller, sem paginação.

GET/api/v1/vendor/scheduled-reportsSeller

Listar agendamentos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

Resposta

200Agendamentos

Campos da resposta

scheduled_reportsobject[]

Os agendamentos.

idinteger
Id do agendamento (inteiro, não UUID).
namestring
Nome dado pelo seller.
report_typestring
salesinventorycommissionspaymentscategories
Tipo do relatório.
filtersstring
Os filtros guardados, como texto JSON (não um objeto). As datas são recalculadas a cada envio, então date_from e date_to guardados são ignorados.
schedulestring
dailyweeklymonthly
Frequência.
recipientsstring[]
E-mails que recebem o CSV.
is_activeboolean
Se o agendamento está ligado.
created_byuuid
Usuário que criou.
created_atstring
Criação, AAAA-MM-DDThh:mm:ss sem fuso.
last_sent_atstring
Último envio. Ausente se nunca enviou.
vendor_iduuid
Seller dono do agendamento, sempre o do token.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
500Falha ao listar.{"error":"failed to list scheduled reports"}

Criar agendamento

Cria um agendamento ativo. A primeira execução acontece no próximo ciclo horário, porque ainda não houve envio.

POST/api/v1/vendor/scheduled-reportsSeller

Criar agendamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

namestringobrigatório
Nome do agendamento. Obrigatório e não pode ser vazio.
report_typestringobrigatório
salesinventorycommissionspaymentscategories
Tipo de relatório. customers é recusado para sellers porque agregaria clientes de toda a loja.
schedulestringobrigatório
dailyweeklymonthly
Frequência.
recipientsstring[]
E-mails de destino. Sem destinatário o relatório roda mas ninguém recebe.
filtersobject
Filtros opcionais, como group_by (day, week, month). As datas são ignoradas: o período vem da frequência. vendor_id é sempre trocado pelo seu seller.

Exemplo de requisição

Resposta

201Agendamento criado

Campos da resposta

(campos / fields)object
Os mesmos campos da listagem.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid JSON body"}
400name vazio.{"error":"name is required"}
400report_type ou schedule inválido.{"error":"failed to create scheduled report","detail":"invalid report_type for vendor schedule: customers"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
Os e-mails não são validados

A API guarda recipients como veio, sem checar o formato. Valide no seu lado: um endereço errado só aparece como falha de entrega depois.

Sem execução manual nem histórico para o seller

O painel do administrador tem "executar agora" e histórico de execuções; estas rotas do seller não. Para testar, crie um agendamento com daily, aguarde o próximo ciclo e confira o e-mail.

Ligar ou desligar

Liga ou desliga um agendamento sem apagá-lo. Desligado, ele deixa de enviar e continua listado.

PUT/api/v1/vendor/scheduled-reports/{id}/toggleSeller

Ligar ou desligar

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

idintegerobrigatório
Id do agendamento (número inteiro).

Corpo da requisição

is_activebooleanobrigatório
true liga, false desliga. Se omitido, vale false (desliga).

Exemplo de requisição

Resposta

200Atualizado

Erros

StatusQuandoCorpo de exemplo
400id que não é número, ou corpo que não é JSON.{"error":"invalid id"}
404Agendamento inexistente ou de outro seller.{"error":"failed to update scheduled report","detail":"scheduled report 99999 not found"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}

Apagar agendamento

Apaga o agendamento. A ação não tem volta.

DELETE/api/v1/vendor/scheduled-reports/{id}Seller

Apagar agendamento

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idintegerobrigatório
Id do agendamento (número inteiro).

Exemplo de requisição

Resposta

204Apagado, sem corpo

Erros

StatusQuandoCorpo de exemplo
400id que não é número.{"error":"invalid id"}
404Agendamento inexistente ou de outro seller.{"error":"failed to delete scheduled report","detail":"scheduled report 99999 not found"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}

Veja também

  • Exportar CSV
  • Relatórios de vendas
Anterior
Exportar relatório em CSV
Próxima
Configuração de métricas
Nesta página
  • Listar agendamentos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar agendamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ligar ou desligar
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar agendamento
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X GET "$BASE_URL/api/v1/vendor/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN"
text
bash
curl -X POST "$BASE_URL/api/v1/vendor/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"}}'
bash
curl -X PUT "$BASE_URL/api/v1/vendor/scheduled-reports/21/toggle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'
bash
curl -X DELETE "$BASE_URL/api/v1/vendor/scheduled-reports/21" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "scheduled_reports": [
    {
      "id": 21,
      "name": "Vendas semanais",
      "report_type": "sales",
      "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
      "schedule": "weekly",
      "recipients": [
        "financeiro@example.com"
      ],
      "is_active": true,
      "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
      "created_at": "2026-10-11T21:05:37",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
    }
  ]
}
json
{
  "id": 21,
  "name": "Vendas semanais",
  "report_type": "sales",
  "filters": "{\"format\": \"\", \"date_to\": \"\", \"group_by\": \"day\", \"date_from\": \"\", \"vendor_id\": \"94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36\", \"compare_to\": \"\", \"category_id\": \"\", \"compare_from\": \"\"}",
  "schedule": "weekly",
  "recipients": [
    "financeiro@example.com"
  ],
  "is_active": true,
  "created_by": "0fd409fb-9869-4c50-a18c-a810a19abeed",
  "created_at": "2026-10-11T21:05:37",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
}
json
{
  "ok": true
}