Integrations

What is system integration?

System integration is the process of connecting different systems or applications so that they can share information and work in a coordinated manner. Integration allows data and processes to flow between systems, eliminating information silos and improving operational efficiency, and has the following objectives:

Process automation: reduce manual and repetitive tasks, allowing systems to exchange information automatically;
Centralization of information: unify data from different sources, facilitating analysis and decision-making;
Improved productivity: avoid rework and increase the speed of operational processes;
Improving user experience: Provide an integrated and consistent view of data across different platforms.

How does system integration work in Hashdata?

Integration between systems allows you to transfer all collections directly from the HashData servers to a local server (on-premises), a cloud server or even third-party servers.

There are two integration options, via REST API or with Hashdata Advanced Reports.

REST API

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. Integration via REST API allows other systems to access data stored in Hashdata. Communication between systems is done via HTTPS requests, using an authentication token to ensure information security.

Hashdata Advanced Reports

Integration with Hashdata Advanced Reports allows the creation of advanced reports and dashboards updated in real time, that is, the data entered in the forms is automatically exported to the reports and dashboards. Both dashboards and reports are easy to create and do not require specialized knowledge. After configuration, integrations and synchronizations are performed automatically by Hashdata in real time.

Enable Integrations

To enable integrations, select the Integrations icon in the main menu (left side). Then follow the instructions on the page and choose which integrations you want to enable.

Forms Integration Setup

After enabling the integrations, you must inform which forms should be integrated with Hashdata Advanced Reports and which should be exported via the REST API.

Select the form to enable the desired integration: Hashdata Advanced Reports, REST API or both;
By clicking to configure integrations;
Define, for each element that makes up the form, the question name, which is a short name that identifies the element in the system. The question name is also used in mathematical formulas and when exporting data. Use the button for the system to suggest the question name. Make adjustments if necessary;
If integration with HashData Advanced Reports is enabled, the Index Name field will be displayed in Hashdata Advanced Reports. This field consists of a number value, which should not be changed, followed by a description that must contain only letters, numbers, underscores and dashes, for example: 21261-formulario-dados-pessoais;

Attention!

Only forms marked for export via REST API will be accessible via REST API. And, similarly, only forms marked for integration with Hashdata Advanced Reports will be visible in the tool.

Attention!

Draft forms can also be exported/embedded, but it is necessary to keep in mind that these forms can have their structure changed at any time.

Integration via REST API

Communication between systems is done via HTTPS requests, using an authentication token to guarantee information security. An authentication token is a unique alphanumeric sequence used to authenticate and authorize a user or application accessing a REST API. It works like a "digital key" that proves that whoever is making the request has permission to do so.

After enabling the REST API integration, you must select the forms accessible through this integration.

Access to data is done through end-points. The URIs for each resource are presented below, but first it is necessary to understand how authentication works.

Authentication token, shown when enabling integration via REST API. Click on the image to enlarge it.

Authentication

Sending the Authentication Token: URI vs. Header

In the Hashdata API, the authentication token can be sent in two ways to validate and authorize access to protected resources:

Sending by URI (Query Parameter)
Sending via HTTP Header (HD-API-TOKEN) 👈 RECOMMENDED option

Each method has advantages and disadvantages, especially when it comes to information security.

1. Sending the Token via URI

Example of a request with the token in the query string of the URL:

GET /users/export?token=abc123

Advantages

✅ Ease of implementation: it is simple to include the token as a parameter in the URL, without the need to modify request headers.
✅ Use in deep links: This can be useful when the client needs to share an authenticated link to a specific resource.

Disadvantages

❌ Exposure in logs and history: Since the URL is visible in the browser, user history, and server logs, the token can be easily compromised.
❌ Ease of interception: If the request is not protected by HTTPS, an attacker can capture the token by monitoring network traffic.
❌ Cache risk: Some proxy configurations and servers may store the URL with the token, allowing unauthorized access later.

2. Sending the Token via HTTP Header (HD-API-TOKEN)

Example of a request sending the token in the HTTP header:

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

Advantages

✅ Greater security: the token is not exposed in the URL, reducing the risk of leaks in logs, browsing histories or caches.
✅ Better access control: HTTP headers are easier to manipulate for security policies like CORS restrictions and protection against replay attacks.
✅ Supports JWT and OAuth authentication: This method is widely used for token-based authentication such as JWT (JSON Web Token) and OAuth 2.0.

Disadvantages

❌ Greater complexity in implementation: requires the client to correctly configure the request header, which can be more difficult in some applications.
❌ Incompatibility with some services: Certain browsers or HTTP clients may have restrictions on modifying custom headers.

Attention

All examples below assume that the authentication token will be sent via HTTP Header: HD-API-TOKEN

FORMS

To list the forms enabled for integration, use the following end-point:

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

Considering that in the example account the only form configured for integration is the "Personal Data Form", when executing the request to the forms end-point, a response is obtained as in the following example:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Personal Data Form",
    "form_status":"DRAFT"
  }
]

Exported Attributes

You can create custom attributes (Exported Attributes) that can be used to select, filter, or group your forms and collections.

For example: Imagine that in an Organization there are some audit forms among hundreds of other forms and that the company wants to identify and export only the data from such forms without linking directly to the form ID. There are several ways to do this, one of which is to create an "Exported Attribute" called "form-type" with the value "audit" in all audit forms. Therefore, when exporting the list of forms, you can choose only the forms that have the value "audit" in the "form-type" key/field, e.g.:

[
  {
    "form_id":"66f172c1dbb522a3729ab9a1",
    "form_name":"Personal Data Form",
    "form_status":"DRAFT",
    "form-type": "audit"
  }
]

ANSWERS

To obtain the responses from a given form, you must enter the formId (form identifier):

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

Replace {formId} with the form identifier, e.g.: 66f172c1dbb522a3729ab9a1

The end-point also has the following optional parameters:

from: DateTime - Starting date/time used to filter responses;
to: DateTime - End date/time used to filter responses.
removeNewLineFromTexts: boolean - removes line breaks from text-type responses (recommended to set to 'true');
<nome-do-campo>: text or number - filters by "field-name". View Field name in Element Attributes and Filter by form fields

Use the from and to parameters to paginate the response or to get the data progressively (as entered into the system).

Accepted formats

For example, the URI to access the responses from the "Personal Data Form", starting at 12:00:00 on 01/01/2025 in Brazilian official time would be:

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

And, the URI to access the responses sent between 01/01/2025 and 02/01/2025 in Brazilian official time would be:

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

Example HTTP call response (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",
        "date": "2024-10-09T12:00:00",
        "factory": "ABC",
        "weight1": 22,
        "weight2": 23,
        "weight3": 21,
        "calculated-average-weight": 22,
        "audit-points": 706,
        "audit-final-result": 95,
        "form-type": "audit",
        "nonconformities_files": ["6705960061539e734ea934ac", "6705960061539e734ea836ef"]
    },
    { ... },
    { ... },
]

Filter by form fields (form questions)

We can use the questions from the forms in the filters, for example: in the case of the response/collection (JSON) shown above, we can filter all collections from the factory whose identifier is "ABC", e.g.:

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

Important!

It is highly recommended to use the from and to parameters, or at least the from parameter, to limit the time frame where collections will be searched. This way you will have a fast response, with low latency. If you do not specify any of the mentioned parameters, the system will search all collections and this may take a while, resulting in high latency.

DOWNLOAD IMAGES AND OTHER FILES

Various types of files can be attached to form questions, such as photos, spreadsheets, documents, etc. To search for any file attached to a response, use the end-point:

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

In the above URL, replace the parameters {{formId}}, {{responseId}}, and {{fileId}} with the data obtained from the collection. In the case of the collection mentioned above, used as an example, the values would be:

formId: 66f172c1dbb522a3729ab9a1 ➡️ form_id
responseId: 6705960061539e305ab18576 ➡️ col_id
fileId: 6705960061539e734ea934ac ➡️ non-conformities_files

CONTRIBUTORS (USERS)

To list all collaborators in a given workspace, use the following endpoint:

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

By default, this end-point returns data in JSON format. When executing the request without providing parameters, you get a response like the one in the following example:

[
  {
      "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":""
  }
]

It is possible to receive employee data in CSV (Comma-Separated Values) format. To do this, simply provide two more parameters: format and separator. For example:

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

Obtaining the following result:

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

What is system integration?​

How does system integration work in Hashdata?​

Enable Integrations​

Forms Integration Setup​

Integration via REST API​

Sending the Authentication Token: URI vs. Header​

1. Sending the Token via URI​

Advantages​

Disadvantages​

2. Sending the Token via HTTP Header (HD-API-TOKEN)​

Advantages​

Disadvantages​

FORMS​

Exported Attributes​

ANSWERS​

Example HTTP call response (body)​

Filter by form fields (form questions)​

DOWNLOAD IMAGES AND OTHER FILES​

CONTRIBUTORS (USERS)​

What is system integration?

How does system integration work in Hashdata?

Enable Integrations

Forms Integration Setup

Integration via REST API

Sending the Authentication Token: URI vs. Header

1. Sending the Token via URI

Advantages

Disadvantages

2. Sending the Token via HTTP Header (HD-API-TOKEN)

Advantages

Disadvantages

FORMS

Exported Attributes

ANSWERS

Example HTTP call response (body)

Filter by form fields (form questions)

DOWNLOAD IMAGES AND OTHER FILES

CONTRIBUTORS (USERS)