Documentación de Encuestum

Encuestum es una plataforma multi-tenant de encuestas y evaluaciones. Cualquiera con el link responde en el navegador; los docentes generan preguntas desde un documento y corrigen respuestas abiertas con IA; las empresas miden NPS con analítica de embudo. Esta página recorre las capacidades a fondo.

Editor y tipos de pregunta

El editor visual es drag-and-drop, con vista previa en vivo y plantillas listas para arrancar (NPS, feedback, registro a evento, evaluación de curso, quiz…).

14 tipos de pregunta: texto, párrafo, email, opción única / múltiple, desplegable, escala / NPS (con 6 presentaciones: números, rectángulos, gradiente de colores, estrellas, caritas y caritas de colores), sí/no, opción-imagen, matriz (grilla), ranking, fecha, subir archivo y respuesta en video (grabación por webcam, estilo Typeform).
Secciones para agrupar preguntas: páginas estilo Google Forms o portadas estilo Typeform.
Lógica condicional (mostrar según otra respuesta), bifurcación / saltos (ir a otra sección o terminar según la respuesta) y piping ({pregunta} en el texto).
Autosave en el editor: nunca perdés trabajo.

Diseño

Un panel de diseño completo, sin salir de la app:

Temas de un clic (claros y oscuros), modo oscuro de la encuesta, buscador de Google Fonts, y control de color de acento, fondo y texto.
Cuadros glass (color + opacidad + desenfoque), contenedor por pregunta, transiciones entre pantallas (fundido, deslizar, zoom, voltear, desenfoque) y alineación (izquierda / centro).
Imágenes: portada, logo, fondo con opacidad, e imagen por pregunta; además video embebido y música de fondo.
Estilo por pregunta: transparencia y alineación individuales.

Inteligencia artificial (bring-your-own-key)

Encuestum no incluye una API key de IA: usás la tuya. Es provider-agnostic — cualquier endpoint OpenAI-compatible (OpenRouter, OpenAI, Together, un LLM local…).

Genera preguntas

Desde un tema o desde un documento / markdown que pegás o subís, la IA arma un borrador de encuesta o examen que después editás a mano.

Corrige respuestas abiertas

Motor híbrido (rúbrica determinística + LLM): puntaje, veredicto, feedback, evidencia citada, needs_review e injection_flag, con doble pasada y resistencia a inyección de prompt.

Gestión de proveedores

Proveedores (OpenAI / OpenRouter / endpoint propio) por organización o globales, con listado de modelos en vivo y rastreo de consumo (tokens y costo aprox. por llamada).

Todo funciona sin key

Sin API key, el resto de la app anda igual (incluida la corrección determinística de preguntas cerradas); solo quedan inactivas la corrección por rúbrica con LLM, los insights y la generación de preguntas.

Distribución y control de acceso

Cada encuesta se sirve en una página pública /s/{slug} (SurveyJS en el navegador), con link personalizado editable, código QR, embed por iframe, links con prefill (?campo=valor) y guardar-y-retomar.

3 modos de acceso por encuesta:
- Pública — cualquiera con el link responde.
- Con clave (PIN) — una clave compartida para entrar.
- Lista de emails admitidos — cada persona con su código único (para entrar y para ver su resultado después) y link mágico por email.
Programación: fecha / hora de inicio y de cierre (en la zona horaria del servidor, ENCUESTUM_TIMEZONE) o cupo de respuestas. Antes de la apertura no se puede responder, y podés reabrir una cerrada con un clic.
Protección anti-bot opcional en encuestas públicas: un captcha proof-of-work self-hosted (sin terceros, sin keys, invisible para la persona) que frena el spam de respuestas.
Pantalla de gracias totalmente customizable: confeti, ícono / emoji / imagen, layouts (tarjeta / minimal / hero), colores propios, tokens (¡Gracias, {nombre}!), botones CTA, compartir (WhatsApp / X / LinkedIn) y redirect con cuenta regresiva.
Pantallas de estado personalizables: la de “analizando” (mientras la IA corrige) y la de “cerrada”, con título, mensaje, emoji, imagen o color de fondo, color de texto y spinner. Nada de pantallas en blanco.

Evaluaciones y educación

Modo examen con integridad: mezclar preguntas / opciones, tiempo límite e intentos configurables. Del lado del docente: cola de revisión, override manual de la nota, gradebook (planilla de notas por alumno) y certificado imprimible al aprobar.

Resultados y analítica

Panel “Resumen” con gráficos por pregunta (barras, histograma NPS con promedio, respuestas abiertas, archivos / videos).
Embudo de conversión: vistas → comenzaron → completaron, con dónde abandonan.
Export CSV / Excel, duplicar encuesta, notificaciones por email al recibir respuestas, webhooks firmados (HMAC) para Zapier / Google Sheets / Make, y borrado de respuesta individual (GDPR).

Plataforma

Encuestum es multi-tenant de fábrica:

Organizaciones con roles owner / admin / member, invitaciones, reset de contraseña y verificación de email.
Subdominio propio por organización con branding (acme.tudominio.com) — definís ENCUESTUM_BASE_DOMAIN, apuntás un DNS comodín y emitís un certificado wildcard.
Panel de super-admin de la plataforma.
Interfaz en 7 idiomas: English, Español, Français, Português, Italiano, 中文, 日本語.
Almacenamiento de archivos directo a Cloudflare R2 / S3 con URL prefirmada: el servidor no toca los archivos grandes, el bucket queda privado y los archivos de respuesta solo los ven miembros de la organización.

Federación con la Suite (Lockatus / SSO)

Por defecto Encuestum usa cuentas locales. Con AUTH_MODE=federado delega el login en Lockatus, el SSO OIDC de la Escriba Suite (login unificado + 2FA + roles): el hub pone la identidad y Encuestum crea al usuario y su organización en el primer ingreso.

Arquitectura

Encuestum es FastAPI + SQLModel + Alembic (SQLite por defecto / Postgres) en el backend, y Next.js 16 (App Router) + SurveyJS + Tailwind en el frontend. Se empaqueta como una sola imagen all-in-one (nginx + Next + FastAPI) donde el frontend habla con el backend same-origin.

Stack: FastAPI · SQLModel · Alembic · asyncpg / aiosqlite · PyJWT + bcrypt · boto3 (R2 / S3) · Next.js 16 · React 19 · SurveyJS (MIT) · Tailwind. Bring-your-own-key para el LLM.