Registrar valores históricos de contadores

Este endpoint permite registrar una lista de valores históricos de contadores. Cada elemento de la lista representa un valor para un empleado, un contador y un día concretos, y se almacenará en el sistema como dato histórico según el período correspondiente al alcance del contador.

PUT /api/v2/businesses/{businessId}/counter-historical-values

A continuación, se enumeran los campos que conforman el cuerpo de la petición.

Los campos obligatorios están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON 
[
  {
    "day": "string",
    "employeeId": "string",
    "counterShortName": "string",
    "value": 0
  }
]
Detalles

  • day*: día para el que se registra el valor en formato yyyy-MM-dd.

  • employeeId*: identificador externo del empleado para el que se registra el valor.

  • counterShortName*: abreviatura del contador.

  • value: valor que se registra en el contador. Puede ser positivo o negativo.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo de la petición:

PUT /api/v2/businesses/BUSINESSID/counter-historical-values
[
  {
    "day": "2026-01-30",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 120
  }
]

Si todos los datos de la petición son correctos, se almacenará en el sistema el valor histórico del contador asociado al empleado y con la fecha correspondiente.

Aspectos que tener en cuenta

Si el formato de fecha enviado en el campo day no es correcto, la petición devolverá un error 400 Bad Request.

Si el identificador de empleado no se corresponde con ninguno del negocio, la petición devolverá un error 404 Not Found indicando en el mensaje Employee not found.

Si la abreviatura no se corresponde con ningún contador del negocio, la petición devolverá un error 400 Bad Request indicando en el mensaje No counter of type X.

El número máximo de elementos permitidos en esta petición es de 4000.

Si la lista contiene varios elementos inválidos, la API devuelve únicamente el primer error encontrado y no inserta el resto de los elementos.

Un valor histórico puede afectar a varios contadores

En Orquest existen contadores que, aunque tengan distinto nombre, comparten la misma lógica interna (manera de contar) y únicamente se diferencian en el scope (alcance temporal). Por ejemplo, los siguientes contadores:

  • THS: total de horas semanales, scope semanal.

  • THM: total de horas mensuales, scope mensual.

  • THA: total de horas anuales, scope anual.

Cuando se registra un valor histórico en cualquiera de ellos (por ejemplo, en THS), ese valor se considera un histórico válido para el conjunto completo (THS, THM, THA, etc.), siempre que aplique dentro del período calculado en cada caso.

Aunque se registre un valor usando un contador concreto, ese valor histórico puede aplicarse al consultar otros contadores de la misma clase.

Prevalece el valor histórico más reciente

Si hay varios valores históricos dentro del alcance temporal de un contador (scope), Orquest devuelve siempre el más reciente. De este modo, el valor que se muestra en la aplicación web o por API es el que se corresponde con el último valor histórico registrado dentro del período del scope.

Ver ejemplo

Si se registran los siguientes valores para THS (total de horas semanales):

[
  {
    "day": "2026-01-24",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 60
  },
  {
    "day": "2026-01-31",
    "employeeId": "0001",
    "counterShortName": "THS",
    "value": 240
  }
]

El valor del contador THM (total de horas mensuales) será 240, porque Orquest toma el último valor histórico dentro del período del contador, en este caso, el registrado para el último día del mes 2026-01-31.

Dentro de un mismo período, siempre prevalece el valor histórico con la fecha más reciente.

Enlaces de interés

¿Qué es un contador?