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

bash
curl -X GET "$BASE_URL/api/v1/vendor/scheduled-reports" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Agendamentos
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"
    }
  ]
}

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

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"}}'

Resposta

201Agendamento criado
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"
}

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

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}'

Resposta

200Atualizado
json
{
  "ok": true
}

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

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/scheduled-reports/21" \
  -H "Authorization: Bearer $TOKEN"

Resposta

204Apagado, sem corpo
text

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