Guía de usuario

Primeros pasos

Para comenzar a utilizar la API, es necesario disponer de un usuario de integraciones. Se trata de un usuario estándar de Orquest, que puede ser creado desde la aplicación, con el permiso "Acceder a api importador" habilitado.

El usuario de integraciones tendrá control total sobre los datos de Orquest relacionados con los nodos en los que tiene visibilidad. Si el usuario requiere acceso a toda la información del negocio, se puede situar directamente en el nodo raíz de la estructura jerárquica.

Autenticación

Para utilizar los diferentes recursos que ofrece la API, es necesario autenticarse como usuario de integraciones. Actualmente, existen dos vías para hacerlo:

Entornos

Para garantizar que la experiencia con la API de Orquest sea lo más fluida posible, es importante entender los diferentes entornos disponibles. A continuación, se describen los dos entornos principales: test y producción.

  • Entorno de pruebas (TEST). Este entorno está diseñado para realizar pruebas sin afectar a los datos reales. Es ideal para experimentar con la API, validar configuraciones y probar nuevas integraciones.

Orquest (TEST).

API (TEST).

  • Entorno de producción (PROD). Este es el entorno en el que se manejan los datos reales y se realizan las operaciones definitivas.

Orquest (PROD).

API (PROD).

Teniendo en cuenta que las URL son distintas, las peticiones deberán realizarse al endpoint que corresponda según el entorno. Por ejemplo, para consultar los servicios disponibles en un negocio, se puede realizar la petición a las siguientes URL:

  • TEST: https://test.orquest.es/api/api/v1/business/BUSINESSID/services

  • PROD: https://importer.orquest.es/api/v1/business/BUSINESSID/services

Como la URL base del entorno de TEST es https://test.orquest.es/api, se duplica /api al añadir el resto del endpoint.

Generación automática de código

La API está descrita por completo en un fichero OpenAPI. A través de este fichero, los desarrolladores pueden utilizar cualquiera de las herramientas de generación automática de código disponibles.

Openapi-generator es una de las herramientas disponibles para este propósito, pero es recomendable explorar las diferentes opciones para elegir la que mejor se adapte a las necesidades de cada proyecto.

Datos temporales

En la aplicación se muestra la zona horaria configurada para cada servicio, es decir, se utilizan los valores horarios correspondientes a cada región en la que se encuentren los usuarios o servicios involucrados.

Sin embargo, los valores temporales integrados a través de la API se deben introducir en UTC+0, es decir, en el tiempo universal coordinado. Esta medida garantiza la consistencia y la correcta manipulación de fechas y horas en todas las operaciones llevadas a cabo en el sistema.

La inserción se hace de los datos con la hora transformada. Por ejemplo, para enviar los datos de las medidas de un día completo en un servicio con zona horaria UTC+2, es necesario enviar las medidas desde las 22:00 UTC+0 del día de antes, hasta las 22:00 UTC+0 del mismo día.

Para obtener información detallada sobre la zona horaria que afecta a cada país, se puede consultar la documentación oficial de la IANA (Internet Assigned Numbers Authority), que mantiene una base de datos de zonas horarias utilizada ampliamente en sistemas informáticos y aplicaciones para determinar la hora local en diferentes lugares.

Lag

El parámetro lag dentro de las peticiones a la API determina el número de días previos a la fecha actual que se considerará al gestionar información en Orquest.

  • Lag = 0: toda la información de la petición se incluirá en el proceso de integración, sin considerar la fecha, reemplazando cualquier información previa por la especificada en el cuerpo de la petición. Todos los datos del sistema se sobrescriben.

  • Lag > 0: cambia la información de aquellos elementos que se encuentran dentro del periodo del lag. Si hubiera datos anteriores no incorporados en la petición y que no entran en el periodo del lag, esta información permanece inalterada.

A continuación, se detalla el comportamiento de este parámetro en la integración de contratos, siendo igual para las asociaciones a servicio, disponibilidades, etc.

  • Ejemplo 1

  • Ejemplo 2

  • Ejemplo 3

Escenario: la petición incluye información de un contrato antiguo cuya vigencia entra en el periodo del lag e información de un nuevo contrato que comienza el día de la petición.

  • Fecha de la petición: 2024-06-01

  • Contrato anterior: 2021-06-25 a 2024-05-31 (incluido en la petición)

  • Nuevo contrato: 2024-06-01 a 2025-06-01 (incluido en la petición)

  • Lag: 10

{
  "business": "CST",
  "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"
    }
  ]
}

Resultado:

Como el periodo del lag contempla la fecha de vigencia de ambos contratos, los dos se actualizan en el sistema con los datos de la petición.

Si hubiera contratos anteriores en el sistema, cuya vigencia estuviera fuera del periodo del lag, estos permanecen en el sistema.

Escenario: la petición solo incluye los datos del nuevo contrato, pero el periodo del lag abarca la vigencia de un contrato anterior.

  • Fecha de la petición: 2024-06-01

  • Contrato anterior: 2021-06-25 a 2024-05-31 (no incluido en la petición)

  • Nuevo contrato: 2024-06-01 a 2025-06-01 (incluido en la petición)

  • Lag: 10

{
  "business": "CST",
  "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"
    }
  ]
}

Resultado:

Como el periodo del lag contempla la fecha de vigencia de ambos contratos, el nuevo contrato se incluye en el sistema y el contrato anterior desaparece.

Escenario: la petición incluye información de un nuevo contrato que comienza dentro del periodo del lag y existe un contrato anterior con fecha de finalización anterior al periodo del lag.

  • Fecha de la petición: 2024-06-01

  • Contrato anterior: 2021-06-25 a 2024-04-30 (no incluido en la petición)

  • Nuevo contrato: 2024-05-01 a indefinido (incluido en la petición)

  • Lag: 1

{
  "business": "CST",
  "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"
    }
  ]
}

Resultado:

Como el periodo del lag contempla la fecha de vigencia del nuevo contrato, este se añade al sistema y el contrato anterior permanece inalterado.

En definitiva, siempre que se establece un valor mayor que 0, cambia la información de aquellos elementos que se encuentran dentro del periodo del lag.

Este parámetro asegura que la información relevante no se pierda y que se puedan actualizar tanto los datos pasados como los futuros según sea necesario. Además, permite enviar solo aquellos datos que van a ser alterados, sin necesidad de enviar en la petición toda la información ya registrada anteriormente.

Metadatos

La API permite introducir datos adicionales en determinadas entidades que pueden ser posteriormente visualizados en la aplicación. Estos datos se denominan metadatos y deben ser configurados por el equipo de Orquest dentro del negocio, estableciendo la información que se integra y su tipo (booleano, numérico, textual, etc.).

La integración se lleva a cabo a través del campo metadata en las entidades que dispongan de él, formando un objeto JSON con las claves que se hayan indicado previamente. Al tratarse de un campo de tipo colección, el comportamiento de la API en la actualización contempla los siguientes supuestos:

  • Si se envía null: no se altera la información de estos campos.

  • Si no se envía: no se altera la información de estos campos.

  • Si se envía vacío {}: se borra toda la información anterior.

  • Si se envían otros datos: se sobreescribe toda la información, es decir, se insertan los nuevos campos, se eliminan los que no aparezcan y se actualizan los existentes.

A continuación, se muestra un ejemplo:

  • metadata

  • null

  • Ø

  • {}

  • Nuevos datos

En la entidad employee, dentro de person, se han configurado los siguientes metadatos:

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

Si en la actualización se envía null, los metadatos permanecen.

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

Resultado:

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

Si en la actualización no se envía este campo, los metadatos permanecen.

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

Resultado:

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

Si en la actualización se envía un objeto vacío, los datos se eliminan.

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

Resultado:

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

Si en la actualización se envían otros datos, cuyos campos han sido previamente configurados en Orquest, la información se sobreescribe.

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

Resultado:

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

En la actualización de metadatos de asociación a servicio, el comportamiento es distinto:

Si no se envía el campo, se envía a null o vacío {}, los metadatos creados anteriormente desaparecen.

Por tanto, para mantener los metadatos de asociación a servicio en el sistema, hay que incluirlos siempre en la petición.

Identificadores

La API de Orquest permite incluir identificadores externos en muchas de sus entidades. Este es un aspecto crucial para la integración de Orquest con otros sistemas, facilitando la sincronización y evitando duplicaciones.

Tipos de identificadores

En Orquest, existen dos tipos de identificadores: los identificadores externos y los identificadores internos.

  • Identificadores externos: permiten relacionar entidades de Orquest con entidades de otros sistemas. Se recomienda encarecidamente usar identificadores externos para simplificar el proceso de integración y evitar la duplicación de información.

  • Identificadores internos: permiten establecer un identificador único interno que Orquest asigna a cada entidad (orquestId). Este valor es empleado para referencias internas y no debe ser utilizado como clave de integración con sistemas externos. Se trata de un dato de solo lectura que no se puede modificar.

En un sistema externo, por ejemplo, un empleado tiene el identificador 123MD. Al crear o actualizar información relativa a este empleado en Orquest, se puede asignar 123MD como employeeId. El sistema, además, tendrá un identificador interno para este empleado que será de uso exclusivo dentro de Orquest.

Buenas prácticas

Utilizar identificadores externos permite que cada entidad en Orquest se corresponda con una entidad única en el sistema externo, evitando así la creación de registros duplicados. Además, se alinean las entidades de Orquest con las de los sistemas externos a través de identificadores comunes, se facilita el intercambio de datos y se simplifica la integración de procesos, asegurando la integridad y coherencia de los datos.

Es recomendable, asimismo, evitar el uso de datos sensibles como identificadores externos: DNI, número de pasaporte o cualquier otra información que pueda exponer la identidad de una persona o ser utilizada con fines indebidos. Esto ayuda a proteger tanto la privacidad de los individuos como la integridad del sistema.