Formato de presentación de encuestas
El formato de presentación de encuestas es el contrato JSON para realizar paso a paso una sesión de encuesta en curso. Cada pregunta llega como un documento autónomo que contiene todo lo que un cliente necesita para presentarla —título, especificación del control de entrada y opciones válidas—, mientras el motor QML mantiene en el servidor la lógica del flujo, la ramificación y la validación de las respuestas.
Un cuestionario es la plantilla verificada; una encuesta es la sesión en la que un encuestado la recorre. El formato de presentación describe siempre una encuesta: la siguiente pregunta para este encuestado, calculada a partir de sus respuestas anteriores.
Independiente del framework por diseño
Sección titulada «Independiente del framework por diseño»El formato no contiene, a propósito, ningún HTML, CSS ni referencia a componentes:
- Sus componentes de interfaz: presente cada control con su propio framework (React, Vue, Angular, una aplicación móvil nativa o un terminal)
- Su estilo: las preguntas adoptan con naturalidad el aspecto de su aplicación
- Lógica en el servidor: la ramificación, la lógica de saltos y la validación de poscondiciones permanecen en el motor QML verificado; un cliente no puede llegar a un recorrido no válido por la forma en que presenta las preguntas
- Una sola ida y vuelta por pregunta: al enviar una respuesta, la respuesta del servidor incluye el siguiente paso
El propio ejecutor de encuestas de Askalot (SirWay) es un cliente de este mismo modelo de ítems: el formato no es una exportación secundaria, sino la forma en que realmente se realizan las encuestas.
El ciclo del flujo
Sección titulada «El ciclo del flujo»Llevar una encuesta de principio a fin es una máquina de estados de tres llamadas a la API REST:
| Método | Punto de conexión | Finalidad |
|---|---|---|
GET |
/api/v1/surveys/{id}/current-step |
Pregunta actual + opciones + estado. Inicializa la sesión en la primera llamada. |
POST |
/api/v1/surveys/{id}/responses |
Envía una respuesta; la respuesta del servidor incluye el siguiente paso. |
POST |
/api/v1/surveys/{id}/finish |
Completa explícitamente la encuesta (idempotente). |
Las mismas tres operaciones están disponibles como herramientas MCP (get_survey_current_item, submit_survey_response, finish_survey); consulte Herramientas de encuesta — Referencia de herramientas MCP.
La autenticación es la credencial REST estándar: el encabezado X-Api-Token (configuración del token).
GET current-step ──► render item ──► POST responses ──► render `next` │ └── status == "completed" ──► doneLos ítems informativos Comment se procesan automáticamente en el servidor: los clientes solo reciben preguntas que pueden responderse.
El documento de paso
Sección titulada «El documento de paso»GET /api/v1/surveys/{id}/current-step devuelve:
{ "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "status": "in_progress", "control_type": "switch", "required": true, "message": null, "item": { "id": "q_question_switch", "kind": "Question", "text": null, "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "extras": { "title": "Do you agree to participate in this survey?", "blockId": "block2", "input": { "control": "Switch", "true": "Yes", "false": "No" }, "outcome": null, "visited": false } }, "options": [ { "value": true, "text": "Yes" }, { "value": false, "text": "No" } ]}| Campo | Significado |
|---|---|
status |
"in_progress" o "completed". Cuando está completada, item es null y message explica el motivo. |
item.id |
El identificador QML del ítem; devuélvalo al enviar la respuesta. |
item.kind |
"Question", "QuestionGroup" o "MatrixQuestion"; determina la forma del resultado que envía. |
item.extras.title |
El título de la pregunta que debe mostrarse. |
item.text |
Texto descriptivo opcional, más largo, bajo el título. |
item.extras.input |
La especificación QML en bruto del control de entrada (nombre del control y su configuración: etiquetas, rangos, etc.). |
control_type |
Discriminador del control en minúsculas para la capa de presentación: radio, dropdown, checkbox, switch, slider, range, editbox, textarea. |
options |
Opciones listas para presentar, ya extraídas del control (véase más abajo). |
required |
Si hace falta una respuesta para avanzar. |
Las respuestas son códigos numéricos
Sección titulada «Las respuestas son códigos numéricos»Askalot representa las respuestas como números en todas partes salvo en el texto abierto (el control textarea). Las labels de un control de elección asignan códigos de respuesta enteros a textos visibles —p. ej., {1: "Hourly", 2: "Daily", 3: "Weekly"}—, y el documento de paso los entrega como pares options ({"value": <code>, "text": <label>}). Su interfaz muestra el text; lo que usted envía es el código. Las entradas numéricas (editbox, slider) envían el propio número, range envía el intervalo como un par [low, high], y switch es el código 1/0 (que en las opciones se entrega como true/false; los booleanos se aceptan como sus equivalentes numéricos).
La serialización JSON puede convertir los códigos en cadenas durante la transmisión (el ejemplo de más abajo muestra "value": "0" para la clave de etiqueta 0); el motor vuelve a convertir en números las cadenas numéricas al recibir el envío, pero es preferible enviar números reales.
Opciones según el tipo de control
Sección titulada «Opciones según el tipo de control»El array options llega ya preparado en una forma presentable para cada control:
control_type |
Forma de options |
|---|---|
radio, dropdown, checkbox |
[{ "value": <integer answer code>, "text": <label> }, ...] |
slider |
[{ "type": "range", "min": 0, "max": 100, "step": 1 }] |
switch |
[{ "value": true, "text": "Yes" }, { "value": false, "text": "No" }] |
editbox, range, textarea |
[]: lea los límites (min/max, controles numéricos) o la configuración del texto en item.extras.input |
Envío de respuestas
Sección titulada «Envío de respuestas»POST /api/v1/surveys/{id}/responses con el identificador del ítem y el resultado:
{ "item_id": "q_question_switch", "outcome": true }La forma del resultado depende del tipo de ítem. Los valores son los códigos de respuesta numéricos descritos más arriba; texto libre solo en el control textarea:
| Tipo de ítem / control | Forma del resultado | Ejemplo |
|---|---|---|
Question (radio, dropdown, slider, editbox) |
Un único número: el código de respuesta (controles de elección) o el propio valor (controles numéricos) | 2, 42 |
Question con control range |
Un par [low, high] con min <= low <= high <= max |
[20, 45] |
Question con control switch |
1/0 (se aceptan true/false) |
true |
Question con control checkbox |
Entero de máscara de bits: la suma de los códigos de respuesta seleccionados (los códigos son potencias de 2) | 5 (códigos 1 + 4) |
Question con control textarea |
Cadena de texto libre | "We mostly use it on weekends" |
QuestionGroup |
Array de números, uno por cada entrada de questions; todas las subpreguntas comparten el control único del grupo, así que todos los valores proceden del mismo espacio de códigos |
[1, 3, 2] |
MatrixQuestion |
Array anidado de números, rows × columns; un control compartido para todas las celdas |
[[1, 2], [3, 1]] |
Con un control range, cada subpregunta de un QuestionGroup y cada celda de una MatrixQuestion es un par [low, high] en lugar de un número ([[1, 3], [2, 6]] para un grupo de dos preguntas).
La respuesta del servidor incluye el siguiente paso, así que basta con una ida y vuelta por pregunta:
{ "survey_id": "c154e81f-4c19-4998-9ffc-df6fee50561f", "status": "in_progress", "output": null, "next": { "control_type": "radio", "item": { "id": "q_question_radio", "kind": "Question", "extras": { "title": "Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris?", "input": { "control": "Radio", "labels": { "0": "Option 0", "1": "Option 1" } } } }, "options": [ { "value": "0", "text": "Option 0" }, { "value": "1", "text": "Option 1" } ], "required": true, "status": "in_progress" }}Cuando el envío completa la encuesta, status es "completed" y next es null.
Validación en el servidor
Sección titulada «Validación en el servidor»Las poscondiciones escritas en el QML (p. ej., el número de hijos debe ser menor que el de miembros del hogar) se evalúan al recibir el envío. Una respuesta rechazada devuelve una respuesta de error cuyo detail contiene el mensaje de ayuda de la pregunta, y el flujo no avanza: vuelva a presentar el ítem actual con el mensaje de ayuda. El cliente nunca necesita replicar las reglas de validación; residen en la definición formal del cuestionario.
Patrón de integración habitual
Sección titulada «Patrón de integración habitual»- Cree encuestas para sus encuestados mediante la API REST (
POST /api/v1/surveys) o mediante una campaña - Su backend hace de intermediario de las tres llamadas del flujo con su token de API (mantenga el token en el servidor; nunca lo envíe a un navegador)
- Su frontend presenta cada documento de paso con sus propios componentes y devuelve los resultados
- Con
status: "completed", cierre la sesión; las respuestas están disponibles de inmediato para el proceso de datos
Si no necesita una presentación personalizada, el ejecutor de encuestas alojado de Askalot (SirWay) ya sirve cada encuesta en un enlace mágico; el formato de presentación es para cuando la encuesta debe formar parte de la experiencia de su producto.