# Encuestas

> Cómo hacer una pregunta a la comunidad en un espacio de Feed o de Contenido: crear la encuesta (opciones, varias respuestas, plazo), votar, cambiar y retirar el voto, quién ve el resultado y cuándo, editar, ver quién votó, cerrar, y las mismas acciones por la API y por el asistente.

La **encuesta** es una publicación con una pregunta y de 2 a 10 opciones para que la comunidad vote. Nace en un espacio de [Feed](/espacos/feed) (como un estado, donde la pregunta es el texto) o de [Contenido](/espacos/conteudo) (como una publicación, donde la pregunta es el título), y en lo demás es una publicación como las otras: aparece en el Feed, recibe reacciones y comentarios, se puede fijar y notifica como una publicación nueva.

La encuesta solo existe en espacios de Feed o de Contenido; en otro tipo de espacio, la API la rechaza.

## Para qué sirve

| Comunidad | Encuesta |
|---|---|
| Evento | *"¿Cuál es el mejor mes para el APICON Rio?"*, con marzo, abril y mayo |
| Escuela online | *"¿Qué tema quieres en la próxima clase en vivo?"*, con varias respuestas |
| Coworking | *"¿Qué horario de limpieza molesta menos?"*, con plazo hasta el viernes |
| Asociación | Una consulta rápida antes de la asamblea, con el resultado cerrado al final del plazo |

## Cómo funciona

### Quién puede qué

| Acción | Quién |
|---|---|
| Crear una encuesta | Propietario, administrador y moderador |
| Votar, cambiar y retirar el voto | Cualquier miembro que ve la publicación |
| Ver el resultado | El equipo, siempre; los demás miembros, después de votar o cuando la encuesta se cierra |
| Editar, ver quién votó y cerrar | Propietario, administrador y moderador |

El financiero vota como cualquier miembro, pero no crea ni gestiona encuestas. Quien ve la publicación sin haber iniciado sesión encuentra **Inicia sesión para votar**; quien inició sesión pero no es miembro de la comunidad ve *Solo los miembros de la comunidad votan*.

### Una respuesta o varias

La tarjeta muestra la etiqueta **Encuesta** y, debajo de la pregunta, **Elige una opción** o **Elige una o más opciones**:

- **Una opción**: hacer clic en la opción ya vota.
- **Varias respuestas** (cuando la encuesta se creó con **Permitir varias respuestas**): la persona marca las opciones y hace clic en **Votar**.

Después de votar, la opción elegida queda marcada como **Tu voto**, y aparecen **Cambiar voto** y **Retirar voto**. Mientras la encuesta está abierta, se puede cambiar o retirar cuantas veces se quiera.

### Quién ve el resultado

- **Los miembros** ven las barras con el porcentaje y el total **después de votar**, o cuando la encuesta **se cierra**. Antes, la tarjeta muestra **Vota para ver el resultado**.
- **El equipo** (propietario, administrador y moderador) ve el resultado siempre, haya votado o no.

El porcentaje de cada opción es sobre **quien votó**, no sobre el total de votos. En una encuesta de varias respuestas, la suma pasa del 100%: si votaron 10 personas y 7 marcaron marzo, marzo tiene el 70%, aunque también hayan marcado otras opciones. El pie dice *"N personas votaron"* (o *Nadie ha votado todavía*).

### Plazo y cierre

Con **Plazo**, la encuesta se cierra sola en la fecha y hora elegidas, en la zona horaria de la comunidad, y la tarjeta muestra **Cierra el …** hasta entonces. Sin plazo, queda abierta hasta que alguien del equipo haga clic en **Cerrar encuesta**.

Cerrada, recibe la etiqueta **Cerrada** y la línea **Cerrada el …**: ya nadie vota, cambia ni retira el voto, y todos ven el resultado final. Los votos se conservan. **Una encuesta cerrada no se puede reabrir.**

### Votos anónimos para los miembros

Los miembros solo ven los números. Quién votó qué, solo lo ve el equipo, en **Ver quién votó**.

### Notificación

La encuesta sigue el camino de una publicación nueva en el espacio: las mismas notificaciones y correos de un estado en el Feed o de una publicación en Contenido, según las preferencias de cada persona. Votar no notifica a nadie.

## Paso a paso

### Crear una encuesta

*Rol: propietario, administrador o moderador.*

1. Abre el espacio de Feed o de Contenido.
2. En la cabecera, haz clic en la flecha junto a **Nuevo Estado** (en Contenido, **Nuevo Contenido**) y elige **Nueva encuesta**. En el mismo menú está **Importar contenido**, que solo ven el propietario y el administrador.
3. Completa:
   - **Pregunta**: en el Feed, es el texto del estado (hasta 500 caracteres); en Contenido, es el título de la publicación (hasta 255).
   - **Opciones**: de 2 a 10, hasta 100 caracteres cada una, sin repetir. **Añadir opción** pone una más; la **×** la quita.
   - **Permitir varias respuestas**: cada persona puede marcar más de una opción.
   - **Quién la ve**, solo en el Feed: **Público** (por defecto), **Miembros** o **Suscriptores**, como en **Nuevo Estado**. En Contenido no hay elección: la encuesta sale pública, como **Nuevo Contenido**.
   - **Plazo (opcional)**: fecha y hora en la zona horaria de la comunidad, que la pantalla muestra. **Sin plazo** lo quita.
4. Haz clic en **Publicar encuesta**.

En Contenido, la publicación nace solo con la pregunta como título. Para poner un texto debajo, edita la publicación después.

### Votar

1. En la tarjeta de la encuesta, haz clic en la opción (en una encuesta de una respuesta, eso ya vota).
2. En una encuesta de varias respuestas, marca las opciones y haz clic en **Votar**.
3. Para cambiar, **Cambiar voto**; para desistir, **Retirar voto**.

### Editar una encuesta

*Rol: propietario, administrador o moderador.*

En el menú **⋮** de la tarjeta, **Editar encuesta**.

- **Antes del primer voto**, se puede cambiar todo: las opciones (texto, orden, añadir y quitar), **Permitir varias respuestas** y el plazo.
- **Después del primer voto**, las opciones ya no cambian, ni el texto ni el orden: los campos aparecen deshabilitados (*"Ya hay votos: las opciones ya no cambian, para no alterar lo que la gente eligió."*), y **Permitir varias respuestas** queda bloqueado. La pregunta sigue editable desde la publicación, y el plazo todavía se puede poner, cambiar o quitar.
- **Cerrada sin votos**, solo el texto de las opciones.

La pregunta es el texto (o el título) de la publicación: para cambiarla, edita la publicación.

### Ver quién votó

*Rol: propietario, administrador o moderador.*

En el menú **⋮** de la tarjeta, **Ver quién votó**. El diálogo **Quién votó** lista a las personas, del voto más reciente al más antiguo, con las opciones de cada una. **Filtrar por opción** muestra solo a quien eligió una de ellas.

### Cerrar

*Rol: propietario, administrador o moderador.*

1. En el menú **⋮** de la tarjeta, **Cerrar encuesta**.
2. Confirma en **Cerrar**. No tiene vuelta atrás: la encuesta no se puede reabrir.

## Ejemplos

**Fecha del evento.** En el Feed de Home: *"¿Cuál es el mejor mes para el APICON Rio?"*, con marzo, abril y mayo, una respuesta y plazo hasta fin de mes. Fíjala arriba para que todos la vean.

**Tema de la próxima clase.** En un espacio de Contenido de la clase: *"¿Qué tema quieres en la próxima clase en vivo?"*, con cinco temas y **Permitir varias respuestas**. El equipo sigue el resultado desde el primer voto y la cierra cuando decida.

## Errores frecuentes y cómo resolverlos

| Situación | Qué hacer |
|---|---|
| No aparece **Nueva encuesta** en el menú | Solo el propietario, el administrador y el moderador crean encuestas |
| *La encuesta necesita al menos 2 opciones.* o *La encuesta puede tener hasta 10 opciones.* | Ajusta el número de opciones |
| *Hay opciones repetidas.* | Dos opciones tienen el mismo texto (las mayúsculas no cuentan): cambia una |
| *Elige un plazo en el futuro.* | El plazo ya pasó; elige otra fecha o déjala sin plazo |
| Las opciones no se pueden editar | La encuesta ya tiene votos: las opciones quedan como se votaron. Para otra pregunta, crea otra encuesta |
| El miembro no ve el resultado | Todavía no votó y la encuesta está abierta |
| No se puede votar | La encuesta está cerrada |

## Preguntas frecuentes

**¿Se puede reabrir una encuesta cerrada?**
No. Para preguntar de nuevo, crea otra.

**¿Se puede convertir una publicación existente en encuesta?**
No. La encuesta nace con la publicación, en **Nueva encuesta**.

**¿Eliminar la publicación borra la encuesta?**
Sí, la encuesta se va con la publicación.

**¿Los miembros saben qué voté?**
No. Solo el equipo ve quién votó qué.

## Por el asistente

El asistente crea, vota y sigue encuestas con las mismas reglas:

- `create_poll`: la crea en el Feed (la pregunta es el texto) o en Contenido (la pregunta es el título). Propietario, administrador y moderador, sin confirmación.
- `get_poll`: el resultado. Cualquier rol; para quien no votó, los números quedan ocultos hasta que la encuesta se cierre.
- `vote_poll` (por la opción o por su texto) y `retract_poll_vote`: en nombre de quien conectó, sin confirmación.
- `update_poll`: edita, y pide confirmación cuando cambia las opciones. `close_poll`: cierra, siempre con confirmación. `list_poll_votes`: quién votó. Las tres son del equipo.

Pídelo así: *"Crea una encuesta en el Feed preguntando cuál es el mejor mes para el APICON Rio, con marzo, abril y mayo."* En Claude, la receta **Preguntar a la comunidad (encuesta)** arma el pedido. Consulta [Herramientas · Contenido](/mcp/ferramentas-conteudo#encuestas).

## En la API

La encuesta va en el campo `poll` de `POST /api/status` (Feed) y de `POST /api/content` (Contenido): `options` (de 2 a 10 textos), `allowMultiple` y `closesAt` (opcional, en el futuro). Solo propietario, administrador y moderador; otro rol recibe `403` con `param: "poll"`, y no se guarda nada. `poll` viene en los ítems de `GET /api/feed`, en estados, en contenido y en las recomendaciones.

| Ruta | Qué hace | Quién |
|---|---|---|
| `GET /api/polls/{id}` | El resultado, como la persona puede verlo | Quien ve la publicación |
| `POST /api/polls/{id}/vote` | Vota (`optionIds`); votar de nuevo cambia el voto | Miembro que ve la publicación |
| `DELETE /api/polls/{id}/vote` | Retira el voto | Miembro que ve la publicación |
| `PUT /api/polls/{id}` | Edita opciones, `allowMultiple` y `closesAt` | Propietario, administrador y moderador |
| `POST /api/polls/{id}/close` | Cierra, sin vuelta atrás | Propietario, administrador y moderador |
| `GET /api/polls/{id}/votes` | Quién votó, con filtro `optionId` | Propietario, administrador y moderador |

Para quien no puede ver el resultado, `resultsVisible` viene en `false`, y `votes`, `percentage` y `totalVoters` vienen en `null` (oculto, no cero).

| Error | Cuándo |
|---|---|
| `400` | Espacio que no es de Feed ni de Contenido, menos de 2 o más de 10 opciones, opción vacía o de más de 100 caracteres, opción repetida, plazo en el pasado o inválido, más de una opción en un voto de una respuesta |
| `403` | El rol no crea ni gestiona encuestas, o la persona no es miembro de la comunidad |
| `404` | La encuesta no existe o es de otra comunidad |
| `409` | `closed` (la encuesta está cerrada) u `optionsLocked` (cambiar las opciones, incluidos el texto o el orden, después del primer voto); también al intentar cambiar `allowMultiple` con votos |

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

## Relacionados

- [Feed](/espacos/feed)
- [Contenido](/espacos/conteudo)
- [Roles y permisos](/conceitos/papeis-e-permissoes)
- [Herramientas · Contenido](/mcp/ferramentas-conteudo#encuestas)