API REST
Askalot ofrece una API REST para acceder mediante programación a todas las capacidades de la plataforma. La API le permite automatizar los procesos de encuesta, integrarse con sistemas externos y crear aplicaciones propias sobre la plataforma Askalot.
Primeros pasos
Sección titulada «Primeros pasos»URL base
Sección titulada «URL base»https://portor.<tenant>.askalot.io/api/v1Sustituya <tenant> por el nombre del inquilino de su organización (p. ej., portor.acme.askalot.io).
Autenticación
Sección titulada «Autenticación»Todas las solicitudes a la API requieren autenticación mediante un token de API personal.
Generar un token:
- Inicie sesión en
https://roundtable.<tenant>.askalot.io - Vaya a Configuración del perfil
- Desplácese hasta la sección «Tokens de API»
- Haga clic en «Generar nuevo token»
- Copie el token (solo se muestra una vez)
Usar el token:
Incluya el token en la cabecera X-Api-Token:
curl -H "X-Api-Token: your_token_here" \ https://portor.<tenant>.askalot.io/api/v1/projectsPropiedades del token:
- Formato: los tokens llevan el prefijo
aslat_(aslat_<32 characters>); el prefijo permite que los escáneres de secretos detecten un commit accidental. En el servidor solo se guarda el prefijo para identificarlo: el token completo se muestra una vez al crearlo y nunca más. - Cabecera: envíelo en la cabecera
X-Api-Token. Esta es la vía de credenciales de REST; en Portor, la cabeceraAuthorization: Bearerestá reservada a los tokens de acceso OAuth (los que lleva una sesión MCP, que REST también acepta), no a los tokens de API. - Alcance: autentica solo la API REST y no lo acepta la interfaz MCP. Un token pertenece a la organización en la que estaba trabajando cuando lo generó: cada solicitud que hace actúa en esa organización, con los roles que usted tiene en ella; un rol que tenga en otra organización no se aplica. Para trabajar en otra organización por REST, cambie a ella en el navegador y genere allí un token. Si un administrador le retira de esa organización, sus tokens se revocan junto con la membresía.
- Revocación: puede revocarlo en cualquier momento desde Configuración del perfil; la revocación es inmediata.
Vigencia y rotación de los tokens
Sección titulada «Vigencia y rotación de los tokens»Al crear un token, usted elige su caducidad: el desplegable de Configuración del perfil ofrece 30 días, 90 días (el valor predeterminado) o 1 año. La caducidad es obligatoria; los tokens nuevos no tienen la opción de «no caducar nunca» (solo algunos tokens antiguos, conservados por compatibilidad, pueden carecer de ella).
- La página Configuración del perfil muestra la fecha de caducidad y los días restantes de cada token, y marca un token para su rotación cuando le quedan 14 días o menos para caducar.
- Para rotarlo: cree un token de sustitución, actualice su integración para que lo use y revoque el antiguo. Los tokens no se renuevan automáticamente: un token caducado devuelve
401y debe sustituirse.
Documentación interactiva
Sección titulada «Documentación interactiva»Explore la API de forma interactiva con Swagger UI en:
https://portor.<tenant>.askalot.io/api/v1/docsLa documentación interactiva le permite:
- Examinar todos los puntos de conexión disponibles
- Ver los esquemas de solicitud y de respuesta
- Probar llamadas a la API directamente en el navegador
Recursos principales
Sección titulada «Recursos principales»Proyectos
Sección titulada «Proyectos»Los proyectos son los contenedores de nivel superior en los que se organiza su investigación mediante encuestas.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/projects |
Lista todos los proyectos |
POST |
/api/v1/projects |
Crea un proyecto nuevo |
GET |
/api/v1/projects/{id} |
Obtiene un proyecto por su ID |
PUT |
/api/v1/projects/{id} |
Actualiza un proyecto |
DELETE |
/api/v1/projects/{id} |
Elimina un proyecto |
POST |
/api/v1/projects/{id}/owners |
Añade propietarios al proyecto |
DELETE |
/api/v1/projects/{id}/owners |
Retira propietarios del proyecto |
Ejemplo: crear un proyecto
curl -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey" }'Respuesta:
{ "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Customer Satisfaction Study", "description": "Q1 2026 customer feedback survey", "created_at": "2026-01-02T10:30:00Z", "questionnaire_ids": [], "campaign_ids": []}Cuestionarios
Sección titulada «Cuestionarios»Los cuestionarios definen la estructura de la encuesta mediante QML (Questionnaire Markup Language).
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/questionnaires |
Lista todos los cuestionarios |
POST |
/api/v1/questionnaires |
Crea un cuestionario nuevo |
GET |
/api/v1/questionnaires/{id} |
Obtiene un cuestionario por su ID |
PUT |
/api/v1/questionnaires/{id} |
Actualiza un cuestionario |
DELETE |
/api/v1/questionnaires/{id} |
Elimina un cuestionario |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations |
Lista las traducciones de una versión, por idioma (completa, claves sin traducir, congelada, editada por una persona) |
GET |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Obtiene la traducción a un idioma con sus textos de origen |
PUT |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Guarda texto traducido (texts, base_updated_at); parcial, combinado con lo almacenado |
DELETE |
/api/v1/questionnaires/{id}/versions/{version_id}/translations/{locale} |
Elimina la traducción a un idioma (se rechaza una vez congelada) |
Parámetros de consulta:
project_id: filtra por proyectostatus: filtra por estado (draft,active,paused,completed)
Campañas
Sección titulada «Campañas»Las campañas vinculan cuestionarios con encuestados para la recogida de datos.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/campaigns |
Lista todas las campañas |
POST |
/api/v1/campaigns |
Crea una campaña nueva |
GET |
/api/v1/campaigns/{id} |
Obtiene una campaña por su ID |
PUT |
/api/v1/campaigns/{id} |
Actualiza una campaña |
DELETE |
/api/v1/campaigns/{id} |
Elimina una campaña |
PUT |
/api/v1/campaigns/{id}/pool |
Asigna un grupo de encuestados a la campaña |
GET |
/api/v1/campaigns/{id}/pool |
Obtiene el grupo asignado a la campaña |
PUT |
/api/v1/campaigns/{id}/questionnaire |
Cambia el cuestionario de la campaña |
POST |
/api/v1/campaigns/{id}/interviewers |
Añade entrevistadores a la campaña |
DELETE |
/api/v1/campaigns/{id}/interviewers |
Retira entrevistadores de la campaña |
Parámetros de consulta:
project_id: filtra por proyectoquestionnaire_id: filtra por cuestionariostatus: filtra por estadoexpand=true: incluye los objetos relacionados (proyecto, cuestionario, encuestados)
Crear una campaña: POST /api/v1/campaigns requiere name, project_id, questionnaire_id y offers_ai_channel. offers_ai_channel (booleano) indica si los encuestados pueden responder también a la encuesta en su propio asistente de IA. No tiene valor predeterminado, y una solicitud que no lo incluya se rechaza. Cuando es true, también son obligatorios intro_text y consent_text. Consulte Autoentrevista asistida por IA.
Modos de campaña:
Askalot admite dos modos de campaña:
- Modo directo: los encuestados completan las encuestas por su cuenta mediante enlaces únicos
- Modo con entrevistador: los entrevistadores administran las encuestas a los encuestados por teléfono o en persona
El modo se determina automáticamente según haya o no entrevistadores asignados a la campaña.
Cada encuesta registra además su propio modo (direct, ai_assisted o field_interview) en su campo mode. Una encuesta es ai_assisted cuando la campaña ofrece el asistente de IA y el encuestado dio allí su consentimiento antes de responder.
Encuestados
Sección titulada «Encuestados»Los encuestados son los destinatarios de las encuestas: las personas a las que se encuesta.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/respondents |
Lista todos los encuestados |
POST |
/api/v1/respondents |
Crea un encuestado nuevo |
GET |
/api/v1/respondents/{id} |
Obtiene un encuestado por su ID |
PUT |
/api/v1/respondents/{id} |
Actualiza un encuestado |
DELETE |
/api/v1/respondents/{id} |
Elimina un encuestado |
Parámetros de consulta:
source_system: filtra por origen (p. ej.,crm,panel_provider)campaign_id: filtra por campaña
Nota: los entrevistadores son usuarios con el rol interviewer. Se gestionan a través del punto de conexión /api/v1/users.
Ejemplo: importar un encuestado
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Smith", "email": "[email protected]", "age": 35, "gender": "female", "location": "New York", "external_id": "CRM-12345", "source_system": "salesforce", "custom_attributes": {"state": "NY", "zip_code": "10001"} }'Campos demográficos:
Los encuestados admiten datos demográficos para la segmentación y el análisis:
age: edad del encuestadogender: identidad de génerolocation: ubicación geográfica (texto libre, normalmente"City, Country")external_id: el identificador en su sistemasource_system: origen de los datos del encuestadopreferred_language: idioma preferido opcional (en,es,fr,de,hu), que se usa para la invitación y como idioma preseleccionado de la encuesta cuando la campaña lo ofrece
La geografía más detallada que location —calle, ciudad, estado o provincia, código postal y país como valores separados— va en custom_attributes, y se puede referenciar como custom_attributes.<key> en cualquier lugar donde se pueda nombrar un atributo del encuestado (factores de muestreo, correspondencias de datos de entrada externos). Un objetivo de calibración nombra la columna del conjunto de datos a la que se extrajo el atributo, _custom_<key>. Las claves adicionales de nivel superior se ignoran en lugar de guardarse, de modo que una exportación de CRM que envía city como campo propio pierde ese valor sin aviso.
Encuestas
Sección titulada «Encuestas»Las encuestas registran cada sesión de encuesta y sus respuestas.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/surveys |
Lista todas las encuestas |
POST |
/api/v1/surveys |
Crea una nueva sesión de encuesta |
GET |
/api/v1/surveys/{id} |
Obtiene una encuesta por su ID |
PUT |
/api/v1/surveys/{id} |
Actualiza el estado de la encuesta |
DELETE |
/api/v1/surveys/{id} |
Elimina una encuesta |
GET |
/api/v1/surveys/{id}/current-step |
Pregunta actual + opciones + estado (Formato de presentación de encuestas) |
POST |
/api/v1/surveys/{id}/responses |
Envía una respuesta; el paso siguiente se incluye en la respuesta |
POST |
/api/v1/surveys/{id}/finish |
Completa explícitamente la encuesta (idempotente) |
Parámetros de consulta:
questionnaire_id: filtra por cuestionariocampaign_id: filtra por campañarespondent_id: filtra por encuestadostatus: filtra por estado (pending,in_progress,completed)expand=true: incluye los objetos relacionados
Las respuestas de la API sobre encuestas incluyen status y un booleano derivado de solo lectura, completed (true exactamente cuando status es completed). La finalización se expresa actualizando status: no existe ningún parámetro de entrada ni de filtro completed.
Responder a una encuesta mediante POST /api/v1/surveys/{id}/responses está limitado a pruebas y simulaciones: se rechaza una encuesta para la que ya se envió una invitación, de modo que no se puede escribir mediante programación en una entrevista real de trabajo de campo. Las respuestas enviadas así se registran como generadas por máquina, y sus tiempos de respuesta se excluyen de la detección de encuestados demasiado rápidos (speeders).
Grupos de encuestados
Sección titulada «Grupos de encuestados»Los grupos de encuestados reúnen a los encuestados en conjuntos reutilizables para las campañas.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/respondent-pools |
Lista todos los grupos de encuestados |
POST |
/api/v1/respondent-pools |
Crea un grupo nuevo |
GET |
/api/v1/respondent-pools/{id} |
Obtiene un grupo por su ID |
DELETE |
/api/v1/respondent-pools/{id} |
Elimina un grupo |
POST |
/api/v1/respondent-pools/{id}/respondents |
Añade encuestados al grupo |
DELETE |
/api/v1/respondent-pools/{id}/respondents |
Retira encuestados del grupo |
POST |
/api/v1/respondent-pools/generate |
Selecciona un grupo a partir de una estrategia de muestreo (requested_size es obligatorio); el grupo guarda su ajustes de selección |
POST |
/api/v1/respondent-pools/preview |
Previsualiza una extracción sin crear un grupo |
POST |
/api/v1/respondent-pools/{id}/refresh |
Vuelve a seleccionar un grupo generado a partir de una estrategia, con la ajustes de selección que tiene guardada |
Parámetros de consulta:
project_id: filtra por proyecto
Estrategias de muestreo
Sección titulada «Estrategias de muestreo»Las estrategias de muestreo definen distribuciones demográficas objetivo para crear muestras representativas, y cómo se evalúa el ajuste a ellas. Una estrategia no contiene ninguna configuración de tamaño ni de selección: son datos de entrada de POST /api/v1/respondent-pools/generate y se guardan en el grupo que se crea.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/sampling-strategies |
Lista todas las estrategias |
POST |
/api/v1/sampling-strategies |
Crea una estrategia nueva |
GET |
/api/v1/sampling-strategies/{id} |
Obtiene una estrategia por su ID |
PUT |
/api/v1/sampling-strategies/{id} |
Actualiza una estrategia |
DELETE |
/api/v1/sampling-strategies/{id} |
Elimina una estrategia |
Parámetros de consulta:
project_id: filtra por proyecto
Ejemplo: crear una estrategia de muestreo
curl -X POST https://portor.<tenant>.askalot.io/api/v1/sampling-strategies \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "name": "Representative Sample", "project_id": "550e8400-e29b-41d4-a716-446655440000", "factors": [ { "name": "Gender", "attribute_path": "gender", "target_distribution": {"male": 0.48, "female": 0.50, "other": 0.02} }, { "name": "Age Group", "attribute_path": "age", "factor_type": "bucketed", "target_distribution": {"18-34": 0.35, "35-54": 0.40, "55+": 0.25} } ] }'Ejemplo: extraer un grupo a partir de la estrategia
curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondent-pools/generate \ -H "X-Api-Token: your_token" \ -H "Content-Type: application/json" \ -d '{ "strategy_id": "<strategy id>", "pool_name": "Pilot wave", "requested_size": 100, "oversample_factor": 1.2 }'requested_size es obligatorio; oversample_factor (por defecto 1.0), selection_algorithm (greedy o random_constrained, por defecto greedy), require_email (por defecto false) y exclude_respondent_ids (por defecto ninguno) son opcionales. Extraiga un segundo grupo de la misma estrategia con otro tamaño siempre que lo necesite.
Paquetes
Sección titulada «Paquetes»Un paquete vincula un proyecto → un cuestionario → un subconjunto seleccionado de campañas a una única cadena lineal de conjuntos de datos Bronce → Plata → Oro: la unidad en torno a la cual se organiza el tablero del proceso de Balansor.
| Método | Punto de conexión | Descripción |
|---|---|---|
GET |
/api/v1/bundles |
Lista todos los paquetes |
POST |
/api/v1/bundles |
Crea un paquete nuevo |
GET |
/api/v1/bundles/{id} |
Detalle del paquete, incluidas las recetas de sus etapas (objetivos de calibración de Plata, operaciones de Oro) |
DELETE |
/api/v1/bundles/{id} |
Elimina un paquete (y su cadena de conjuntos de datos) |
POST |
/api/v1/bundles/{id}/clone |
Clona un paquete en profundidad: se copian los conjuntos de datos listos y las recetas de las etapas |
GET |
/api/v1/bundles/{id}/quality |
El resumen de representatividad del paquete (selección, trabajo de campo, ponderación, desviación durante el trabajo de campo, respuesta) |
GET |
/api/v1/bundles/{id}/comparison |
Comparación entre Bronce y Plata (409 conflict hasta que ambas etapas estén en ready) |
GET |
/api/v1/bundles/{id}/coding |
Estado de la codificación de respuestas abiertas: los candidatos a codificación que ofrece el conjunto de datos Bronce, la selección de preguntas del analista y, por pregunta, las dimensiones propuestas con sus categorías y su estado de selección (decidir qué dimensiones se convierten en columnas sigue haciéndose en la interfaz de Balansor) |
PUT |
/api/v1/bundles/{id}/coding/selection |
Define qué unidades de texto abierto codifica este paquete: conjunto completo de claves de unidad que sustituye al anterior (rol de gestor, se requiere un usuario identificado) |
POST |
/api/v1/bundles/{id}/strategy |
Asigna o retira la estrategia de muestreo vigente del paquete (rol de gestor, se requiere un usuario identificado) |
PUT |
/api/v1/bundles/{id}/targets |
Edita los objetivos de calibración del paquete —la especificación de ponderación de Plata—, cada objetivo raked o benchmark (rol de gestor, se requiere un usuario identificado) |
GET |
/api/v1/bundles/{id}/targets/copy-preview?source_bundle_id={source} |
Previsualiza la copia de los objetivos de calibración de otro paquete en este: addable y rejected con los motivos; no escribe nada (rol de gestor) |
Parámetros de consulta:
project_id: filtra por proyecto
Las operaciones de las etapas (extracción, codificación + ponderación, refinamiento, exportación) se realizan mediante las herramientas MCP de paquetes y conjuntos de datos; consulte mcp-bundle-tools.md y mcp-dataset-tools.md para la referencia completa de parámetros de calidad y de etapas.
Formato de las respuestas
Sección titulada «Formato de las respuestas»Respuestas correctas
Sección titulada «Respuestas correctas»Todas las respuestas correctas devuelven JSON con códigos de estado HTTP estándar:
| Estado | Significado |
|---|---|
200 OK |
La solicitud se completó correctamente (también al crear un recurso: el objeto creado se devuelve en el cuerpo) |
204 No Content |
El recurso se eliminó correctamente |
Respuestas de error
Sección titulada «Respuestas de error»Los errores usan un único envoltorio: un código error legible por máquina y un detail legible por personas:
{ "error": "not_found", "detail": "bundle 'abc123' not found"}| Estado | Código error |
Significado |
|---|---|---|
401 |
unauthenticated |
Credenciales ausentes, no válidas o caducadas |
403 |
forbidden |
No tiene la capacidad necesaria o no es propietario del recurso de destino |
404 |
not_found |
El recurso no existe (o no es visible para usted) |
409 |
conflict |
La solicitud es válida, pero el recurso aún no está listo (p. ej., al comparar un paquete cuya cadena aún se está procesando); vuelva a intentarlo cuando termine el proceso |
422 |
validation_error |
Entrada mal formada; detail contiene una lista de problemas por campo |
Especificación OpenAPI
Sección titulada «Especificación OpenAPI»La especificación completa de la API está disponible en formato OpenAPI 3.0:
GET /api/v1/openapi.jsonUse esta especificación para generar clientes de API tipados en el lenguaje de programación que prefiera.
Flujos de trabajo habituales
Sección titulada «Flujos de trabajo habituales»Automatizar la creación de campañas
Sección titulada «Automatizar la creación de campañas»# 1. Create a projectPROJECT_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/projects \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Q1 Survey"}' | jq -r '.id')
# 2. Create a questionnaire (the QML itself is the payload — there is no file to stage)QUESTIONNAIRE_ID=$(curl -s -X POST https://portor.<tenant>.askalot.io/api/v1/questionnaires \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$(jq -n --arg p "$PROJECT_ID" --rawfile c feedback.qml \ '{name: "Customer Feedback", project_id: $p, content: $c}')" | jq -r '.id')
# 3. Create a campaigncurl -X POST https://portor.<tenant>.askalot.io/api/v1/campaigns \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "{\"name\": \"Q1 Campaign\", \"project_id\": \"$PROJECT_ID\", \"questionnaire_id\": \"$QUESTIONNAIRE_ID\", \"offers_ai_channel\": false}"Importar encuestados desde su CRM
Sección titulada «Importar encuestados desde su CRM»# Import respondents from a CSV or your CRM systemfor respondent in "${RESPONDENTS[@]}"; do curl -X POST https://portor.<tenant>.askalot.io/api/v1/respondents \ -H "X-Api-Token: $TOKEN" \ -H "Content-Type: application/json" \ -d "$respondent"done