# Enquetes

> Como fazer uma pergunta à comunidade num espaço de Feed ou de Conteúdo: criar a enquete (opções, várias escolhas, prazo), votar, trocar e retirar o voto, quem vê o resultado e quando, editar, ver quem votou, encerrar, e as mesmas ações pela API e pelo assistente.

A **enquete** é um post com uma pergunta e de 2 a 10 opções para a comunidade votar. Ela nasce num espaço de [Feed](/espacos/feed) (como um status, em que a pergunta é o texto) ou de [Conteúdo](/espacos/conteudo) (como um post, em que a pergunta é o título), e no resto é um post como os outros: aparece no Feed, recebe reações e comentários, pode ser fixada e notifica como um post novo.

A enquete só existe em espaço de Feed ou de Conteúdo; em outro tipo de espaço, a API recusa.

## Para que serve

| Comunidade | Enquete |
|---|---|
| Evento | *"Qual o melhor mês para o APICON Rio?"*, com março, abril e maio |
| Escola online | *"Que tema você quer na próxima aula ao vivo?"*, com várias escolhas |
| Coworking | *"Que horário de limpeza atrapalha menos?"*, com prazo até sexta |
| Associação | Uma consulta rápida antes da assembleia, com o resultado fechado no fim do prazo |

## Como funciona

### Quem pode o quê

| Ação | Quem |
|---|---|
| Criar uma enquete | Proprietário, administrador e moderador |
| Votar, trocar e retirar o voto | Qualquer membro que vê o post |
| Ver o resultado | A equipe, sempre; os outros membros, depois de votar ou quando a enquete encerra |
| Editar, ver quem votou e encerrar | Proprietário, administrador e moderador |

O financeiro vota como qualquer membro, mas não cria nem gerencia enquetes. Quem vê o post sem estar logado encontra **Entre para votar**; quem está logado mas não é membro da comunidade vê *Só membros da comunidade votam*.

### Voto único ou várias escolhas

O card mostra o selo **Enquete** e, embaixo da pergunta, **Escolha uma opção** ou **Escolha uma ou mais opções**:

- **Uma opção**: clicar na opção já vota.
- **Várias escolhas** (quando a enquete foi criada com **Permitir várias escolhas**): a pessoa marca as opções e clica em **Votar**.

Depois de votar, a opção escolhida fica marcada como **Seu voto**, e aparecem **Trocar voto** e **Retirar voto**. Enquanto a enquete está aberta, dá para trocar ou retirar quantas vezes quiser.

### Quem vê o resultado

- **Membros** veem as barras com o percentual e o total **depois de votar**, ou quando a enquete **encerra**. Antes disso, o card mostra **Vote para ver o resultado**.
- **A equipe** (proprietário, administrador e moderador) vê o resultado sempre, tendo votado ou não.

O percentual de cada opção é sobre **quem votou**, não sobre o total de votos. Numa enquete de várias escolhas, a soma passa de 100%: se 10 pessoas votaram e 7 marcaram março, março tem 70%, mesmo que elas tenham marcado outras opções também. O rodapé diz *"N pessoas votaram"* (ou *Ninguém votou ainda*).

### Prazo e encerramento

Com **Prazo**, a enquete encerra sozinha na data e hora escolhidas, no fuso da comunidade, e o card mostra **Encerra em …** até lá. Sem prazo, ela fica aberta até alguém da equipe **Encerrar enquete**.

Encerrada, ela ganha o selo **Encerrada** e a linha **Encerrada em …**: ninguém mais vota, troca nem retira o voto, e todos veem o resultado final. Os votos ficam guardados. **Uma enquete encerrada não pode ser reaberta.**

### Votos anônimos para os membros

Os membros veem só os números. Quem votou em quê, só a equipe vê, em **Ver quem votou**.

### Notificação

A enquete segue o caminho de um post novo no espaço: as mesmas notificações e e-mails de um status no Feed ou de um post no Conteúdo, conforme as preferências de cada pessoa. Votar não notifica ninguém.

## Passo a passo

### Criar uma enquete

*Papel: proprietário, administrador ou moderador.*

1. Abra o espaço de Feed ou de Conteúdo.
2. No cabeçalho, clique na seta ao lado de **Novo Status** (no Conteúdo, **Novo Conteúdo**) e escolha **Nova enquete**. No mesmo menu fica **Importar conteúdo**, que só o proprietário e o administrador veem.
3. Preencha:
   - **Pergunta**: no Feed, é o texto do status (até 500 caracteres); no Conteúdo, é o título do post (até 255).
   - **Opções**: de 2 a 10, até 100 caracteres cada, sem repetir. **Adicionar opção** põe mais uma; o **×** remove.
   - **Permitir várias escolhas**: cada pessoa pode marcar mais de uma opção.
   - **Quem vê**, só no Feed: **Público** (o padrão), **Membros** ou **Assinantes**, como no **Novo Status**. No Conteúdo não há escolha: a enquete sai pública, como o **Novo Conteúdo**.
   - **Prazo (opcional)**: data e hora no fuso da comunidade, que a tela mostra. **Sem prazo** tira o prazo.
4. Clique em **Publicar enquete**.

No Conteúdo, o post nasce só com a pergunta como título. Para pôr um texto embaixo dela, edite o post depois.

### Votar

1. No card da enquete, clique na opção (no voto único, isso já vota).
2. Na enquete de várias escolhas, marque as opções e clique em **Votar**.
3. Para mudar, **Trocar voto**; para desistir, **Retirar voto**.

### Editar uma enquete

*Papel: proprietário, administrador ou moderador.*

No menu **⋮** do card, **Editar enquete**.

- **Antes do primeiro voto**, dá para mudar tudo: as opções (texto, ordem, incluir e remover), **Permitir várias escolhas** e o prazo.
- **Depois do primeiro voto**, as opções não mudam mais, nem o texto nem a ordem: os campos aparecem desabilitados (*"Já há votos: as opções não mudam mais, para não alterar o que as pessoas escolheram."*), e **Permitir várias escolhas** fica travado. A pergunta continua editável pelo post, e o prazo ainda pode ser posto, mudado ou tirado.
- **Encerrada sem votos**, só o texto das opções.

A pergunta é o texto (ou o título) do post: para mudá-la, edite o post.

### Ver quem votou

*Papel: proprietário, administrador ou moderador.*

No menu **⋮** do card, **Ver quem votou**. O diálogo **Quem votou** lista as pessoas, do voto mais recente para o mais antigo, com as opções de cada uma. **Filtrar por opção** mostra só quem escolheu uma delas.

### Encerrar

*Papel: proprietário, administrador ou moderador.*

1. No menu **⋮** do card, **Encerrar enquete**.
2. Confirme em **Encerrar**. Não tem volta: a enquete não pode ser reaberta.

## Exemplos

**Data do evento.** No Feed da Home: *"Qual o melhor mês para o APICON Rio?"*, com março, abril e maio, voto único e prazo até o fim do mês. Fixe no topo para todos verem.

**Tema da próxima aula.** Num espaço de Conteúdo da turma: *"Que tema você quer na próxima aula ao vivo?"*, com cinco temas e **Permitir várias escolhas**. A equipe acompanha o resultado desde o primeiro voto e encerra quando decidir.

## Erros comuns e como resolver

| Situação | O que fazer |
|---|---|
| Não aparece **Nova enquete** no menu | Só proprietário, administrador e moderador criam enquetes |
| *A enquete precisa de pelo menos 2 opções.* ou *A enquete pode ter até 10 opções.* | Ajuste o número de opções |
| *Há opções repetidas.* | Duas opções têm o mesmo texto (maiúsculas não contam): mude uma |
| *Escolha um prazo no futuro.* | O prazo já passou; escolha outra data ou deixe sem prazo |
| As opções não dão para editar | A enquete já tem votos: as opções ficam como foram votadas. Para outra pergunta, crie outra enquete |
| O membro não vê o resultado | Ele ainda não votou e a enquete está aberta |
| Não dá para votar | A enquete está encerrada |

## Perguntas frequentes

**Dá para reabrir uma enquete encerrada?**
Não. Para perguntar de novo, crie outra.

**Dá para transformar um post que já existe em enquete?**
Não. A enquete nasce com o post, em **Nova enquete**.

**Excluir o post apaga a enquete?**
Sim, a enquete vai junto com o post.

**Os membros sabem em quem eu votei?**
Não. Só a equipe vê quem votou em quê.

## Pelo assistente

O assistente cria, vota e acompanha enquetes com as mesmas regras:

- `create_poll`: cria no Feed (a pergunta é o texto) ou no Conteúdo (a pergunta é o título). Proprietário, administrador e moderador, sem confirmação.
- `get_poll`: o resultado. Qualquer papel; para quem não votou, os números ficam escondidos até a enquete encerrar.
- `vote_poll` (pela opção ou pelo texto dela) e `retract_poll_vote`: em nome de quem conectou, sem confirmação.
- `update_poll`: edita, e pede confirmação quando muda as opções. `close_poll`: encerra, sempre com confirmação. `list_poll_votes`: quem votou. As três são da equipe.

Peça assim: *"Crie uma enquete no Feed perguntando qual o melhor mês para o APICON Rio, com março, abril e maio."* No Claude, a receita **Perguntar à comunidade (enquete)** monta o pedido. Ver [Ferramentas · Conteúdo](/mcp/ferramentas-conteudo#enquetes).

## Na API

A enquete vai no campo `poll` de `POST /api/status` (Feed) e de `POST /api/content` (Conteúdo): `options` (de 2 a 10 textos), `allowMultiple` e `closesAt` (opcional, no futuro). Só proprietário, administrador e moderador; outro papel recebe `403` com `param: "poll"`, e nada é gravado. O `poll` vem nos itens de `GET /api/feed`, em status, em conteúdo e nas recomendações.

| Rota | O que faz | Quem |
|---|---|---|
| `GET /api/polls/{id}` | O resultado, como a pessoa pode ver | Quem vê o post |
| `POST /api/polls/{id}/vote` | Vota (`optionIds`); votar de novo troca o voto | Membro que vê o post |
| `DELETE /api/polls/{id}/vote` | Retira o voto | Membro que vê o post |
| `PUT /api/polls/{id}` | Edita opções, `allowMultiple` e `closesAt` | Proprietário, administrador e moderador |
| `POST /api/polls/{id}/close` | Encerra, sem volta | Proprietário, administrador e moderador |
| `GET /api/polls/{id}/votes` | Quem votou, com filtro `optionId` | Proprietário, administrador e moderador |

Para quem não pode ver o resultado, `resultsVisible` vem `false`, e `votes`, `percentage` e `totalVoters` vêm `null` (escondido, não zero).

| Erro | Quando |
|---|---|
| `400` | Espaço que não é de Feed nem de Conteúdo, menos de 2 ou mais de 10 opções, opção vazia ou com mais de 100 caracteres, opção repetida, prazo no passado ou inválido, mais de uma opção num voto único |
| `403` | O papel não cria ou não gerencia enquetes, ou a pessoa não é membro da comunidade |
| `404` | A enquete não existe ou é de outra comunidade |
| `409` | `closed` (a enquete está encerrada) ou `optionsLocked` (mudar as opções, inclusive o texto ou a ordem, depois do primeiro voto); também quando se tenta mudar `allowMultiple` com votos |

Ver [Polls](/api/referencia/polls).

## Relacionados

- [Feed](/espacos/feed)
- [Conteúdo](/espacos/conteudo)
- [Papéis e permissões](/conceitos/papeis-e-permissoes)
- [Ferramentas · Conteúdo](/mcp/ferramentas-conteudo#enquetes)