Getting started

Getting Started

To start using the API, it is necessary to have an integration user. This is a standard Orquest user, which can be created from the application, with the "Access importer API" permission enabled.

The integration user will have full control over the Orquest data related to the nodes they have visibility over. If the user requires access to all business information, they can be placed directly in the root node of the hierarchical structure.

Authentication

To use the different resources offered by the API, it is necessary to authenticate as an integration user. Currently, there are two ways to do this:

API Key.
Authentication Form (Deprecated).

Environments

To ensure the smoothest experience with the Orquest API, it is important to understand the different environments available. Below are the two main environments: test and production.

Test environment (TEST): this environment is designed for testing purposes without affecting real data. It is ideal for experimenting with the API, validating configurations and testing new integrations.

Orquest (TEST)

API (TEST)

Production environment (PROD): this is the environment where real data is managed and final operations are conducted.

Orquest (PROD)

API (PROD)

Since the URLs are different, requests should be made to the appropriate endpoint according to the environment. For example, to query the available services in a business, it is possible to make the request to the following URLs:

TEST: https://api-test.orquest.es/api/v2/businesses/BUSINESSID/services
PROD: https://importer.orquest.es/api/v2/businesses/BUSINESSID/services

The URLs indicated in this section correspond to the general Orquest environment. Some clients have their own environment with a different domain, so it will be necessary to check with the Orquest team what the domain and base URL corresponding to the business are.

Automatic Code Generation

The API is fully described in an OpenAPI file. Through this file, developers can use any of the available automatic code generation tools.

Openapi-generator is one of the tools available for this purpose, but it is advisable to explore the different options to choose the one that best suits the needs of each project.

Temporal data

The application displays the configured time zone for each service, meaning the time values corresponding to each region where the users or services are located.

However, the temporal values integrated through the API must be entered in UTC+0, that is, in Universal Time Coordinated. This measure ensures consistency and the correct handling of dates and times in all operations carried out in the system.

The insertion is done with the time transformed. For example, to send measures for a full day in a service with a UTC+2 time zone, it is necessary to send the data from 22:00 UTC+0 of the previous day to 22:00 UTC+0 of the same day.

For detailed information about the time zone affecting each country, you can refer to the official documentation of the IANA (Internet Assigned Numbers Authority), which maintains a time zone database widely used in computer systems and applications to determine the local time in different locations.

Lag

The lag parameter within API requests determines, in days, how far back in the past the information already existing in Orquest that is not included in the request is protected from automatic deletion.

Sending lag does not imply filtering or rejecting what is sent in the request body: all elements explicitly included (contracts, service associations, incidences, etc.) are always created or updated, regardless of their dates or the value of lag. This parameter only decides what happens to information that already exists in the system and that the request does not include.

Lag = 0 (the default value): there is no protection at all. All elements that already existed in the system and are not included in the request are deleted, whether or not they have an end date. Everything is therefore replaced by what is sent in the request.
Lag > 0: any already-finished element not included in the request is deleted if its validity falls within the lag period; if its validity is earlier than that, it is excluded from deletion and remains unchanged in the system.

Below, the behavior of this parameter in the integration of contracts is detailed, being the same for service associations, availabilities, incidences, etc.

Example 1
Example 2
Example 3

Scenario: the request includes both an old, already-closed contract and a new contract. Both are sent explicitly in the request.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-05-31 (included in the request)
New contract: 2024-06-01 to 2025-06-01 (included in the request)
Lag: 10

{
  "business": "BUSINESSID",
  "lag": 10,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
    {
      "from": "2021-06-25",
      "to": "2024-05-31",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    },
    {
      "from": "2024-06-01",
      "to": "2025-06-01",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

Both contracts are created or updated in the system with the data from the request, since both are explicitly included in it; the value of lag has no bearing on this outcome.

If there were other contracts in the system not included in this request, whose end date was earlier than the last 10 days, those contracts would remain unchanged.

Scenario: the request only includes the new contract data; the previous contract already exists in the system but is not included in the request, and its end date falls within the lag period.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-05-31 (not included in the request)
New contract: 2024-06-01 to 2025-06-01 (included in the request)
Lag: 10

{
  "business": "BUSINESSID",
  "lag": 10,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
     {
      "from": "2024-06-01",
      "to": "2025-06-01",
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

The new contract is created in the system because it is explicitly included in the request.

The previous contract, since it is not included, is evaluated for possible deletion: as its end date (2024-05-31) falls within the last 10 days relative to the request date (2024-06-01), it is deleted from the system.

Scenario: the request only includes the new contract data; there is a previous contract in the system, not included in the request, whose end date falls outside the lag period.

Request date: 2024-06-01
Previous contract: 2021-06-25 to 2024-04-30 (not included in the request)
New contract: 2024-05-01 to indefinite (included in the request)
Lag: 1

{
  "business": "BUSINESSID",
  "lag": 1,
  "partial": false,
  "ignoreWithoutOuterId": false,
  "ignoreServiceAssociations": true,
  "ignoreContracts": false,
  "person": {
    "name": "Evaristo",
    "surname": "Garrido",
    "birthday": "1989-02-03",
    "employeeId": "1006353"
  },
  "contracts": [
     {
      "from": "2024-05-01",
      "to": null,
      "regularMinutes": 2400,
      "weeklyContract": true,
      "additionalMinutes": 1200,
      "regularControlPeriod": "WEEKLY",
      "additionalControlPeriod": "WEEKLY",
      "calendarDaysOff": true,
      "numberOfHolidays": 30,
      "numberOfPublicHolidays": 14,
      "weeklyDaysInvolved": "MONDAY_SUNDAY",
      "costPerHour": 10,
      "personCategory": "001"
    }
  ]
}

Outcome:

The new contract is created in the system because it is explicitly included in the request.

The previous contract is not affected: its validity (2024-04-30) is earlier than the lag period and remains unchanged.

In short, lag decides what happens to previous, already-finished information that is no longer sent. With lag = 0 (the default value) there is no protection at all: all information not included is deleted, and everything is replaced by what is sent in the request.

This parameter ensures that relevant information is not lost by allowing only the data that will be altered to be sent, without needing to include everything already registered in every request.

In addition to this behavior, in employee limitations the dates of the sent elements are also validated: if any of them falls outside the lag period, the request is rejected.

Metadata

The API allows adding additional data to certain entities that can later be viewed in the application. This data is called metadata and must be configured by the Orquest team within the business, establishing the information to be integrated and its type (boolean, numeric, textual, etc.).

The integration is done through the metadata field in the entities that have it, forming a JSON object with the keys that were previously indicated. Since it is a collection-type field, the API’s behavior in the update considers the following scenarios:

If null is sent: the information in these fields is not altered.
If not sent: the information in these fields is not altered.
If sent empty {}: all previous information is deleted.
If other data is sent: all information is overwritten, meaning the new fields are inserted, the ones that do not appear are deleted, and the existing ones are updated.

The following is an example:

metadata
null
Ø
{}
New data

In the employee entity, inside person, the following metadata has been configured:

[
  {
    "name": "John",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If null is sent in the update, metadata remains.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": null
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If this field is not sent in the update, metadata remains.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163"
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "40k",
        "position": "translator"
    }
  }
]

If an empty object is sent in the update, the data is deleted.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {}
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163"
  }
]

If other data is sent in the update, with fields that have been previously configured in Orquest, the information is overwritten.

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "45k",
        "alias": "JS"
    }
  }
]

Outcome:

[
  {
    "name": "Johnny",
    "surname": "Smith",
    "employeeId": "10163",
    "metadata": {
        "salary": "45k",
        "alias": "JS"
    }
  }
]

Identifiers

The Orquest API allows including external identifiers in many of its entities. This is a crucial aspect for integrating Orquest with other systems, facilitating synchronization and avoiding duplication.

Types of identifiers

In Orquest, there are two types of identifiers: external identifiers and internal identifiers.

External identifiers: allow linking Orquest entities with entities from other systems. It is strongly recommended to use external identifiers to simplify the integration process and avoid duplication of information.
Internal identifiers: allow establishing a unique internal identifier that Orquest assigns to each entity (orquestId). This value is used for internal references and should not be used as an integration key with external systems. It is a read-only data that cannot be modified.

In an external system, for example, an employee has the identifier 123MD. When creating or updating information related to this employee in Orquest, 123MD can be assigned as employeeId. The system will also have an internal identifier for this employee that will be used exclusively within Orquest.

Best practices

Using external identifiers allows each entity in Orquest to correspond to a unique entity in the external system, thus preventing the creation of duplicate records. Additionally, it aligns Orquest entities with those in external systems through common identifiers, facilitates data exchange and simplifies process integration, ensuring data integrity and consistency.

It is also recommended to avoid using sensitive data as external identifiers, such as ID numbers, passport numbers, or any other information that could expose a person’s identity or be used improperly. This helps protect both the privacy of individuals and the integrity of the system.