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. 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 con la misma fecha toDay, 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-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.

Consideraciones

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

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

Los elementos se agrupan por empleado: si uno de los valores de un empleado es inválido, se descarta el lote completo de ese empleado, aunque el resto de valores fueran correctos. El fallo de un empleado no afecta a los demás empleados incluidos en la misma petición.

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 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 los valores históricos 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á.

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?