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-valuesA 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 |
|---|
Detalles
|
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.
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.
|
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 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. |
Enlaces de interés
¿Qué es un contador?