API - Español

Soporte Técnico Innoscout: registrando respuestas con una API (interfaz de programación de aplicaciones).

Activación y Clave de la API

Para activar la API para su cuenta, diríjase a la configuración de su cuenta, y haga clic en el botón “Activar API”.

Puede regenerar la clave API en cualquier momento, pero todas las solicitudes futuras deben incluir la nueva clave (la clave anterior será rechazada).

También puede desactivar la API de su cuenta en cualquier momento.

URL Base de la API

El URL base para todas las solicitudes de la API es

https://www.innoscout.com/api/v1/<organisation-id>/

Reemplace la con la ID de Organización de la página de configuración de su cuenta.

Autenticación

Envíe un token HTTP de tipo portador (bearer) con su Clave API con cada solicitud.

Authorization: Bearer <api-key>

Reemplace con la clave API de la página de configuración de su cuenta.

Respuestas

Todas las respuestas exitosas siguen el mismo formato base:

{
   data: [...],
   errors: null
}

Una respuesta de error puede contener algunos datos, pro contendrá un objeto de error:

GET <api-base-url>/questionnaires
Result:
{
   data: {}, // (opcional)
   errors: []
}

GET Cuestionarios

GET <api-base-url>/questionnaires
Result:
{
    "data": [
        {
            "id": guid-string,
            "slug": string,
            "name": string,
            "description": string
        },
        ...
    ],
    "errors": null
}

GET Cuestionarios y Preguntas

GET <api-base-url>/questionnaires/<questionnaire-id>
Result:
{
    "data": {
        "id": guid-string,
        "slug": string,
        "name": string,
        "description": string,
        "questions": [
            // Para todos los tipos de preguntas
            {
                "id": guid-string , // la id a referenciar cuando se envíe una respuesta
                "index": number in the questionnaire,
                "required": boolean,
                "title": string,
                "subtitle": string,
                "type": string, see https://help.innoscout.com/article/10-question-types
            }
            // Para preguntas numéricas
            {
                ... otras propiedades como las anteriores,
                "configuration": {
                    "decimalpoints": "2",
                    "minimum": "4",
                    "maximum": "8"
                },
            },
            // Para las preguntas de selección y selección múltiple
            {
                ... otras propiedades como las anteriores,
                "configuration": {
                    // Se permiten valores como cadenas de texto (strings) separadas por \n
                    "items": "Selection1\nSelection2\nSelection3",
                    // ¿Se permiten otros valores?
                    "allowother": boolean
                },
            },
        ]
    },
    "errors": null
}

POST Respuestas

Puede sencillamente “validar” las respuestas o “validar y enviar” respuestas con la propiedad “submit”.

POST <api-base-url>/questionnaires/<questionnaire-id>/submissions
Payload:
{
    "name": "", // Nombre de la Empresa o Entidad – Algo que identifique quién envió la respuesta
    "email": "", // Dirección de correo electrónico de la respuesta
    "submit": false, // verdadero para validar y enviar / falso para únicamente validar
    "answers": [
        // para cada respuesta, añadir estas propiedades comunes
        {
            "question-id": "30efcc0c-4751-47ce-7b55-08da00e0bd17",
        },
        // para preguntas tipo texto (corto y largo) y enlace
        {
            // ... propiedades comunes,
            "text": "API import 1"
        },
        // para preguntas numéricas, separe el número antes de la parte decimal (número) y despues de la parte decimal (decimales). Los decimales pueden ser opcionales.
        {
            // ... propiedades comunes,
            "number": "4",
            "decimals": "9"
        },
        // para preguntas de selección única
        // Si se permiten otros valores en la configuración de la pregunta, usted puede asignar un valor diferente. De otro modo solo aquellos que se encuentren en la propiedad “ítems” de “question” (véase más arriba).
        {
            // ... propiedades comunes,
            "selection": "Selection3"
        },
        // para preguntas de selección múltiple
        // Si se permiten otros valores en la configuración de la pregunta, usted puede asignar un valor diferente. De otro modo solo aquellos que se encuentren en la propiedad “ítems” de “question” (véase más arriba).
        {
            // ... propiedades comunes,
            "selections": [
                "Selection1",
                "Selection2",
                "OtherValue"
            ]
        },
        // para la pregunta tipo fecha, configura “datetime” en el formato “aaaa-MM-dd”. Actualmente no se acepta la hora.
        {
            // ... propiedades comunes,
            "datetime": "2022-12-31"
        }
    ]
}

Result:
{
    "data": {
        "id": guid-string, //
        "entityID": guid-string, // id único de la entidad, no usado actualmente.
        "entityName": string, // nombre de la empresa
        "email": string, // dirección de correo
        "submitted": true, // siempre verdadero si se retorna algún dato
        "items": [
            // Estas propiedades en común para todos los tipos de pregunta
            {
                "id": guid-string,
                "question-id": "30efcc0c-4751-47ce-7b55-08da00e0bd17"
            },
            // Para texto (corto y largo) y enlace
            {
                // ... propiedades comunes
	        "answer": {
                    "text": "https://example.com"
                },
            },
            // Para preguntas numéricas
            {
                // ... propiedades comunes
                "answer": {
                    "number": "4",
                    "decimals": "9"
                },
            },
            // Para preguntas de selección simple
            {
                // ... propiedades comunes
                "answer": {
                    "selection": "Selection3",
                    "other": null
                },
            },
            // Para preguntas de selección múltiple
            {
                // ... propiedades comunes
                "answer": {
                    "selections": [
                        "Selection1",
                        "Selection2",
                        "OtherValue"
                    ]
                },
            },
            // Para preguntas de fecha
            {
                // ... propiedades comunes
                "answer": {
                    "datetime": "2022-12-31"
                },
            }
        ]
    },
    "errors": [
       "0": "Error 1",
       "1": "Error 2"
    ]
}

Tipos de Pregunta

Innoscout permite varios tipos de pregunta. Hay tipos genéricos de preguntas y tipos específicos, que están basados en los tipos genéricos, pero con configuraciones predeterminadas. La siguiente tabla muestra a qué tipo genérico de preguntas está relacionado un tipo específico. En la documentación API, solamente se diferencian los tipos genéricos.