Casos de uso

Filtrar por fecha

Cómo acotar un rango, cómo pedir un solo día, y sobre qué fecha filtra cada reporte.

Los reportes se acotan con from_date y to_date, en formato YYYY-MM-DD. Las dos son inclusivas y las dos son independientes: podés mandar una, la otra, o las dos. De esa combinación salen los cuatro casos que necesitás.

Las cuatro formas de pedir un rango

Lo que querésQué mandás
Desde una fecha en adelantefrom_date=2026-01-01
Hasta una fechato_date=2026-03-31
Un rango cerradofrom_date=2026-01-01&to_date=2026-03-31
Un solo díafrom_date=2026-01-15&to_date=2026-01-15

Para un solo día tenés que mandar las dos con la misma fecha. Mandar solo from_date no es “ese día”: es todo desde ese día en adelante, sin techo. Es la confusión más común con estos filtros.

Las inscripciones de un día puntual:

$curl "https://www.crehana.com/api/v5/rest/org/acme/reports/learning/general/?from_date=2026-01-15&to_date=2026-01-15" \
>  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS"

Todas las inscripciones desde el arranque del año:

$curl "https://www.crehana.com/api/v5/rest/org/acme/reports/learning/general/?from_date=2026-01-01" \
>  -H "Api-Key: $API_KEY" -H "Secret-Access: $SECRET_ACCESS"

to_date incluye el día completo

to_date=2026-01-15 no corta en la medianoche de ese día: entra todo el 15, hasta el último minuto. No hace falta pedir el 16 para “cerrar” el 15.

Sobre qué fecha filtra cada reporte

El rango no siempre se aplica sobre lo mismo. Cada reporte lo aplica sobre la fecha que ese mismo reporte devuelve, y en la zona en la que la devuelve:

ReporteFiltra sobreZonaRango
reports/learning/quizzesfecha del último intento de evaluaciónUTCopcional
reports/learning/generalfecha de inscripción al cursozona de la organizaciónopcional
reports/learning/general-v2fecha de inscripción al cursozona de la organizaciónopcional
reports/learning/performancefecha de inscripción al cursozona de la organizaciónopcional
reports/attendance/shiftsfecha de creación del turno—opcional
reports/attendance/shifts-scheduleinicio de la asignación—opcional
reports/attendance/marksfecha de la marcazona del lugar donde se marcóobligatorio, máx. 31 días
reports/attendance/daily-managementfecha de la jornadazona del lugar de la marcaobligatorio, máx. 31 días

La zona importa en los bordes del rango. Una inscripción de las 21:00 hora de Lima es del día siguiente en UTC: si el reporte la muestra como el día 15 y el filtro comparara en UTC, pedir el 15 no la traería. Por eso cada reporte filtra en la misma zona en la que muestra la fecha — así lo que pedís y lo que ves coinciden.

El reporte general v2 aceptaba un course_enroll_date que ya no figura en la referencia. Su equivalente es from_date sin to_date, con una diferencia: from_date compara en la zona de la organización y el parámetro viejo comparaba en UTC, así que en el borde del día los resultados pueden no ser idénticos.

Los reportes de asistencia exigen el rango

En attendance/marks y attendance/daily-management el rango es obligatorio y no puede pasar de 31 días. No es una restricción arbitraria: esas dos tablas crecen con colaboradores × días, y en una organización grande una consulta sin acotar recorre millones de filas.

La ventana es inclusiva, así que del 1 al 31 de agosto son 31 días y entra; del 1 de agosto al 1 de septiembre son 32 y no.

Si falta un extremo:

1{
2  "errors": [
3    {
4      "loc": ["query", "to_date"],
5      "msg": "This field is required for this report",
6      "type": "value_error.missing"
7    }
8  ]
9}

Si la ventana es demasiado ancha:

1{
2  "errors": [
3    {
4      "loc": ["query", "to_date"],
5      "msg": "The maximum date window is 31 days",
6      "type": "value_error.date_range"
7    }
8  ]
9}

Para bajar un histórico más largo, partilo en tramos de hasta 31 días y concatená los resultados.

Cuándo responde 400

Los dos casos de error se validan antes de tocar los datos, así que recibís un 400 y no un 200 con una lista vacía que parezca “no hay nada”:

Situaciónmsg
Formato distinto de YYYY-MM-DDInvalid date, expected format YYYY-MM-DD
from_date posterior a to_datefrom_date must be earlier than or equal to to_date

La forma completa de las respuestas de error está en Errores.

Recomendaciones

  • Mandá el rango siempre que puedas. Un reporte sin acotar devuelve el histórico completo de la organización y se pagina mucho peor — ver Paginación.
  • Para sincronizar a diario, pedí el día anterior con las dos fechas iguales. Es el caso de “los movimientos de ayer” y es una sola llamada.
  • Si comparás contra el panel, tené en cuenta la zona: los reportes de learning se filtran en la zona de la organización, y los de evaluaciones en UTC.