Encuestas
Gestione encuestas, trabaje con variables ocultas y configuraciones
Descripción general
La API de Encuestas/Cuestionarios le permite crear encuestas mediante programación, gestionar preguntas, configurar ajustes, manejar variables ocultas, controlar el ciclo de vida de la encuesta (duplicar, renombrar, archivar, eliminar) y gestionar los textos de etiquetas predeterminados.
Descarga la versión en markdown de la sección "Encuestas" para usar en ChatGPT / otros LLMs:
Crear y editar
Esta sección cubre la creación de una nueva encuesta y el guardado de sus preguntas.
Crear encuesta
Crea una nueva encuesta en la carpeta especificada y devuelve el objeto de encuesta.
Cuerpo de la solicitud (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| folder_id | integer | Sí | ID de la carpeta en la que crear la encuesta |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"folder_id": 5}' Respuesta exitosa (201)
{
"id": 124,
"workspace_id": 1,
"name": "Survey #12",
"virtual_id": "abc12xyz",
"url_preview": "https://example.com/quiz/124/preview",
"url_shared": "https://example.com/q/abc12xyz",
"is_published": false
} Posibles errores
| HTTP | Código | Descripción |
|---|---|---|
| 400 | workspace_not_found, folder_not_found | Espacio de trabajo o carpeta no encontrado |
| 401 | user_not_authenticated | Token de autorización inválido o ausente |
| 403 | quiz_limit_today | Se alcanzó el límite diario de creación de encuestas para esta cuenta |
| 422 | validation_error | Error de validación del cuerpo de la solicitud |
Preguntas de la encuesta
Guarde el conjunto completo de preguntas de una encuesta usando el endpoint /quiz/{id}/save.
Guarda la estructura completa de preguntas de la encuesta. Reemplaza el conjunto de preguntas existente.
Cuerpo de la solicitud (JSON)
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| ids | array | Sí | Array ordenado de identificadores de preguntas (UUIDs, "welcome", "submit") |
| entities | object | Sí | Objeto que mapea cada ID de pregunta a su objeto de datos completo |
Valores de ids
El array ids contiene identificadores de preguntas en orden de visualización. Valores especiales:
| Valor | Descripción |
|---|---|
| welcome | Pantalla de bienvenida (página de introducción) |
| submit | Pantalla de finalización (página de agradecimiento) |
| UUID | UUID — una pregunta regular |
Campos comunes para todos los tipos de pregunta
| Campo | Tipo | Descripción |
|---|---|---|
| type | string | Obligatorio. Identificador del tipo de pregunta (ver tabla de tipos) |
| title | string | Título / texto de etiqueta de la pregunta |
| withTitle | boolean | Mostrar el campo de título |
| description | string | Texto de descripción / subtítulo de la pregunta |
| withDescription | boolean | Mostrar el campo de descripción |
| isRequired | boolean | Marcar la pregunta como obligatoria |
| isBlocked | boolean | Bloquear la pregunta (ocultar a los encuestados) |
| multimedia | object \| null | Objeto multimedia (imagen, vídeo, audio) o null |
| filling_time_enabled | boolean | Habilitar límite de tiempo por pregunta |
| filling_time_seconds | integer | Límite de tiempo para la pregunta en segundos |
Tipos de pregunta
| type | Nombre | Descripción |
|---|---|---|
| welcome | Pantalla de bienvenida | Pantalla de introducción / bienvenida |
| yesno | Sí / No | Pregunta de Sí / No |
| choice | Opción | Selección única o múltiple de una lista de opciones |
| dropdown | Desplegable | Selección de lista desplegable |
| ranking | Clasificación | Clasificación de opciones mediante arrastrar y soltar |
| slider | Control deslizante | Control deslizante con mín./máx./paso configurables |
| rating | Valoración | Escala de valoración con estrellas, corazones o emojis |
| scale | Escala | Escala numérica (p. ej. 1–10) |
| input | Entrada de texto | Entrada de texto corto o largo |
| Correo electrónico | Campo de entrada de correo electrónico | |
| phone | Teléfono | Campo de entrada de número de teléfono |
| datetime | Fecha y hora | Selector de fecha y/o hora |
| matrix | Matriz | Cuadrícula de matriz (filas × columnas) |
| message | Mensaje | Bloque de mensaje estático o información |
| file | Carga de archivo | Carga de archivo |
| html | Bloque HTML | Bloque de contenido HTML personalizado |
| submit | Pantalla de envío | Pantalla de finalización / agradecimiento |
Estructura del objeto multimedia
| Campo | Descripción |
|---|---|
| type | img, video, audio |
| imgUrl | URL de la imagen |
| videoUrl | URL del vídeo |
| imgLocation | Posición de la imagen: top, left, right, background |
| videoSettings | Objeto de configuración del reproductor de vídeo |
Campos adicionales por tipo de pregunta
Reglas de validación
- Todos los valores en ids deben ser únicos
- Cada valor en ids debe tener una entrada correspondiente en entities
- Cada clave en entities debe estar presente en ids
- Cada objeto de entidad debe tener un campo type
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": ["welcome", "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "submit"],
"entities": {
"welcome": { "type": "welcome", "title": "Welcome", "welcomeLabel": "Start" },
"a1b2c3d4-e5f6-7890-abcd-ef1234567890": { "type": "rating", "title": "Rate the service", "ratingCount": 5, "ratingFigure": "star" },
"submit": { "type": "submit", "submitLabel": "Submit" }
}
}' Errores
| HTTP | Descripción |
|---|---|
| 400 | Encuesta no encontrada |
| 401 | Se requiere autorización |
| 403 | Acceso a la encuesta denegado |
| 422 | Error de validación: ids y entities son inconsistentes |
| 500 | Error interno del servidor al guardar la estructura de la encuesta |
Obtener lista de encuestas
Devuelve una lista paginada de todas las encuestas activas (no archivadas).
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| sort | string | No | Campo por el que ordenar (p. ej. name, created_at) |
| order | string | No | Dirección de ordenación: asc o desc |
| limit | integer | No | Número máximo de encuestas a devolver |
| offset | integer | No | Número de encuestas a omitir (desplazamiento de paginación) |
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz?sort=name&order=asc&limit=10&offset=0" \
-H "Authorization: Bearer YOUR_TOKEN" [
{
"id": "survey ID",
"name": "name",
"url_shared": "survey URL",
"is_published": true,
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My Surveys",
"pos": 1,
"is_default": true,
"created_at": "2022-04-01T08:37:14.000000Z",
"updated_at": "2022-04-27T15:46:27.000000Z",
"deleted_at": null
}
}
] Obtener datos de la encuesta
Devuelve el objeto de datos completo de una encuesta específica, incluyendo todas las preguntas y configuraciones.
curl -X GET https://api.surveyninja.io/api/v3/service/quiz/123 \
-H "Authorization: Bearer YOUR_TOKEN" {
"id": "survey ID",
"answer_count": "number of responses",
"name": "name",
"url_shared": "survey URL",
"widgets": "question structure (ids, entities)",
"hidden_options": "hidden variable",
"folder": {
"id": 384,
"workspace_id": 384,
"user_id": 12,
"name": "My Surveys",
"pos": 1,
"is_default": true,
"created_at": "2022-04-01T08:37:14.000000Z",
"updated_at": "2022-04-27T15:46:27.000000Z",
"deleted_at": null
}
} Configuración de la encuesta
Actualiza uno o más grupos de configuración de una encuesta. Todos los parámetros son opcionales — solo se actualizarán los campos que envíe.
Básico
| Parámetro | Tipo | Descripción |
|---|---|---|
| name | string | Nombre / título de la encuesta |
| lang | string | Código de idioma de la interfaz de la encuesta (p. ej. en, ru) |
| info_title | string | Título interno de la encuesta (mostrado en el panel) |
| description | string | Descripción SEO meta para la página de la encuesta |
Visualización
| Parámetro | Tipo | Descripción |
|---|---|---|
| show_progressbar | boolean | Mostrar barra de progreso |
| show_navigate | boolean | Mostrar botones de navegación (Atrás / Siguiente) |
| numeration | boolean | Mostrar números de pregunta |
| auto_move_by_enter | boolean | Avanzar automáticamente a la siguiente pregunta al pulsar Enter |
| show_by_one | boolean | Mostrar una pregunta a la vez |
| allow_multiple_answer | boolean | Permitir múltiples envíos desde el mismo encuestado |
| show_copyright | boolean | Mostrar el pie de derechos de autor de SurveyNinja |
Acceso y restricciones
| Parámetro | Tipo | Descripción |
|---|---|---|
| close_quiz_enabled | boolean | Cerrar la encuesta (dejar de aceptar respuestas) |
| limit_time_enabled | boolean | Habilitar fecha límite de respuesta |
| limit_time_value | string | Fecha límite de respuesta (cadena de fecha y hora) |
| limit_time_timezone | string | Zona horaria para la fecha límite (p. ej. Europe/Madrid) |
| limit_answer_count_enabled | boolean | Limitar el número total de respuestas |
| limit_answer_count_value | integer | Maximum number of responses |
| use_password | boolean | Proteger la encuesta con contraseña |
| multiple_ip | boolean | Permitir múltiples respuestas desde la misma dirección IP |
| show_captcha | boolean | Mostrar CAPTCHA antes del envío |
| ip_list_enabled | boolean | Habilitar filtrado por dirección IP |
| ip_whitelist | string | Lista de direcciones IP permitidas separadas por comas |
| ip_blacklist | string | Lista de direcciones IP bloqueadas separadas por comas |
| available_devices[] | array | Dispositivos permitidos: desktop, mobile, tablet |
Comportamiento
| Parámetro | Tipo | Descripción |
|---|---|---|
| scoring_switcher | boolean | Habilitar modo de puntuación |
| question_required_mode | string | individual / all_required / all_optional |
| question_random_order | boolean | Aleatorizar el orden de las preguntas |
| disable_auto_redirect | boolean | Deshabilitar la redirección automática tras el envío |
| block_jump_to_prev_widget | boolean | Impedir que los encuestados vuelvan a preguntas anteriores |
| filling_time_enabled | boolean | Habilitar límite de tiempo total de la encuesta |
| filling_time_seconds | integer | Límite de tiempo de la encuesta en segundos |
Analítica y código QR
| Parámetro | Tipo | Descripción |
|---|---|---|
| scripts_in_head | string | Scripts personalizados insertados en |
| scripts_in_body | string | Scripts personalizados insertados antes de |
| scripts_in_head_enabled | boolean | Habilitar scripts en el head |
| scripts_in_body_enabled | boolean | Habilitar scripts en el body |
| sso_active | boolean | Habilitar inicio de sesión único (SSO) |
| qr_code_size | integer | Tamaño del código QR en píxeles |
| qr_code_color | string | Color de primer plano del código QR (HEX) |
| qr_code_background_color | string | Color de fondo del código QR (HEX) |
| qr_code_margin | integer | Margen del código QR en píxeles |
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/settings/info" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "New survey name",
"lang": "en",
"show_progressbar": true,
"limit_answer_count_enabled": true,
"limit_answer_count_value": 500,
"question_required_mode": "all_required"
}' Gestión de encuestas
Los siguientes endpoints le permiten gestionar el ciclo de vida de las encuestas: agregar notas, duplicar, renombrar, convertir en plantilla, archivar, mover y eliminar.
Ciclo de vida de la encuesta
Guarda la estructura completa de preguntas de la encuesta (reemplaza las preguntas existentes).
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/save" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"ids": ["welcome", "question-1", "submit"],
"entities": {
"welcome": { "type": "welcome", "...": "..." },
"question-1": { "type": "choice", "title": "...", "...": "..." },
"submit": { "type": "submit", "...": "..." }
}
}' Aplica un tema de diseño a la encuesta.
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/applyTheme/925" \
-H "Authorization: Bearer YOUR_API_TOKEN" Publica el borrador actual de la encuesta para que los encuestados puedan acceder a él.
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/publish" \
-H "Authorization: Bearer YOUR_API_TOKEN" Guarda la lógica de ramificación (condiciones de omisión/salto) para la encuesta.
curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/conditions" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"conditions": {
"...": "logic structure, same as in the builder"
}
}' Agregar nota
Agrega o actualiza una nota (comentario interno) adjunta a la encuesta.
Parámetros de la solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| notes | string | Sí | Texto de la nota (máximo 1000 caracteres) |
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/note \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"notes": "Note text (maximum 1000 characters)"
}' {
"status": true,
"notes": "Note text"
} Duplicar encuesta
Crea una copia completa de la encuesta incluyendo todas las preguntas y configuraciones.
Parámetros de la solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | No | Nombre para la encuesta duplicada (opcional; por defecto es una copia del nombre original) |
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/duplicate \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Copy name (optional)"
}' {
"status": true,
"quiz": {
"id": 123,
"name": "Copy: Survey Name",
"url_shared": "https://example.com/abc123",
"is_published": false,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"folder": {
"id": 1,
"name": "My Folder"
}
}
} Renombrar encuesta
Cambia el nombre de la encuesta.
Parámetros de la solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| name | string | Sí | Nuevo nombre de la encuesta |
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/rename \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "New survey name"
}' {
"status": true,
"name": "New survey name"
} Convertir en plantilla
Marca la encuesta como plantilla reutilizable disponible en la galería de plantillas.
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/template \
-H "Authorization: Bearer YOUR_TOKEN" {
"status": true
} Archivar encuesta
Archiva o desarchiva una encuesta. Las encuestas archivadas no aceptan nuevas respuestas.
Parámetros de la solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| archive | boolean | Sí | true — archivar la encuesta, false — desarchivar |
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/archive \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"archive": true
}' {
"status": true,
"archive_at": "2024-01-01T12:00:00Z",
"is_archived": true
} Mover encuesta
Mueve la encuesta a una carpeta diferente dentro del mismo espacio de trabajo.
Parámetros de la solicitud
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
| folder_id | integer | Sí | ID de la carpeta de destino |
curl -X POST https://api.surveyninja.io/api/v3/service/quiz/123/move \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 5
}' {
"status": true,
"folder_id": 5,
"folder": {
"id": 5,
"name": "New Folder"
}
} Eliminar encuesta
Elimina permanentemente una encuesta junto con todas sus respuestas. Esta acción no se puede deshacer.
curl -X DELETE https://api.surveyninja.io/api/v3/service/quiz/123 \
-H "Authorization: Bearer YOUR_TOKEN" {
"status": true
} Encuestas archivadas
Devuelve la lista de encuestas archivadas.
curl -X GET https://api.surveyninja.io/api/v3/service/quiz/archived \
-H "Authorization: Bearer YOUR_TOKEN" [
{
"id": 123,
"name": "Archived survey",
"url_shared": "https://example.com/abc123",
"is_published": false,
"created_at": "2024-01-01T12:00:00Z",
"updated_at": "2024-01-01T12:00:00Z",
"archive_at": "2024-01-02T12:00:00Z",
"folder": {
"id": 1,
"name": "My Folder"
}
}
] Textos predeterminados
Los textos predeterminados son los botones y etiquetas de interfaz que se muestran a los encuestados (p. ej. Siguiente, Atrás, Enviar). Recupere los valores actuales y personalícelos por encuesta.
Obtener textos predeterminados GET /api/v3/service/quiz/{id}/default-texts
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
| lang | string | ru | Código de idioma para el que recuperar las etiquetas (p. ej. ru, en) |
Devuelve un array de objetos de etiqueta, cada uno con code, standard_text y user_text (personalización o null).
curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts?lang=ru" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" Ejemplo de respuesta
[
{ "code": "btn_next", "standard_text": "Next", "user_text": null },
{ "code": "btn_back", "standard_text": "Back", "user_text": "Go Back" },
{ "code": "btn_submit", "standard_text": "Submit", "user_text": null }
] Actualizar textos predeterminados POST /api/v3/service/quiz/{id}/default-texts
Actualiza los textos de etiquetas personalizados para la encuesta. Envíe text: null para restablecer al texto estándar.
| Parámetro | Tipo | Descripción |
|---|---|---|
| texts[] | array | Array de objetos con los campos code y text |
| texts[].code | string | Código de etiqueta de la respuesta GET |
| texts[].text | string|null | Nuevo texto; null restablece al valor estándar |
400 blocked_by_tariff — la funcionalidad no está disponible en el plan actual. curl -X POST "https://api.surveyninja.io/api/v3/service/quiz/123/default-texts" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"texts": [
{ "code": "btn_next", "text": "Forward" },
{ "code": "btn_back", "text": null }
]
}'