Gestion de la date et de l'heure dans l'API d'exportation de données

Le modèle de date et d'heure

Trois règles définissent la manière dont l'API traite les dates et les heures :

1. Toute requête adressée aux /jobs, /printer-states et /printer-interventions doit inclure un paramètre timezone contenant un identifiant de fuseau horaire IANA valide, par exemple America/Denver ou Europe/Bucharest.
2. Toute valeur startDateTime ou endDateTime fournie dans la requête est interprétée comme une heure locale dans le fuseau horaire indiqué. Ces valeurs ne tiennent pas compte du décalage horaire par rapport à l'UTC.
3. Chaque valeur de date et d'heure contenue dans la réponse est formatée selon l'heure locale du même fuseau horaire, en utilisant le format YYYY-MM-DDTHH:MM:SS.sss.

Le paramètre timezone détermine la signification de la requête et le formatage de la réponse. Deux requêtes portant sur les mêmes données sous-jacentes, envoyées avec des fuseaux horaires différents, génèrent des réponses comportant des chaînes de date et d'heure différentes, même si elles décrivent les mêmes événements.

Format de la date et de l'heure

L'API utilise un format unique pour toutes les valeurs de date et d'heure, tant dans les requêtes que dans les réponses :

YYYY-MM-DDTHH:MM:SS.sss

Par exemple, 2026-03-15T14:30:00.000 correspond à 14 h 30 le 15 mars 2026, selon le fuseau horaire indiqué dans la requête.

Dans les requêtes, la partie en millisecondes (.sss) est facultative. Dans les réponses, il est toujours présent.

Période par défaut

Vous pouvez omettre startDateTime, endDateTime, ou les deux. Ces deux valeurs par défaut s'appliquent indépendamment l'une de l'autre :

• Si vous n'indiquez pas de startDateTime, l'API considère que la plage commence 24 heures avant l'heure actuelle.
• Si vous n'indiquez pas de endDateTime, l'API utilise l'heure actuelle comme heure de fin de la plage.

Les valeurs par défaut se combinent comme on peut s'y attendre :

• Si vous n'indiquez aucune de ces deux valeurs, l'API renvoie les données des dernières 24 heures.
• Si vous indiquez startDateTime comme étant « il y a une heure » et que vous n'indiquez pas endDateTime, l'API renvoie les données de l'heure précédente.
• Si vous indiquez endDateTime et que vous n'indiquez pas startDateTime, l'API renvoie les données correspondant à la période commençant 24 heures avant la requête et se terminant à l'heure indiquée par endDateTime.

Les valeurs par défaut sont calculées selon le fuseau horaire indiqué dans la requête.

Conservation des données : les sept derniers jours

L'API d'exportation de données fournit des données opérationnelles en temps réel. Les historiques des travaux, l'historique de l'état de l'imprimante et les événements d'intervention ne sont disponibles que pour les sept derniers jours. Toute demande concernant des données datant de plus de sept jours génère une erreur.

Prévoyez votre intégration de manière à ce que les extractions planifiées s'exécutent suffisamment souvent pour capturer toutes les données avant qu'elles ne deviennent obsolètes :

• Pour les relevés nocturnes, prévoyez une marge d'au moins un ou deux jours. Si une exécution planifiée échoue, vous disposez de suffisamment de temps pour en déterminer la cause et la relancer avant que les données ne soient plus disponibles.
• Pour les mises à jour ou les extractions ponctuelles, ne demandez pas de données datant de plus de sept jours.

Règles applicables à la plage demandée

• startDateTime doit être antérieure à endDateTime. Toute requête qui enfreint une règle génère une erreur ERR_INVALID_DATE_RANGE.
• Ces deux valeurs doivent respecter le format décrit à l'adresse Format de la date et de l'heure. Une requête contenant une valeur mal formée génère une erreur ERR_INVALID_DATE_FORMAT.
• La durée comprise entre startDateTime et endDateTime ne doit pas dépasser l'intervalle maximal autorisé. Une requête qui dépasse la limite maximale génère une erreur ERR_DATE_RANGE_EXCEEDED.

Indication du fuseau horaire

Le paramètre timezone accepte les identifiants de fuseau horaire de l'IANA, tels que America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo ou UTC. La page de documentation interactive présente une liste de toutes les valeurs acceptées par l'API.

Un identifiant non valide ou non reconnu génère une erreur ERR_INVALID_TIMEZONE. Les abréviations à trois lettres telles que MST ou EST ne constituent pas des identifiants IANA et ne sont pas acceptées ; veuillez utiliser à la place l'identifiant de la région correspondant (par exemple, America/Denver ou America/New_York).

Fournir la langue

Le paramètre timezone n'est pas le seul paramètre qui détermine la manière dont l'API formate une réponse. Le point de terminaison /printer-interventions accepte également un paramètre language facultatif, qui détermine la langue du champ description dans la réponse.

Les valeurs autorisées sont : en (anglais), de (allemand), ja (japonais), it (italien), fr (français) et es (espagnol). Une valeur ne figurant pas dans cette liste entraîne une erreur ERR_INVALID_LANGUAGE.

Il convient de prendre en compte deux aspects de ce paramètre :

• Si vous n'indiquez pas de paramètre, ou si aucune description n'est disponible dans la langue que vous avez demandée, la description s'affiche en anglais. La requête aboutit dans les deux cas ; votre intégration ne peut donc pas partir du principe que la langue d'une description correspond à celle qu'elle a demandée.
• Ce paramètre n'affecte que le champ description. Le champ interventionCode qui l'accompagne est indépendant de la langue ; utilisez donc ce champ lorsque vous avez besoin de regrouper, de comparer ou de stocker des événements de manière cohérente, quelle que soit la langue demandée.

L'heure d'été et les horaires ambigus

Les requêtes et les réponses étant exprimées en heure locale, les changements d'heure liés à l'heure d'été donnent lieu à deux situations dont il convient de tenir compte :

Heures locales ignorées lors du passage à l'heure d'été

Lorsque les horloges sont avancées d'une heure, une heure de l'heure locale n'existe pas. Par exemple, dans le fuseau horaire America/Denver, le jour du passage à l'heure d'été, 02:30:00 n'est pas une heure locale valide. Évitez d'utiliser des heures comprises dans la plage d'heures exclue comme startDateTime ou endDateTime.

Horaires locaux répétés lors du passage à l'heure d'automne

Lorsque les horloges reculent d'une heure, une heure de l'heure locale se produit deux fois. Une valeur telle que 01:30:00 le jour du passage à l'heure d'hiver est ambiguë. Choisissez des horaires en dehors des heures répétées afin d'éviter toute ambiguïté quant à l'instance que vous demandez.

Si votre intégration s'exécute en mode automatique et risque d'envoyer une requête dont l'heure de début ou de fin se situe pendant une transition, programmez l'exécution de cette requête à quelques heures avant ou après la transition, ou choisissez des horaires qui se situent clairement en dehors de celle-ci.

Recommandations concernant le stockage et la comparaison des horodatages de réponse

Les horodatages des réponses correspondent à l'heure locale, sans décalage horaire. Afin d'éviter toute ambiguïté dans les systèmes en aval, envisagez l'une des approches suivantes :

• Enregistrez l'horodatage de la réponse ainsi que le fuseau horaire que vous avez indiqué dans la requête. Ces deux éléments, pris ensemble, permettent d'identifier un instant unique dans le temps.
• Dans votre intégration, convertissez chaque horodatage de réponse en UTC avant de l'enregistrer, en utilisant le fuseau horaire que vous avez indiqué dans la requête. Le stockage des valeurs UTC simplifie les comparaisons entre des données extraites dans différents fuseaux horaires.
• Veillez à toujours soumettre vos requêtes en utilisant le même fuseau horaire, par exemple UTC, afin que tous les horodatages enregistrés soient directement comparables.

Exemples

Les exemples suivants illustrent comment le fuseau horaire, l'heure de début et l'heure de fin s'articulent entre eux.

Fenêtre par défaut à l'heure des Rocheuses

Une requête soumise à 9 h 00 le 15 mars 2026, dans le fuseau horaire America/Denver, sans heure de début ni de fin indiquée, renvoie les données comprises entre 2026-03-14T09:00:00 et 2026-03-15T09:00:00, toutes deux exprimées en heure des Rocheuses.

Plage horaire spécifique (heure d'Europe de l'Est)

Une requête contenant les paramètres timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00, et endDateTime=2026-03-15T16:00:00 renvoie les données relatives à la journée de travail de huit heures à l'heure locale de Bucarest. Les horodatages des réponses sont également exprimés en heure locale de Bucarest.

La même fenêtre vue selon deux fuseaux horaires

Pour récupérer deux fois les mêmes données sous-jacentes, mises en forme pour deux publics différents, envoyez deux requêtes avec des valeurs de fuseau horaire différentes et ajustez les paramètres startDateTime et endDateTime de manière à ce qu'ils correspondent aux mêmes instants dans chaque fuseau horaire. Les données utiles des réponses décrivent les mêmes événements, mais utilisent des chaînes de caractères d'horodatage différentes.