Obtener contadores por producto
Este endpoint permite consultar los datos de los contadores de un producto en un periodo no superior a 366 días. Para el cálculo, se tendrán en cuenta las asignaciones o los fichajes consolidados, según se haya configurado.
GET /api/v3/businesses/{businessId}/products/{productId}/counters-with-clockguards?outerIds={outerId}&from={yyyy-MM-dd}&to={yyyy-MM-dd}|
Los identificadores que se deben utilizar en la URL ( |
Si los datos incluidos en la petición son correctos, la respuesta contendrá los datos de los contadores indicados en la URL.
Ejemplo de respuesta
GET /api/v3/businesses/BUSINESSID/products/PRODUCTID/counters-with-clockguards?outerIds=HN&from=2026-08-18&to=2026-08-21[
{
"counter": {
"outerId": "HN",
"counterType": {
"id": 1,
"key": "counter.weekly_net_hours",
"shortName": "HNS",
"scope": "WEEK",
"dataType": "TIME"
},
"customName": "Horas netas",
"customShortName": "HN"
},
"counts": [
{
"key": "HNS_HN_20260817_20260823",
"from": "2026-08-17",
"to": "2026-08-23",
"total": [
{
"employeeId": "1006350",
"count": 360.0,
"dailyCount": [
{
"day": "2026-08-19",
"count": 120
},
{
"day": "2026-08-18",
"count": 240
}
]
},
{
"employeeId": "170326",
"count": 0.0,
"dailyCount": []
}
]
}
]
}
]Detalles
-
counter: información del contador.
-
outerId: identificador externo del contador utilizado en la petición.
-
counterType: información del tipo de contador.
-
id: identificador interno del tipo de contador.
-
key: clave del tipo de contador definida a nivel interno.
-
shortName: abreviatura del tipo de contador.
-
scope: ámbito temporal del contador (
WEEK,MONTH,YEAR, etc.). -
dataType: tipo de dato del contador (
TIME,INTEGER, etc.).
-
-
customName: nombre personalizado del contador, presente únicamente si se ha definido una parametrización personalizada.
-
customShortName: abreviatura personalizada del contador, presente únicamente si se ha definido una abreviatura personalizada.
-
-
counts: lista de periodos con los valores del contador.
-
key: clave que identifica el periodo de cálculo.
-
from: fecha de inicio del periodo de cálculo.
-
to: fecha de fin del periodo de cálculo.
-
total: lista de valores por empleado en el periodo.
-
employeeId: identificador externo del empleado.
-
count: valor del contador para el periodo indicado.
-
dailyCount: desglose diario del valor del contador para el empleado. Si no hay valores, aparecerá un array vacío
[].-
day: fecha a la que corresponde el valor.
-
count: valor del contador para ese día.
-
-
-
En el ejemplo, el contador muestra las horas netas semanales trabajadas por cada empleado, expresado en minutos.
Consideraciones
Esta consulta tiene en cuenta asignaciones y fichajes consolidados, pero no los suma. Para cada día del periodo solicitado, el sistema elige una única fuente: el fichaje consolidado o la asignación planificada.
La elección depende, en primer lugar, del parámetro de servicio Calcular contadores con fichajes:
-
Si está desactivado, los contadores se calculan siempre con asignaciones.
-
Si está activado (comportamiento por defecto), los contadores se calculan con fichajes consolidados en función del rango efectivo de fichajes.
El rango efectivo de fichajes es el tramo de fechas en el que el sistema da por buenos los fichajes ya consolidados. El comportamiento es el siguiente:
-
Si el día cae dentro del rango, se usa el fichaje (si no hay fichaje, cuenta
0, aunque haya asignación). -
Si el día cae fuera del rango, se usa la asignación.
|
El rango siempre queda topado a ayer, por lo que el fichaje del día de hoy nunca entra en el rango efectivo, aunque sea el último registrado: ese día queda fuera y se calcula por asignación. |
Para establecer el rango, se utiliza el parámetro de negocio Contar todos los fichajes, que determina cuándo se empiezan a contar los fichajes:
-
Desactivado (por defecto): el rango llega hasta el domingo de la semana anterior a la del último fichaje registrado, topado a ayer. La semana del último fichaje queda fuera, por si aún no está consolidada del todo.
-
Activado: el rango llega hasta la fecha del último fichaje registrado, topado a ayer. Se cuentan los fichajes de la semana en curso.
|
El límite del rango se calcula siempre a partir de la fecha del último fichaje registrado, no de la fecha actual: registrar un fichaje más reciente desplaza ese límite, aunque la semana del último fichaje seguirá excluida con la configuración por defecto. |
La respuesta dependerá de la configuración del contador, como el ámbito (semanal, mensual, anual, etc.) o el tipo de dato (minutos, cantidad de días, etc.).
Se puede consultar la información de varios contadores en la misma petición incluyendo los diferentes identificadores en la URL, separados por comas: ?outerIds=id1,id2,….
Si no hay datos que repercutan en el contador para el periodo indicado en la URL, indicará "count": 0.0.
Los empleados que no tengan configurado un identificador externo en el sistema (employeeId) aparecerán en la respuesta sin este campo.
Códigos de error
Además de los errores comunes, este endpoint puede devolver los siguientes códigos:
| Código | Mensaje | Descripción |
|---|---|---|
|
BusinessCounter with outerId not found |
Alguno de los |
|
The request exceded the maximum number of days allowed (366 days max) |
El periodo solicitado entre |