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. Si se ha modificado, deberá indicarse en este campo la abreviatura personalizada.

  • value: valor que se registra en el contador. Puede ser positivo, negativo o nulo. Si no se envía o se envía null, cualquier valor registrado previamente para ese día, se elimina.

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.

Consideraciones

Si no se envía valor o se envía nulo ("value": null), cualquier valor registrado previamente con la misma fecha day, se elimina.

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

Cada elemento de la lista se procesa de forma independiente: los elementos válidos se registran aunque otros de la misma petición sean inválidos, y el fallo de uno solo no descarta el resto del lote.

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 próximo al final del alcance del contador

Si hay varios valores históricos dentro del alcance temporal de un contador (scope), Orquest devuelve siempre el valor más cercano al final de dicho alcance.

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

Orquest registra los valores históricos y, como THS, THM y THA comparten la misma manera de contar, estos valores históricos pueden aplicarse a los tres contadores.

THS (semanal)

Para la semana del 24 de enero, el valor será 60.

Para la semana del 31 de enero, el valor será 240.

THM (mensual)

En enero de 2026, existen dos valores históricos, pero el sistema utiliza el más próximo al final del alcance del contador: 240.

THA (anual)

En 2026, también existen dos valores, pero el sistema utiliza el más próximo al final del alcance del contador: 240. Si se registran valores con fecha day posterior a 2026-01-31 y dentro del scope anual, el valor de este contador se actualizará.

En el alcance temporal de un contador, prevalece el valor con la fecha más cercana al final.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

400 Bad Request

-

Alguno de los campos de la petición no tiene el formato esperado. Se recomienda validar el formato de fecha (yyyy-MM-dd) antes de enviar la petición.

Employee not found

El identificador de empleado indicado no existe en el negocio. Se recomienda verificar el identificador a través de Obtener información de un empleado.

No counter of type {counterShortName}

La abreviatura de contador indicada no coincide con ningún contador del negocio. Se recomienda consultar las abreviaturas válidas a través de Obtener contadores activos de un negocio.

Enlaces de interés

¿Qué es un contador?