Registrar valores históricos de contadores por periodos

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 período concreto, 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-period-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 
[
    {
        "employeeId": "string",
        "fromDay": "string",
        "toDay": "string",
        "counterShortName": "string",
        "value": 0
    }
]
Detalles

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

  • fromDay*: primer día del intervalo para el que se registra el valor, en formato yyyy-MM-dd.

  • toDay*: último día del intervalo para el que se registra el valor, en formato yyyy-MM-dd.

  • 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-period-values
[
    {
        "employeeId": "0001",
        "fromDay": "2026-02-09",
        "toDay": "2026-02-15",
        "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 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 el formato de fecha enviado en los campos fromDay o toDay no es correcto, la petición devolverá un error 400 Bad Request.

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 realiza la petición con los siguientes valores:

[
    {
        "employeeId": "0002",
        "fromDay": "2026-02-02",
        "toDay": "2026-02-08",
        "counterShortName": "THS",
        "value": 240
    },
    {
        "employeeId": "0002",
        "fromDay": "2026-02-09",
        "toDay": "2026-02-15",
        "counterShortName": "THS",
        "value": 120
    }
]

Orquest registra dos valores históricos por período y, en ambos casos, la fecha que se usa como referencia es toDay:

  • 2026-02-08 → 240

  • 2026-02-15 → 120

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 2 al 8, el valor será 240.

Para la semana del 9 al 15, el valor será 120.

THM (mensual)

En febrero de 2026, existen dos valores históricos, pero el sistema utiliza el más reciente: 120. Si se registran valores con fecha toDay posterior a 2026-02-15 y dentro del scope mensual, el valor de este se actualizará.

THA (anual)

En 2026, también existen varios históricos dentro del año, pero el sistema utiliza el más reciente: 120. Si se registran valores con fecha toDay posterior a 2026-02-15 y dentro del scope anual, el valor de este se actualizará.

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?