Exportações

Relatório mensal de 300 pessoas não sai numa request HTTP. As exportações entram numa fila como pending, um worker processa em segundo plano e o arquivo fica disponível para download por 24 horas.

Headers obrigatórios

Todas as requisições devem incluir X-Timesheet-Id e Authorization: Bearer {token}. Profissionais só enxergam e geram exportações dos próprios dados (o filtro timesheetUserId é forçado para o autenticado); gestores podem exportar qualquer escopo.

---

Estrutura de Dados

Campo	Tipo	Descrição
kind	String	Tipo do relatório: monthly_sheet, project_billing ou payroll.
format	String	Formato do arquivo — atualmente somente csv (padrão).
status	String	pending, processing, completed ou failed.
startsOn / endsOn	Date	Janela do relatório (YYYY-MM-DD).
filters	Object	Filtros aplicados (timesheetUserId, timesheetProjectId).
fileUrl	String	Caminho do arquivo gerado (preenchido ao concluir).
fileSizeBytes	Number	Tamanho do arquivo.
errorMessage	String	Motivo da falha (quando failed).
expiresAt	DateTime	Expiração do arquivo — 24h após a conclusão.
completedAt	DateTime	Quando a geração terminou.

Tipos de Relatório

kind	Conteúdo	Fonte
monthly_sheet	Espelho de ponto diário (uma linha por dia: expectativa, trabalhado, saldo, extras, primeira entrada e última saída).	Daily Sheet
project_billing	Horas e valores por projeto, com pendente de fatura e orçamento consumido.	Project Billing
payroll	Totais por profissional consolidados mês a mês sobre toda a janela (dias trabalhados, horas, extras, custo e faturamento).	Monthly Totals

---

Endpoints

GET  /v1/timesheet/exports
POST /v1/timesheet/exports
GET  /v1/timesheet/exports/:id
GET  /v1/timesheet/exports/:id/download

Listar Exportações

Aceita page, perPage, status, kind e timesheetUserId (somente gestores). Profissionais listam apenas as próprias exportações.

Solicitar Exportação

Cria o registro como pending e enfileira o job de geração imediatamente.

POST /v1/timesheet/exports

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
kind	string	Sim	monthly_sheet, project_billing ou payroll.
format	string	Não	csv (padrão).
startsOn	date	Sim	Início da janela (YYYY-MM-DD).
endsOn	date	Sim	Fim da janela (>= startsOn).
filters	object	Não	Filtros do relatório.
filters.timesheetUserId	number	Não	Profissional (ignorado/forçado para não-gestores).
filters.timesheetProjectId	number	Não	Projeto (para project_billing).

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/exports" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "monthly_sheet",
    "startsOn": "2026-08-01",
    "endsOn": "2026-08-31"
  }'

Respostas

201 Created

Retorna o ID da exportação para acompanhamento: { "id": 1 }.

Acompanhar Status

GET /v1/timesheet/exports/:id

Consulte até o status virar completed (ou failed, com errorMessage). Profissionais recebem 404 para exportações de terceiros.

Exemplo de Resposta

{
  "id": 1,
  "timesheetId": 4,
  "timesheetUserId": 5,
  "kind": "monthly_sheet",
  "format": "csv",
  "status": "completed",
  "startsOn": "2026-09-01",
  "endsOn": "2026-09-30",
  "filters": {
    "timesheetUserId": 5
  },
  "fileUrl": "tmp/exports/timesheet-4-export-1-monthly_sheet.csv",
  "fileSizeBytes": 465,
  "errorMessage": null,
  "expiresAt": "2026-09-26T12:33:59.809-03:00",
  "createdAt": "2026-09-25T12:33:59.723-03:00",
  "completedAt": "2026-09-25T12:33:59.811-03:00"
}

Baixar Arquivo

GET /v1/timesheet/exports/:id/download

Respostas

200 OK

Retorna o arquivo CSV (text/csv) para download — primeira linha com os cabeçalhos do relatório.

422 Unprocessable Entity

O arquivo expirou — 24h após a conclusão, é preciso gerar uma nova exportação.

{
  "message": "Exportação expirada, gere uma nova",
  "code": "EXPORT_EXPIRED"
}

404 Not Found

Exportação inexistente, de outro profissional, ou ainda não concluída (pending/processing/failed).

---

Processamento (Fila)

A geração roda fora da request HTTP, na fila timesheet_exports (Redis/BullMQ), processada pelo job generate-timesheet-export. Para que as exportações saiam de pending, o worker precisa estar rodando:

node ace queue:listen

O worker grava o CSV em tmp/exports/, atualiza o registro para completed com fileUrl, fileSizeBytes, completedAt e expiresAt (+24h). Falhas marcam o registro como failed com errorMessage.