API Reference: Enquetes

Base URL: /api/enquetes. Todos os endpoints requerem autenticacao. Suporte a foto, push/email opcionais e enquetes nacionais.

POST /api/enquetes

Cria uma nova enquete no nucleo.

Permissao: COORDENADOR / ADMINISTRADOR

Body

Exemplo de body

{
  "pergunta": "Qual o melhor dia para a reuniao semanal?",
  "tipoEscolha": "UNICA",
  "opcoes": ["Segunda", "Quarta", "Sexta"],
  "fotoUrl": "https://storage.supabase.co/.../enquete.jpg",
  "dataEncerramento": "2026-04-15T23:59:00Z",
  "resultadoTempoReal": true,
  "modalObrigatorio": true,
  "enviarPush": true,
  "enviarEmail": true
}

GET /api/enquetes

Lista todas as enquetes do nucleo do usuario logado.

Permissao: Qualquer usuario autenticado

Response 200

[
  {
    "id": "uuid",
    "pergunta": "Qual o melhor dia para a reuniao semanal?",
    "tipoEscolha": "UNICA",
    "fotoUrl": "https://...",
    "dataEncerramento": "2026-04-15T23:59:00Z",
    "encerrada": false,
    "totalVotos": 12,
    "criado_em": "2026-04-01T10:00:00Z"
  }
]

GET /api/enquetes/:id

Retorna detalhes de uma enquete especifica, incluindo opcoes, status de voto do usuario e resultados.

Permissao: Qualquer usuario autenticado

Response 200

{
  "id": "uuid",
  "pergunta": "Qual o melhor dia para a reuniao semanal?",
  "tipoEscolha": "UNICA",
  "fotoUrl": "https://...",
  "opcoes": [
    { "id": "uuid-1", "texto": "Segunda" },
    { "id": "uuid-2", "texto": "Quarta" },
    { "id": "uuid-3", "texto": "Sexta" }
  ],
  "jaVotou": true,
  "meuVoto": "uuid-2",
  "resultados": [
    { "opcaoId": "uuid-1", "texto": "Segunda", "percentual": 25.0 },
    { "opcaoId": "uuid-2", "texto": "Quarta", "percentual": 58.3 },
    { "opcaoId": "uuid-3", "texto": "Sexta", "percentual": 16.7 }
  ],
  "encerrada": false
}

GET /api/enquetes/pendente-modal

Retorna a primeira enquete com modalObrigatorio=true que o usuario ainda nao votou. Retorna null se nao houver nenhuma pendente.

Permissao: Qualquer usuario autenticado

POST /api/enquetes/:id/votar

Registra o voto do usuario logado em uma enquete.

Permissao: Qualquer usuario autenticado

Body

{ "opcaoId": "uuid-2" }

Response 201

{ "message": "Voto registrado com sucesso" }

Erros

• 400 — Enquete ja encerrada ou usuario ja votou
• 404 — Enquete ou opcao nao encontrada

Foto em Enquetes

Enquetes suportam campo foto_url para imagem ilustrativa:

• Upload feito via componente FileUpload no bucket enquetes do Supabase Storage
• A foto e exibida acima da pergunta tanto no card da listagem quanto no modal obrigatorio

Push e Email Opcionais

Na criacao de enquetes, os checkboxes enviarPush e enviarEmail controlam se notificacoes push e emails sao enviados aos membros:

• Ambos sao habilitados por padrao (default: true)
• Quando enviarPush: true, o backend chama PushService.sendPushToAll()
• Quando enviarEmail: true, o backend chama MailService.sendToSegment() com tipo enquete
• Desmarcar ambos cria a enquete silenciosamente (apenas in-app)

Visibilidade de Resultados Parciais

Regras de visibilidade dos resultados enquanto a enquete esta aberta:

• Admin/Coordenador: Sempre veem os resultados parciais, independentemente da configuracao resultado_tempo_real
• Membros comuns: So veem resultados parciais se resultadoTempoReal=true
• Apos encerramento: Todos os membros veem os resultados finais

Modal Obrigatorio

Quando uma enquete e criada com modalObrigatorio=true, o componente EnqueteModal e renderizado dentro do dashboard-shell:

• O modal e exibido automaticamente ao acessar qualquer pagina do dashboard
• O usuario nao pode fechar o modal sem votar
• Apos votar, o modal e fechado e a navegacao normal e liberada
• O frontend consulta GET /api/enquetes/pendente-modal ao carregar o shell

Enquetes Nacional

Enquetes do nivel Nacional (sem nucleo_id) sao exibidas em todos os nucleos:

• Criadas pelo super admin via painel nacional
• Aparecem na listagem de enquetes de todos os nucleos com badge "Nacional"
• Votos sao contabilizados globalmente
• Push e email sao enviados para todos os nucleos quando habilitados
• O modal obrigatorio tambem funciona para enquetes nacionais

Frontend: Votacao Inline

• Enquetes sao exibidas como cards expansiveis na listagem
• Se possuir foto, a imagem e exibida no topo do card
• Ao expandir, o usuario ve as opcoes e pode votar diretamente
• Apos votar, os resultados sao exibidos como barras de progresso com percentual
• Enquetes encerradas mostram apenas os resultados finais