Contenido
Este manual es una guía detallada para los desarrolladores que se encarguen de establecer las interfaces para integrar servicios de terceros a KontrolID. Se ofrece esta posibilidad través de APIs. Un API es una especificación formal sobre cómo un módulo de un software se comunica o interactúa con otro.
APIs Disponibles
Según la necesidad que su organización tenga, existen varios servicios API disponibles para conectarse con KontrolID, según su necesidad.
1- API para traer datos de formularios
Si lo que se necesita es automatizar y usar los datos recogidos de los formularios, o sea la información que ve desde el servidor web https://app.kontrolid.com/ -> Análisis, y llevarlo al CRM, ERP o a un servicio de Inteligencia de negocios como PowerBI, o usarlo en Excel, etc.
2- API para subir datos a recursos compartidos
Si lo que se necesita es automatizar el proceso de cargue de archivos csv o multimedia a KontrolID, o sea cargar los archivos generados por otras fuentes y llevarlo directamente a https://app.kontrolid.com/ -> Recursos Compartidos.
3- API para gestión de tareas
Si lo que se necesita es desplegar la información de estatus de tareas o creación de estas, o sea ver la información del servidor web https://app.kontrolid.com/ -> Tareas.
4- API Administrativos – Reportes de uso
Si lo que se necesita es desplegar la información de reportes de uso o sea ver la información del servidor web https://app.kontrolid.com/ -> Formularios-> Reportes locales -> Reporte de uso
5- API para traer lista de proyectos, formularios y usuarios
Este API despliega información relacionada con los proyectos, formularios y usuarios de la Organización. Adicionalmente trae una lista detallada de los usuarios.
6- API para acceder a todos los datos enviados (Submissions)
Este API despliega toda la información relacionada con los formularios (Datos) enviados al servidor de manera agregada la cual le permitirá ver la información del servidor web https://app.kontrolid.com/ -> Análisis –> Monitoreo -> Datos Enviados o cuando quiere revisar la información de un usuario -> Análisis –> Tabla -> Asunto : Actividad del Usuario.
Esta API le permite también llegar a la misma información del punto 1- API de descargar datos.
7- API de ubicaciones de usuarios en última sincronización
Este API despliega la información de las ubicaciones gps de los usuarios reportadas desde la última sincronización con el servidor. Corresponde a la información obtenida por Análisis -> Ubicaciones de Usuarios.
8- API de auditoría de datos capturados y dispositivos
Estas APIs detallan los accesos a datos auditados y otra que despliega la información histórica de tiempos de dispositivos y sincronización de datos de usuarios con el servidor. Adicionalmente muestra las tareas y formularios que debería recibir (ver) un usuario.
9- API de registros de eventos (LOGS)
Este API despliega la información relativa al log de eventos de sesiones de usuarios. Incluye la información consolidada, es decir, el resumen de eventos concolidado.
10- API de contactos
Este API despliega la información relativa a la nueva característica de campañas.
11- API de campañas
Este API despliega la información relativa a la nueva característica de campañas.
12- API para cambiar de una organización a otra
Este API permite moverse de la organización actual a otra.
Requisitos para acceder a las API
Para poder usar las API, la organización debe tener activado este servicio. De lo contrario cuando acceda al mismo, verá el siguiente mensaje:
Para uso de las API, se requiere autenticación con un usuario que tenga privilegio de Gestión de Formularios, Análisis y Tareas (Analyst). Todos los llamados deben hacer uso de la Autenticación Básica por protocolo seguro https.
Esta autenticación debe especificarse dentro del código que haga la petición a cualquiera de los servicios.
¿Qué usuario/contraseña se debe usar?
El mismo usuario/contraseña que usa para acceso a https://app.kontrolid.com/ siempre que el usuario tenga privilegio de Analyst. Si este usuario tiene un Rol asociado, la información que tiene disponible para ver/uso estará conforme al Rol. A través de los roles de usuarios es que se puede filtrar información para sólo ver un determinado campo de preguntas (columnas) o unos determinados registros (filas).
¿Cómo se especifica el usuario/contraseña?
La autenticación en KontrolID es del tipo Básica sobre un canal seguro encriptado https. Cuando se haga la petición, el par usuario:contraseña debe enviarse codificado base64.
Demostración
Para ver el proceso completo puede ingresar desde la aplicación móvil con usuario: api y contraseña: api. Ingrese algunos datos en cualquiera de los dos formularios:
Ingresando a la Aplicación web con estas mismas credenciales.
Podrá ver los datos en Análisis:
La respuesta cuando se hace la petición a través del API para descargar datos se pueden visualizar incluso desde el mismo navegador, estando autenticado o se le pedirá los datos de autenticación:
Con la url: https://api.kontrolid.com/api/v1/data
Obtiene una respuesta JSON con las url especificas por formularios según los proyectos que tenga habilitado el usuario. En este caso la respuesta es:
Pantallazo:
Datos en formato JSON:
[{"id":6866,"id_string":"s98_6866","title":"TestAPI","description":"TestAPI","url":"https://api.kontrolid.com/api/v1/data/s98_6866"},{"id":7253,"id_string":"s98_7253","title":"TestAPI_Repeat","description":"TestAPI_Repeat","url":"https://api.kontrolid.com/api/v1/data/s98_7253","subforms":{"Hijos":"https://api.kontrolid.com/api/v1/data/s98_7253?form=Hijos"}}]
Visor de JSON en navegador
Para una mejor visualización desde el navegador Chrome puede instalar un complemento de Visor de JSON
El JSON se verá así:
Como podrá observar el enlace directo a los datos de cada formulario corresponde a una url compuesta por: https://api.kontrolid.com/api/v1/data/sXX_YYYY donde XX_YYYY corresponde a la identificación única del formulario, misma que podrá consultar desde el editor de formularios -> Información -> ID
El acceso a los datos en los subformularios o dentro de grupos de repetición, se hace a través del nombre de este:
https://api.kontrolid.com/api/v1/data/sXX_YYYY?form=NombreGrupoRepeticion
Un ejemplo de uso de esta api para visualización de esta información por fuera de KontrolID se encuentra disponible para su consulta del código desarrollado en lenguaje Python en este repositorio en Gitlab, y el resultado se puede visualizar en : https://kontrolid.herokuapp.com/receive/ donde podrá ver que se muestran en tiempo real los datos que ingrese desde la aplicación móvil, así:
En este mismo repositorio en Gitlab, podrá ver un ejemplo de cargue de información a KontrolID.
El código se diseñó para cargar un archivo tipo imagen (pero puede ser igualmente un archivo .csv con datos) .
La url para la carga de archivos corresponde a: https://api.kontrolid.com/api/v1/misc/media/upload/media y el resultado se puede ver consultando en KontroliD – Recursos Compartidos:
