Primeros pasos

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://api-test.orquest.es/api/v2/businesses/BUSINESSID/services

  • PROD: https://importer.orquest.es/api/v2/businesses/BUSINESSID/services

Las URL indicadas en esta sección corresponden al entorno general de Orquest. Algunos clientes disponen de un entorno propio con un dominio distinto, por lo que será necesario consultar con el equipo de Orquest cuál es el dominio y la base URL correspondientes al negocio.

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, en días, hasta qué punto en el pasado se protege frente al borrado automático la información ya existente en Orquest que no se incluye en la petición.

Enviar lag no implica un filtrado ni rechazo de lo que se envía en el cuerpo de la petición: todos los elementos incluidos explícitamente (contratos, asociaciones a servicio, incidencias, etc.) se crean o actualizan siempre, sin importar sus fechas ni el valor de lag. Este parámetro solo decide qué ocurre con la información que ya existe en el sistema y que la petición no incluye.

  • Lag = 0 (valor por defecto): no existe ninguna protección. Todos los elementos que ya existían en el sistema y no se incluyen en la petición se eliminan, tengan o no fecha de fin. Por tanto, todo se sustituye por lo que se envía en la petición.

  • Lag > 0: cualquier elemento ya finalizado no incluido en la petición se elimina si su vigencia entra dentro del periodo del lag; si su vigencia es anterior, se excluye del borrado y permanece sin cambios en el sistema.

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, incidencias, etc.

  • Ejemplo 1

  • Ejemplo 2

  • Ejemplo 3

Escenario: la petición incluye tanto un contrato antiguo ya cerrado como un nuevo contrato. Ambos se envían explícitamente en 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": "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"
    }
  ]
}

Resultado:

Los dos contratos se crean o actualizan en el sistema con los datos de la petición, ya que ambos están incluidos explícitamente en ella; el valor de lag no influye en este resultado.

Si hubiera otros contratos en el sistema no incluidos en esta petición, cuya fecha de fin fuera anterior a los últimos 10 días, esos contratos se conservarían sin cambios.

Escenario: la petición solo incluye los datos del nuevo contrato; el contrato anterior ya existe en el sistema, pero no se incluye en la petición, y su fecha de fin cae dentro del periodo del lag.

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

Resultado:

El nuevo contrato se crea en el sistema por estar incluido explícitamente en la petición.

El contrato anterior, al no estar incluido, se evalúa para su posible borrado: como su fecha de fin (2024-05-31) cae dentro de los últimos 10 días respecto a la fecha de la petición (2024-06-01), se elimina del sistema.

Escenario: la petición solo incluye los datos del nuevo contrato; existe un contrato anterior en el sistema, no incluido en la petición, cuya fecha de fin queda fuera del 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": "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"
    }
  ]
}

Resultado:

El nuevo contrato se crea en el sistema por estar incluido explícitamente en la petición.

El contrato anterior no se ve afectado: su vigencia (2024-04-30) es anterior al periodo del lag y se conserva sin cambios.

En definitiva, el lag decide qué ocurre con la información previa ya finalizada que deja de enviarse. Con lag = 0 (valor por defecto) no hay ninguna protección: toda la información no incluida se elimina, todo se sustituye por lo que se envía en la petición.

Este parámetro asegura que la información relevante no se pierda al enviar únicamente los datos que van a ser alterados, sin necesidad de incluir en cada petición todo lo ya registrado anteriormente.

Además de este comportamiento, en las limitaciones de empleado, también se validan las fechas de los elementos enviados: si alguna queda fuera del periodo del lag, la petición se rechaza.

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"
    }
  }
]

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.