Relatórios (CRUD)

O servidor armazena definições de relatório e permite operações completas de criação, leitura, atualização e exclusão.

Listar — GET /api/v1/reports

Permissão: canList

Query params

Param	Tipo	Descrição
q	string	Busca full-text pelo nome/descrição
page	int	Página (começa em 1)
limit	int	Itens por página (1–100, default 20)

Resposta sem paginação

[
  {
    "id": "uuid",
    "name": "Sales Report",
    "description": "Monthly sales overview",
    "createdAt": "2026-04-06T12:00:00.000Z",
    "updatedAt": "2026-04-06T12:00:00.000Z",
    "storageKind": "inline"
  }
]

Resposta com paginação

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Detalhes — GET /api/v1/reports/:id

Permissão: canList

Retorna o relatório completo incluindo definitionJson, packageBytes, etc.

Status	Erro	Quando
404	not_found	ID não encontrado

Criar — POST /api/v1/reports

Permissão: canInsert

Body:

{
  "name": "My Report",
  "description": "Optional description",
  "definitionJson": "{ ... }",
  "packageBytes": "base64encoded..."
}

Campo	Obrigatório	Descrição
name	Sim	Nome do relatório (não vazio)
description	Não	Descrição
definitionJson	Não	JSON inline da definição
packageBytes	Não	Base64 do pacote .sulfite

Resposta 201: Metadados do relatório criado (id, name, description, createdAt, updatedAt, storageKind).

Status	Erro	Quando
400	validation_error	name ausente ou vazio
403	forbidden	Sem canInsert

Atualizar — PUT /api/v1/reports/:id

Permissão: canEdit

Body: Mesmos campos do POST (todos opcionais). Se name for fornecido, não pode ser vazio.

Resposta 200: Metadados atualizados.

Status	Erro	Quando
400	validation_error	name vazio
404	not_found	ID não encontrado

Excluir — DELETE /api/v1/reports/:id

Permissão: canDelete

Resposta 204: Sem body.

Status	Erro	Quando
404	not_found	ID não encontrado

Exemplo: fluxo completo

# Criar
curl -X POST http://localhost:8080/api/v1/reports \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vendas Mensal", "definitionJson": "{...}"}'

# Listar
curl http://localhost:8080/api/v1/reports \
  -H "Authorization: Bearer $TOKEN"

# Buscar
curl "http://localhost:8080/api/v1/reports?q=vendas" \
  -H "Authorization: Bearer $TOKEN"

# Atualizar
curl -X PUT http://localhost:8080/api/v1/reports/$ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Atualizado"}'

# Excluir
curl -X DELETE http://localhost:8080/api/v1/reports/$ID \
  -H "Authorization: Bearer $TOKEN"