Ir al contenido
Base de conocimiento

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.

https://portor.<tenant>.askalot.io/api/v1

Sustituya <tenant> por el nombre del inquilino de su organización (p. ej., portor.acme.askalot.io).

Todas las solicitudes a la API requieren autenticación mediante un token de API personal.

Generar un token:

  1. Inicie sesión en https://roundtable.<tenant>.askalot.io
  2. Vaya a Configuración del perfil
  3. Desplácese hasta la sección «Tokens de API»
  4. Haga clic en «Generar nuevo token»
  5. Copie el token (solo se muestra una vez)

Usar el token:

Incluya el token en la cabecera X-Api-Token:

Ventana de terminal
curl -H "X-Api-Token: your_token_here" \
https://portor.<tenant>.askalot.io/api/v1/projects

Propiedades 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 cabecera Authorization: Bearer está 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.

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 401 y debe sustituirse.

Explore la API de forma interactiva con Swagger UI en:

https://portor.<tenant>.askalot.io/api/v1/docs

La 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

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

Ventana de terminal
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": []
}

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 proyecto
  • status: filtra por estado (draft, active, paused, completed)

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 proyecto
  • questionnaire_id: filtra por cuestionario
  • status: filtra por estado
  • expand=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.

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

Ventana de terminal
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 encuestado
  • gender: identidad de género
  • location: ubicación geográfica (texto libre, normalmente "City, Country")
  • external_id: el identificador en su sistema
  • source_system: origen de los datos del encuestado
  • preferred_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.

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 cuestionario
  • campaign_id: filtra por campaña
  • respondent_id: filtra por encuestado
  • status: 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).

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

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

Ventana de terminal
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

Ventana de terminal
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.

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.

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

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

La especificación completa de la API está disponible en formato OpenAPI 3.0:

GET /api/v1/openapi.json

Use esta especificación para generar clientes de API tipados en el lenguaje de programación que prefiera.

Ventana de terminal
# 1. Create a project
PROJECT_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 campaign
curl -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}"
Ventana de terminal
# Import respondents from a CSV or your CRM system
for 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