Manejo de fechas y horas en la API de exportación de datos

El modelo de fecha y hora

Hay tres reglas que describen cómo gestiona la API las fechas y las horas:

1. Todas las solicitudes dirigidas a /jobs, /printer-states y /printer-interventions deben incluir un parámetro timezone que contenga un identificador de zona horaria válido de la IANA, por ejemplo, America/Denver o Europe/Bucharest.
2. Cualquier valor de startDateTime o endDateTime que se facilite en la solicitud se interpreta como hora local en la zona horaria indicada. Los valores no incluyen el desplazamiento horario con respecto al UTC.
3. Todos los valores de fecha y hora de la respuesta se formatean como hora local en la misma zona horaria, siguiendo el formato YYYY-MM-DDTHH:MM:SS.sss.

El parámetro timezone determina el significado de la solicitud y el formato de la respuesta. Dos solicitudes de los mismos datos subyacentes, enviadas con zonas horarias diferentes, generan respuestas con cadenas de fecha y hora distintas, aunque describan los mismos acontecimientos.

Formato de fecha y hora

La API utiliza un único formato para todos los valores de fecha y hora, tanto en las solicitudes como en las respuestas:

YYYY-MM-DDTHH:MM:SS.sss

Por ejemplo, 2026-03-15T14:30:00.000 corresponde a las 14:30:00 horas del 15 de marzo de 2026, según la zona horaria indicada en la solicitud.

En las solicitudes, la parte correspondiente a los milisegundos (.sss) es opcional. En las respuestas, siempre está presente.

Intervalo de tiempo predeterminado

Puede omitir startDateTime, endDateTime o ambos. Los dos valores predeterminados se aplican de forma independiente:

• Si omite startDateTime, la API utiliza las 24 horas anteriores a la hora actual como inicio del intervalo.
• Si omite endDateTime, la API utiliza la hora actual como fecha de finalización del intervalo.

Los valores predeterminados se combinan tal y como cabría esperar:

• Si omite ambos valores, la API devuelve los datos de las últimas 24 horas.
• Si introduce startDateTime como «hace una hora» y omite endDateTime, la API devuelve los datos correspondientes a la hora anterior.
• Si se especifica endDateTime y se omite startDateTime, la API devuelve los datos correspondientes al intervalo que comienza 24 horas antes de la solicitud y finaliza en el momento indicado por endDateTime.

Los valores por defecto se calculan en la zona horaria indicada en la solicitud.

Conservación de datos: los últimos siete días

La API de exportación de datos proporciona datos operativos en tiempo real. Los registros de trabajos, el historial de estado de la impresora y los eventos de intervención solo están disponibles para los últimos siete días. Una solicitud de datos con más de siete días de antigüedad devuelve un error.

Planifique su integración de tal forma que las extracciones programadas se ejecuten con la frecuencia suficiente para recopilar todos los datos antes de que caduquen:

• Para los extractos nocturnos, prevea un margen de al menos uno o dos días. Si una ejecución programada falla, dispone de tiempo para investigar el problema y volver a ejecutarla antes de que los datos dejen de estar disponibles.
• En el caso de las actualizaciones retrospectivas o las extracciones puntuales, no solicite datos con más de siete días de antigüedad.

Reglas aplicables al intervalo solicitado

• startDateTime debe ser anterior a endDateTime. Una solicitud que incumpla esta regla generará el error ERR_INVALID_DATE_RANGE.
• Ambos valores deben seguir el formato descrito en Formato de fecha y hora. Una solicitud con un valor mal formado da lugar a un error con el código ERR_INVALID_DATE_FORMAT.
• El intervalo de tiempo entre startDateTime y endDateTime no debe superar el intervalo máximo permitido. Una solicitud que supere el límite máximo se rechazará con el error ERR_DATE_RANGE_EXCEEDED.

Indicar la zona horaria

El parámetro timezoneadmite identificadores de zonas horarias de la IANA, como America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo o UTC. En la página de documentación interactiva se muestra una lista de todos los valores que admite la API.

Un identificador no válido o no reconocido da lugar a un error ERR_INVALID_TIMEZONE. Las abreviaturas de tres letras, como MST o EST, no son identificadores de la IANA y no se aceptan; utilice en su lugar el identificador correspondiente basado en la región (por ejemplo, America/Denver o America/New_York).

Proporcionar el idioma

El parámetro timezone no es el único que controla el formato que la API da a una respuesta. El punto final /printer-interventions endpoint also accepts an optional language que determina el idioma del campo description en la respuesta.

Los valores admitidos son en (inglés), de (alemán), ja (japonés), it (italiano), fr (francés) y es (español). Si se introduce un valor que no figura en esta lista, se producirá un error con el código ERR_INVALID_LANGUAGE.

Hay dos aspectos de este parámetro que conviene tener en cuenta a la hora de planificar:

• Si omite el parámetro, o si no hay ninguna descripción disponible en el idioma que ha solicitado, la descripción se mostrará en inglés. La solicitud se procesa correctamente en ambos casos, por lo que su integración no puede dar por sentado que el idioma de una descripción coincida con el idioma solicitado.
• Este parámetro solo afecta al campo description. El campo interventionCode que lo acompaña es independiente del idioma; por lo tanto, utilice dicho campo cuando necesite agrupar, comparar o almacenar eventos de forma coherente, independientemente del idioma solicitado.

El horario de verano y las horas ambiguas

Dado que las solicitudes y las respuestas se expresan en hora local, los cambios de horario de verano dan lugar a dos situaciones que conviene tener en cuenta:

Se han omitido las horas locales en el cambio horario de primavera

Cuando se adelantan los relojes, no existe una hora de la hora local. Por ejemplo, en la zona horaria America/Denver, el día del cambio de hora de primavera, 02:30:00 no constituyen una hora local válida. Evite utilizar horas del intervalo omitido como startDateTime o endDateTime.

Horarios locales repetidos durante la transición al otoño

Cuando se atrasan los relojes, una hora de la hora local se repite dos veces. Un valor como 01:30:00 el día del cambio horario de otoño resulta ambiguo. Elija horas que no coincidan con las horas repetidas para evitar dudas sobre qué instancia está solicitando.

Si su integración se ejecuta de forma autónoma y pudiera enviar una solicitud cuya hora de inicio o de finalización coincida con una transición, programe la solicitud para que se ejecute unas horas antes o después de la transición, o utilice horas que se encuentren claramente fuera de ella.

Recomendaciones para el almacenamiento y la comparación de las marcas de tiempo de respuesta

Las marcas de tiempo de las respuestas corresponden a la hora local sin desplazamiento horario. Para evitar ambigüedades en los sistemas posteriores, considere uno de los siguientes enfoques:

• Guarde la marca de tiempo de la respuesta junto con la zona horaria que haya indicado en la solicitud. Ambos elementos, considerados en su conjunto, definen un instante único en el tiempo.
• En su integración, convierta cada marca de tiempo de respuesta a UTC antes de almacenarla, utilizando la zona horaria que haya indicado en la solicitud. El almacenamiento de valores UTC simplifica las comparaciones entre datos extraídos en diferentes zonas horarias.
• Envíe siempre las solicitudes utilizando la misma zona horaria, por ejemplo, UTC, para que todas las marcas de tiempo almacenadas sean directamente comparables.

Ejemplos

Los siguientes ejemplos ilustran cómo se combinan la zona horaria, la hora de inicio y la hora de finalización.

Ventana predeterminada en la hora de la montaña

Una solicitud enviada a las 9:00 de la mañana del 15 de marzo de 2026, en la zona horaria America/Denver, sin que se haya especificado ninguna hora de inicio ni de fin, devuelve datos desde 2026-03-14T09:00:00 hasta 2026-03-15T09:00:00, ambas fechas interpretadas en la zona horaria de la Montaña.

Intervalo de tiempo concreto en la hora de Europa del Este

Una solicitud que especifique timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00, y endDateTime=2026-03-15T16:00:00 devuelve datos correspondientes a la jornada laboral de ocho horas en la hora local de Bucarest. Las marcas de tiempo de las respuestas también se muestran en hora local de Bucarest.

La misma ventana vista en dos zonas horarias

Para recuperar dos veces los mismos datos subyacentes, formateados para dos públicos distintos, envíe dos solicitudes con valores timezonediferentes y ajuste startDateTime y endDateTime de modo que correspondan a los mismos instantes en cada zona horaria. Las cargas útiles de las respuestas describen los mismos eventos, pero utilizan cadenas de marca de tiempo diferentes.