Modo Consumidor

O modo consumidor oferece uma API simplificada e somente-leitura para aplicações que apenas consomem relatórios. Ideal para:

• Portais de autoatendimento
• Aplicações embedadas (iframe)
• Integrações que só precisam listar e baixar relatórios

Permissões mínimas

O modo consumidor funciona com o preset de permissão consumer:

Permissão	Valor
can_list	✅
can_generate	✅
Todas as demais	❌

Endpoints

Catálogo — GET /api/v1/consumer/reports

Permissão: canList

Query params: ?page=1&limit=20 (paginação opcional)

Retorna uma lista leve (sem a definição completa) dos relatórios disponíveis:

[
  {
    "id": "uuid",
    "name": "Sales Report",
    "description": "Monthly sales overview",
    "updatedAt": "2026-04-06T12:00:00.000Z",
    "formats": ["pdf", "html", "csv", "excel"]
  }
]

---

Metadados — GET /api/v1/consumer/reports/:id

Permissão: canList

Retorna metadados do relatório com informações sobre parâmetros:

{
  "id": "uuid",
  "name": "Sales Report",
  "description": "Monthly sales overview",
  "updatedAt": "2026-04-06T12:00:00.000Z",
  "formats": ["pdf", "html", "csv", "excel"],
  "hasParams": true,
  "paramCount": 3
}

Status	Erro	Quando
404	not_found	ID não encontrado

---

Esquema de parâmetros — GET /api/v1/consumer/reports/:id/params

Permissão: canList

Retorna o schema dos parâmetros aceitos pelo relatório:

{
  "parameters": [
    {
      "id": "date_start",
      "label": "Data Início",
      "type": "date",
      "required": true,
      "defaultValue": "2026-01-01",
      "options": ["2026-01-01", "2026-02-01"]
    },
    {
      "id": "region",
      "label": "Região",
      "type": "string",
      "required": false,
      "defaultValue": null,
      "options": ["Norte", "Sul", "Leste", "Oeste"]
    }
  ]
}

Status	Erro	Quando
404	not_found	ID não encontrado
422	invalid_report	Definição inválida

---

Gerar e baixar — GET /api/v1/consumer/reports/:id/output

Permissão: canGenerate

Query params: Todos os query params (exceto format) são passados como parâmetros do relatório.

Param	Descrição
format	Formato de saída: pdf, html, csv, excel (default: pdf)
*	Demais params são passados ao relatório

Exemplo: /consumer/reports/abc123/output?format=pdf&date_start=2026-01-01&region=Sul

Resposta 200: Binário do arquivo com Content-Type e Content-Disposition apropriados.

Status	Erro	Quando
400	invalid_format	Formato não suportado
404	not_found	ID não encontrado
422	invalid_report	Definição inválida
422	generation_failed	Erro na renderização

Exemplo: portal de autoatendimento

// Token consumer — sem acesso a settings/edit/delete
const API = 'https://servidor.com/api/v1/consumer';
const headers = { 'Authorization': 'Bearer <consumer-token>' };

// 1. Listar relatórios disponíveis
const reports = await fetch(`${API}/reports`, { headers }).then(r => r.json());

// 2. Obter parâmetros de um relatório
const params = await fetch(`${API}/reports/${id}/params`, { headers })
  .then(r => r.json());

// 3. Gerar e baixar
const qs = new URLSearchParams({ format: 'pdf', date_start: '2026-01-01' });
const output = await fetch(`${API}/reports/${id}/output?${qs}`, { headers });
const blob = await output.blob();

// 4. Exibir no iframe ou baixar
const url = URL.createObjectURL(blob);
iframe.src = url;