Integrações

O que é integração entre sistemas?

A integração entre sistemas é o processo de conectar diferentes sistemas ou aplicações, de modo que eles possam compartilhar informações e trabalhar de maneira coordenada. A integração permite que dados e processos fluam entre os sistemas, eliminando silos de informação e melhorando a eficiência operacional, e possui os seguintes objetivo:

Automatização de processos: reduzir tarefas manuais e repetitivas, permitindo que sistemas troquem informações automaticamente;
Centralização de informações: unificar dados provenientes de diferentes fontes, facilitando a análise e a tomada de decisão;
Melhoria da produtividade: evitar retrabalho e aumentar a velocidade dos processos operacionais;
Aperfeiçoamento da experiência do usuário: fornecer uma visão integrada e consistente de dados em diferentes plataformas.

Como funciona a integração entre sistemas no Hashdata?

A integração entre sistemas permite transferir todas as coletas diretamente dos servidores do HashData para um servidor local (on-premises), um servidor na nuvem ou até mesmo servidores de terceiros.

Há duas opções de integração, via API REST ou com Hashdata Advanced Reports.

API REST

Uma API REST (Application Programming Interface Representational State Transfer) é uma interface de comunicação entre sistemas que segue os princípios do REST (Representational State Transfer), um estilo de arquitetura para projetar serviços de rede. A integração via API REST permite que outros sistemas acessem os dados armazenados no Hashdata. A comunicação entre os sistemas é feita via requisições HTTPS, utilizando um token de autenticação para garantir a segurança das informações.

Hashdata Advanced Reports

A integração com o Hashdata Advanced Reports permite a criação relatórios e painéis avançados atualizados em tempo real, ou seja, os dados inseridos nos formulários são automaticamente exportados para os relatórios e painéis. Tanto os painéis quanto os relatórios são fáceis de criar e não requerem conhecimento especializado. Após a configuração, as integrações e sincronizações são realizadas automaticamente pelo Hashdata em tempo real.

Habilitar integrações

Para habilitar as integrações, selecione o ícone de Integrações no menu principal (lateral esquerda). Depois siga as instruções da página e escolha quais integrações deseja habilitar.

Configuração da integração dos Formulários

Após habilitar as integrações, é necessário informar quais formulários devem ser integrados ao Hashdata Advanced Reports e quais devem ser exportados via API REST.

Selecione o formulário para habilitar a integração desejada: Hashdata Advanced Reports, REST API ou ambas;
Ao clicar em para configurar as integrações;
Defina, para cada elemento que compões o formulário, o nome da questão, que é um nome curto que identifica o elemento no sistema. O nome da questão e é utilizado também nas fórmulas matemáticas e na exportação de dados. Utilize o botão , para o sistema sugerir o nome da questão. Faça ajustes, caso necessário;
Se a integração com o HashData Advanced Reports tiver habilitada, será mostrado o campo Nome do índice no Hashdata Advanced Reports. Este campo é composto por um valor número, que não deve ser alterado, seguido por uma descrição que deve conter apenas letras, números, sublinhados e traços, por exemplo: 21261-formulario-dados-pessoais;

Atenção!

Somente os formulários marcadas para exportação via API REST ficarão acessíveis via API REST. E, da mesma forma, somente os formulários marcados para integração com o Hashdata Advanced Reports ficarão visíveis na ferramenta.

Atenção!

Os rascunhos de formulários também podem ser exportados / integrados, mas é necessário ter em mente que esses formulários podem ter sua estrutura alterada a qualquer momento.

Integração via API REST

A comunicação entre os sistemas é feita via requisições HTTPS, utilizando um token de autenticação para garantir a segurança das informações. Um token de autenticação é uma sequência alfanumérica única, utilizada para autenticar e autorizar um usuário ou aplicação que está acessando uma API REST. Ele funciona como uma "chave digital" que comprova que quem está realizando a requisição tem permissão para fazê-lo.

Após habilitar a integração API REST é necessário selecionar os formulários acessíveis por meio desta integração.

O acesso aos dados é feito por meio dos end-point. As URI's de cada recurso são apresentadas a seguir, mas antes é necessário entender como funciona a autenticação.

Token de autenticação, mostrado ao habilitar a integração via API REST. Clique na imagem para ampliá-la.

Autenticação

Envio do Token de Autenticação: URI vs. Cabeçalho

Na API Hashdata, o token de autenticação pode ser enviado de duas formas para validar e autorizar o acesso a recursos protegidos:

Envio pela URI (Query Parameter)
Envio pelo Cabeçalho HTTP (HD-API-TOKEN) 👈 Opção RECOMENDADA

Cada método tem vantagens e desvantagens, especialmente quando se trata de segurança da informação.

1. Envio do Token pela URI

Exemplo de requisição com o token na query string da URL:

GET /users/export?token=abc123

Vantagens

✅ Facilidade de implementação: é simples incluir o token como um parâmetro na URL, sem necessidade de modificar cabeçalhos da requisição.
✅ Uso em links diretos: pode ser útil quando o cliente precisa compartilhar um link autenticado para um recurso específico.

Desvantagens

❌ Exposição em logs e históricos: como a URL fica visível no navegador, histórico do usuário e logs do servidor, o token pode ser facilmente comprometido.
❌ Facilidade de interceptação: se a requisição não estiver protegida por HTTPS, um atacante pode capturar o token ao monitorar o tráfego de rede.
❌ Risco de cache: algumas configurações de proxy e servidores podem armazenar a URL com o token, permitindo acesso indevido posteriormente.

2. Envio do Token pelo Cabeçalho HTTP (HD-API-TOKEN)

Exemplo de requisição enviando o token no cabeçalho HTTP:

GET /users/export
HD-API-TOKEN: abc123

Vantagens

✅ Maior segurança: o token não é exposto na URL, reduzindo o risco de vazamento em logs, históricos de navegação ou caches.
✅ Melhor controle de acesso: cabeçalhos HTTP são mais fáceis de manipular para políticas de segurança, como restrições de CORS e proteção contra ataques de replay.
✅ Compatível com autenticação JWT e OAuth: esse método é amplamente utilizado para autenticação baseada em tokens, como JWT (JSON Web Token) e OAuth 2.0.

Desvantagens

❌ Maior complexidade na implementação: requer que o cliente configure corretamente o cabeçalho da requisição, o que pode ser mais difícil em algumas aplicações.
❌ Incompatibilidade com alguns serviços: certos navegadores ou clientes HTTP podem ter restrições para modificar cabeçalhos personalizados.

Atenção

Todos exemplos abaixo assumem que o token de autenticação será enviado via HTTP Header: HD-API-TOKEN

FORMULÁRIOS

Para listar os formulários habilitados para integração, utilize o seguinte end-point:

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

Considerando que na conta de exemplo o único formulário configurado para a integração é o "Formulário de Dados Pessoais", ao executar a requisição para o end-point de formulários, obtém-se uma resposta como ao do exemplo a seguir:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Formulário de Dados Pessoais",
    "form_status":"DRAFT"
  }
]

Atributos Exportados

É possível criar atributos personalizados (Atributos exportados) que podem ser usados para selecionar, filtrar ou agrupar os formulários e as coletas.

Por exemplo: Imagine que em uma Organização existam alguns formulários de auditoria entre outras centenas de formulários e que a empresa deseja identificar e exportar apenas os dados de tais formulários sem vincular diretamente ao ID dos formulários. Há várias formas de fazer isso, sendo uma delas criar um "Atributo exportado" chamado "tipo-de-formulario" com o valor "auditoria" em todos os formulários de auditorias. Assim, ao exportar a lista de formulários, pode-se escolher apenas os formulários que tenham o valor "auditoria" na chave/campo "tipo-de-formulario", ex.:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Formulário de Dados Pessoais",
    "form_status":"DRAFT",
    "tipo-de-formulario": "auditoria"
  }
]

RESPOSTAS

Para obter as respostas de um determinado formulário é necessário informar o formId (identificador do formulário):

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

Substitua {formId} pelo identificador do formulário, ex.: 66f172c1dbb522a3729ab9a1

O end-point possui também os seguintes parâmetros opcionais:

from: DateTime - Data/hora inicial usada para filtrar as respostas;
to: DateTime - Data/hora final usada para filtrar as respostas.
removeNewLineFromTexts: boolean - remove quebras de linhas das respostas do tipo texto (é recomendado configurar com 'true');
<nome-do-campo>: texto ou número - filtra pelo "nome-do-campo". Ver Nome do campo em Atributos do Elemento e Filtrar por campos do formulário

Use os parâmetros from e to para paginar a resposta ou para obter os dados progressivamente (conforme inseridos no sistema).

Formatos aceitos

Os parâmetros from e to aceitam qualquer formato de Date do Javascript, por exemplo, data no formato string (ISO 8601): 2024-12-31T23:59:59.999Z (hora UTC). Os milesegundos são opcionais, ex.: 2024-12-31T23:59:59Z

Por exemplo, a URI para acessar as respostas do "Formulário de Dados Pessoais", a partir das 12:00:00 do dia 01/01/2025 no horário oficial brasileiro seria:

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

E, a URI para acessar as respostas enviadas entre o dia 01/01/2025 e 02/01/2025 no horário oficial brasileiro seria:

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

Exemplo de resposta da chamada HTTP (body)

[
    {
        "col_id": "6705960061539e305ab18576",
        "form_id": "66f172c1dbb522a3729ab9a1",
        "user_id": "64282604d86b5ebe18373ab2",
        "collection_date": "2024-01-01T20:25:19.592Z",
        "collection_received_date": "2024-01-01T20:30:01.156Z",
        "auditor": "João da Silva",
        "data": "2024-10-09T12:00:00",
        "fabrica": "ABC",
        "peso1": 22,
        "peso2": 23,
        "peso3": 21,
        "peso-medio-calculado": 22,
        "pontos-na-auditoria": 706,
        "resultado-final-auditoria": 95,
        "tipo-de-formulario": "auditoria",
        "nao-conformidades_files": ["6705960061539e734ea934ac", "6705960061539e734ea836ef"]
    },
    { ... },
    { ... },
]

Filtrar por campos do formulário (questões do formulário)

Podemos utilizar as questões dos formulários nos filtros, por exemplo: no caso da resposta/coleta (JSON) exibida acima, podemos filtrar todas as coletas da fábrica cujo identificador é "ABC", ex.:

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

Importante!

É altamente recomendado usar os parâmetros from e to, ou pelo menos o parâmetro from, para limitar o espaço temporal onde as coletas serão procuradas. Assim você terá uma resposta rápida, com baixa latência. Se não especificar nenhum dos parâmetros citados o sistema efetuará uma busca em todas as coletas e isso pode demorar, resultando em uma alta latência.

DOWNLOAD DE IMAGENS E OUTROS ARQUIVOS

Vários tipos de arquivos podem ser anexados às questões dos formulários, tais como fotos, planilhas, documentos, etc. Para buscar qualquer arquivo anexado a uma resposta, utilize o end-point:

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

Na URL acima, substitua os parâmetros {{formId}}, {{responseId}} e {{fileId}} pelos dados obtidos na coleta. No caso da coleta citada acima, usada como exemplo, os valores seriam:

formId: 66f172c1dbb522a3729ab9a1 ➡️ form_id
responseId: 6705960061539e305ab18576 ➡️ col_id
fileId: 6705960061539e734ea934ac ➡️ nao-conformidades_files

COLABORADORES (USUÁRIOS)

Para listar todos os colaboradores de uma determinada área de trabalho, utiliza o seguinte end-point:

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

Por padrão, esse end-point retorna os dados no formato JSON. Ao executar a requisição sem informar parâmetros, obtém-se uma resposta como a do exemplo a seguir:

[
  {
      "user_id":"66ae9f205c7ed7e95d183804",
      "user_nickname":"Pedro",
      "user_full_name":"Pedro Alcântara",
      "user_department":""
  },
  {
      "user_id":"6752ff2b2536410b2897de91",
      "user_nickname":"José",
      "user_full_name":"José da Silva",
      "user_department":""
  }
]

É possível receber os dados dos colaboradores no formato CSV (Comma-Separated Values). Para isso, basta informar mais dois parâmetros: format e separator. Por exemplo:

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

Obtendo-se o seguinte resultado:

user_id;user_nickname;user_full_name;user_department
66ae9f205c7ed7e95d183804;Pedro;Pedro Alcântara;
6752ff2b2536410b2897de91;José;José da Silva;

O que é integração entre sistemas?​

Como funciona a integração entre sistemas no Hashdata?​

Habilitar integrações​

Configuração da integração dos Formulários​

Integração via API REST​

Envio do Token de Autenticação: URI vs. Cabeçalho​

1. Envio do Token pela URI​

Vantagens​

Desvantagens​

2. Envio do Token pelo Cabeçalho HTTP (HD-API-TOKEN)​

Vantagens​

Desvantagens​

FORMULÁRIOS​

Atributos Exportados​

RESPOSTAS​

Exemplo de resposta da chamada HTTP (body)​

Filtrar por campos do formulário (questões do formulário)​

DOWNLOAD DE IMAGENS E OUTROS ARQUIVOS​

COLABORADORES (USUÁRIOS)​

O que é integração entre sistemas?

Como funciona a integração entre sistemas no Hashdata?

Habilitar integrações

Configuração da integração dos Formulários

Integração via API REST

Envio do Token de Autenticação: URI vs. Cabeçalho

1. Envio do Token pela URI

Vantagens

Desvantagens

2. Envio do Token pelo Cabeçalho HTTP (HD-API-TOKEN)

Vantagens

Desvantagens

FORMULÁRIOS

Atributos Exportados

RESPOSTAS

Exemplo de resposta da chamada HTTP (body)

Filtrar por campos do formulário (questões do formulário)

DOWNLOAD DE IMAGENS E OUTROS ARQUIVOS

COLABORADORES (USUÁRIOS)