Integraciones

¿Qué es la integración de sistemas?

La integración de sistemas es el proceso de conectar diferentes sistemas o aplicaciones para que puedan compartir información y trabajar de manera coordinada. La integración permite que los datos y procesos fluyan entre sistemas, eliminando silos de información y mejorando la eficiencia operativa, y tiene los siguientes objetivos:

Automatización de procesos: reduce las tareas manuales y repetitivas, permitiendo que los sistemas intercambien información automáticamente;
Centralización de la información: unificar datos de diferentes fuentes, facilitando el análisis y la toma de decisiones;
Mejora de la productividad: evita retrabajos y aumenta la velocidad de los procesos operativos;
Mejorar la experiencia del usuario: Proporcionar una vista integrada y consistente de los datos en diferentes plataformas.

¿Cómo funciona la integración de sistemas en Hashdata?

La integración del sistema le permite transferir todas las colecciones directamente desde los servidores HashData a un servidor local (en las instalaciones), un servidor en la nube o incluso servidores de terceros.

Hay dos opciones de integración: a través de REST API o con Hashdata Advanced Reports.

API REST

Una API REST (Application Programming Interface Representational State Transfer) es una interfaz de comunicación entre sistemas que sigue los principios de REST (Representational State Transfer), un estilo arquitectónico para Diseño de servicios de red. La integración a través de API REST permite que otros sistemas accedan a los datos almacenados en Hashdata. La comunicación entre sistemas se realiza a través de solicitudes HTTPS, utilizando un token de autenticación para garantizar la seguridad de la información.

Informes avanzados de Hashdata

La integración con Hashdata Advanced Reports permite la creación de informes avanzados y cuadros de mando actualizados en tiempo real, es decir, los datos ingresados en los formularios se exportan automáticamente a los informes y cuadros de mando. Tanto los paneles como los informes son fáciles de crear y no requieren conocimientos especializados. Después de la configuración, las integraciones y las sincronizaciones las realiza Hashdata automáticamente en tiempo real.

Habilitar integraciones

Para habilitar las integraciones, seleccione el ícono Integraciones en el menú principal (lado izquierdo). Luego siga las instrucciones de la página y elija qué integraciones desea habilitar.

Configuración de integración de formularios

Después de habilitar las integraciones, debes informar qué formularios deben integrarse con Hashdata Advanced Reports y cuáles deben exportarse a través de la API REST.

Seleccione el formulario para habilitar la integración deseada: Hashdata Advanced Reports, REST API o ambos;
Al hacer clic en para configurar las integraciones;
Defina, para cada elemento que compone el formulario, el nombre de la pregunta, que es un nombre corto que identifica al elemento en el sistema. El nombre de la pregunta también se utiliza en fórmulas matemáticas y al exportar datos. Utilice el botón para que el sistema sugiera el nombre de la pregunta. Realizar ajustes si es necesario;
Si la integración con Informes avanzados de HashData está habilitada, el campo Nombre de índice se mostrará en Hashdata Informes avanzados. Este campo consta de un valor numérico, que no debe modificarse, seguido de una descripción que debe contener únicamente letras, números, guiones bajos y guiones, por ejemplo: 21261-formulario-dados-pessoais;

¡Atención!

Solo los formularios marcados para exportar a través de la API REST serán accesibles a través de la API REST. Y, de manera similar, solo formularios marcados para la integración con Hashdata Advanced Reports serán visibles en la herramienta.

¡Atención!

Los borradores de formularios también se pueden exportar/incrustar, pero es necesario tener en cuenta que estos formularios pueden tener su estructura modificada en cualquier momento.

Integración mediante API REST

La comunicación entre sistemas se realiza mediante peticiones HTTPS, utilizando un token de autenticación para garantizar la seguridad de la información. Un token de autenticación es una secuencia alfanumérica única que se utiliza para autenticar y autorizar a un usuario o aplicación que accede a una API REST. Funciona como una “llave digital” que acredita que quien realiza la solicitud tiene permiso para hacerlo.

Después de habilitar la integración de la API REST, debe seleccionar los formularios accesibles a través de esta integración.

El acceso a los datos se realiza a través de end-points. A continuación se presentan las URI de cada recurso, pero primero es necesario comprender cómo funciona la autenticación.

Token de autenticación, que se muestra al habilitar la integración a través de la API REST. Haga clic en la imagen para ampliarla.

Autenticación

Envío del token de autenticación: URI vs. encabezado

En la API Hashdata, el token de autenticación se puede enviar de dos maneras para validar y autorizar el acceso a recursos protegidos:

Envío por URI (Parámetro de consulta)
Envío mediante encabezado HTTP (HD-API-TOKEN) 👈 Opción RECOMENDADA

Cada método tiene ventajas y desventajas, especialmente cuando se trata de seguridad de la información.

1. Envío del token a través de URI

Ejemplo de una solicitud con el token en la cadena de consulta de la URL:

GET /usuarios/export?token=abc123

Ventajas

✅ Facilidad de implementación: es sencillo incluir el token como parámetro en la URL, sin necesidad de modificar los encabezados de la solicitud.
✅ Uso en enlaces profundos: Esto puede ser útil cuando el cliente necesita compartir un enlace autenticado a un recurso específico.

Desventajas

❌ Exposición en registros e historial: dado que la URL es visible en el navegador, el historial del usuario y los registros del servidor, el token puede verse fácilmente comprometido.
❌ Facilidad de intercepción: si la solicitud no está protegida por HTTPS, un atacante puede capturar el token monitoreando el tráfico de la red.
❌ Riesgo de caché: Algunas configuraciones de proxy y servidores pueden almacenar la URL con el token, lo que permite un acceso no autorizado más adelante.

2. Envío del token a través del encabezado HTTP (HD-API-TOKEN)

Ejemplo de una solicitud que envía el token en el encabezado HTTP:

GET /usuarios/exportar
HD-API-TOKEN: abc123

Ventajas

✅ Mayor seguridad: el token no queda expuesto en la URL, reduciendo el riesgo de fugas en logs, historiales de navegación o cachés.
✅ Mejor control de acceso: los encabezados HTTP son más fáciles de manipular para políticas de seguridad como restricciones CORS y protección contra ataques de reproducción.
✅ Admite autenticación JWT y OAuth: este método se usa ampliamente para la autenticación basada en tokens, como JWT (JSON Web Token) y OAuth 2.0.

Desventajas

❌ Mayor complejidad en la implementación: requiere que el cliente configure correctamente el encabezado de la solicitud, lo que puede ser más difícil en algunas aplicaciones.
❌ Incompatibilidad con algunos servicios: Ciertos navegadores o clientes HTTP pueden tener restricciones para modificar encabezados personalizados.

:::advertencia Atención Todos los ejemplos a continuación suponen que el token de autenticación se enviará a través del encabezado HTTP: HD-API-TOKEN

FORMULARIOS

Para enumerar los formularios habilitados para la integración, utilice el siguiente punto final:

GET https://api2.hashdata.app/v1/export/forms

Considerando que en la cuenta de ejemplo el único formulario configurado para la integración es el “Formulario de Datos Personales”, al ejecutar la solicitud al punto final de los formularios, se obtiene una respuesta como en el siguiente ejemplo:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Formulario de datos personales",
    "form_status":"BORRADOR"
  }
]

Atributos exportados

Puede crear atributos personalizados (Atributos exportados) que se pueden usar para seleccionar, filtrar o agrupar sus formularios y colecciones.

Por ejemplo: Imaginemos que en una organización existen algunos formularios de auditoría entre cientos de otros formularios y que la empresa desea identificar y exportar únicamente los datos de dichos formularios sin vincular directamente al ID del formulario. Hay varias formas de hacer esto, una de las cuales es crear un "Atributo exportado" llamado "form-type" con el valor "audit" en todos los formularios de auditoría. Por lo tanto, al exportar la lista de formularios, puede elegir solo los formularios que tengan el valor "auditoría" en la clave/campo "tipo de formulario", por ejemplo:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Formulario de datos personales",
    "form_status":"BORRADOR",
    "form-type": "audit"
  }
]

RESPUESTAS

Para obtener las respuestas de un formulario determinado, debes ingresar el formId (identificador del formulario):

GET https://api2.hashdata.app/v1/export/forms/{formId}/respuestas

Reemplace {formId} con el identificador del formulario, p. ej.: 66f172c1dbb522a3729ab9a1

El punto final también tiene los siguientes parámetros opcionales:

from: DateTime - Fecha/hora de inicio utilizada para filtrar las respuestas;
to: DateTime - Fecha/hora de finalización utilizada para filtrar las respuestas.
removeNewLineFromTexts: boolean - elimina los saltos de línea de las respuestas de tipo texto (se recomienda configurarlo como 'verdadero');
<nome-do-campo>: texto o número - filtra por "nombre del campo". Ver Nombre del campo en Atributos del elemento y Filtrar por campos de formulario

Utilice los parámetros from y to para paginar la respuesta o para obtener los datos progresivamente (tal como se ingresan en el sistema).

Formatos aceptados

Por ejemplo, la URI para acceder a las respuestas del “Formulario de Datos Personales”, a partir de las 12:00:00 del 01/01/2025 en horario oficial brasileño sería:

GET https://api2.hashdata.app/v1/export/forms/66f172c1dbb522a3729ab9a1/responses?from=2025-01-01T15:00:00Z

Y, la URI para acceder a las respuestas enviadas entre el 01/01/2025 y el 02/01/2025 en horario oficial brasileño sería:

GET https://api2.hashdata.app/v1/export/forms/66f172c1dbb522a3729ab9a1/responses?from=2025-01-01T03:00:00Z&to=2025-01-02T03:00:00Z

Ejemplo de respuesta de llamada HTTP (cuerpo)

[
    {
        "col_id": "6705960061539e305ab18576",
        "form_id": "66f172c1dbb522a3729ab9a1",
        "usuario_id": "64282604d86b5ebe18373ab2",
        "fecha_de_recolección": "2024-01-01T20:25:19.592Z",
        "fecha_de_recolección_recibida": "2024-01-01T20:30:01.156Z",
        "auditor": "João da Silva",
        "fecha": "2024-10-09T12:00:00",
        "fábrica": "ABC",
        "peso1": 22,
        "peso2": 23,
        "peso3": 21,
        "peso-promedio-calculado": 22,
        "puntos-auditoría": 706,
        "resultado-final-auditoría": 95,
        "tipo-formulario": "auditoría",
        "archivos-de-no-conformidades": ["6705960061539e734ea934ac", "6705960061539e734ea836ef"]
    },
    { ... },
    { ... },
]

Filtrar por campos de formulario (preguntas de formulario)

Podemos utilizar las preguntas de los formularios en los filtros, por ejemplo: en el caso de la respuesta/colección (JSON) mostrada arriba, podemos filtrar todas las colecciones de la fábrica cuyo identificador sea "ABC", por ejemplo:

GET https://api2.hashdata.app/v1/export/forms/66f172c1dbb522a3729ab9a1/responses?from=2025-01-01T15:00:00Z&fabrica=ABC

¡Importante!

Es muy recomendable utilizar los parámetros from y to, o al menos el parámetro from, para limitar el período de tiempo en el que se buscarán las colecciones. De esta manera tendrás una respuesta rápida, con baja latencia. Si no especifica ninguno de los parámetros mencionados, el sistema realizará una búsqueda en todas las colecciones y esto puede tardar un tiempo, lo que genera una alta latencia.

DESCARGAR IMÁGENES Y OTROS ARCHIVOS

Se pueden adjuntar varios tipos de archivos para formular preguntas, como fotos, hojas de cálculo, documentos, etc. Para buscar cualquier archivo adjunto a una respuesta, utilice el punto final:

GET https://api2.hashdata.app/v1/export/forms/{{formId}}/respuestas/{{responseId}}/archivos/{{fileId}}

En la URL anterior, reemplace los parámetros {{formId}}, {{responseId}} y {{fileId}} con los datos obtenidos de la colección. En el caso de la colección mencionada anteriormente, utilizada como ejemplo, los valores serían:

formId: 66f172c1dbb522a3729ab9a1 ➡️ form_id
responseId: 6705960061539e305ab18576 ➡️ col_id
fileId: 6705960061539e734ea934ac ➡️ archivos_de_no-conformidades

COLABORADORES (USUARIOS)

Para enumerar a todos los colaboradores en un espacio de trabajo determinado, utilice el siguiente punto final:

GET https://api2.hashdata.app/v1/export/users

De forma predeterminada, este punto final devuelve datos en formato JSON. Al ejecutar la solicitud sin proporcionar parámetros, obtendrá una respuesta como la del siguiente ejemplo:

[
  {
      "id_usuario": "66ae9f205c7ed7e95d183804",
      "apodo_usuario": "Pedro",
      "nombre_completo_usuario": "Pedro Alcântara",
      "departamento_usuario": ""
  },
  {
      "id_usuario": "6752ff2b2536410b2897de91",
      "apodo_usuario": "José",
      "nombre_completo_usuario": "José da Silva",
      "departamento_usuario": ""
  }
]

Es posible recibir datos de los colaboradores en formato CSV (Valores separados por comas). Para hacer esto, simplemente proporcione dos parámetros más: format y separator. Por ejemplo:

GET https://api2.hashdata.app/v1/export/users?format=csv&separator=;

Obteniendo el siguiente resultado:

id_usuario;apodo_usuario;nombre_completo_usuario;departamento_usuario
66ae9f205c7ed7e95d183804;Pedro;Pedro Alcântara;
6752ff2b2536410b2897de91;José;José da Silva;

¿Qué es la integración de sistemas?​

¿Cómo funciona la integración de sistemas en Hashdata?​

Habilitar integraciones​

Configuración de integración de formularios​

Integración mediante API REST​

Envío del token de autenticación: URI vs. encabezado​

1. Envío del token a través de URI​

Ventajas​

Desventajas​

2. Envío del token a través del encabezado HTTP (HD-API-TOKEN)​

Ventajas​

Desventajas​

FORMULARIOS​

Atributos exportados​

RESPUESTAS​

Ejemplo de respuesta de llamada HTTP (cuerpo)​

Filtrar por campos de formulario (preguntas de formulario)​

DESCARGAR IMÁGENES Y OTROS ARCHIVOS​

COLABORADORES (USUARIOS)​

¿Qué es la integración de sistemas?

¿Cómo funciona la integración de sistemas en Hashdata?

Habilitar integraciones

Configuración de integración de formularios

Integración mediante API REST

Envío del token de autenticación: URI vs. encabezado

1. Envío del token a través de URI

Ventajas

Desventajas

2. Envío del token a través del encabezado HTTP (HD-API-TOKEN)

Ventajas

Desventajas

FORMULARIOS

Atributos exportados

RESPUESTAS

Ejemplo de respuesta de llamada HTTP (cuerpo)

Filtrar por campos de formulario (preguntas de formulario)

DESCARGAR IMÁGENES Y OTROS ARCHIVOS

COLABORADORES (USUARIOS)