Dates dans les feuilles de calcul et les API : éviter les formats ambigus et les changements de jour

Pourquoi une date qui semble identique peut avoir plusieurs sens

Une cellule peut afficher « 03/04/2025 », mais cette apparence ne permet pas de savoir s’il s’agit du 3 avril ou du 4 mars. La feuille de calcul peut interpréter la valeur selon ses paramètres, le format de la cellule ou la manière dont elle a été saisie. Lors de l’envoi à un autre système, l’API peut aussi appliquer ses propres règles. Microsoft explique que les règles d’interprétation des dates dans les tableurs peuvent être complexes et recommande de les préciser autant que possible dans son [guide sur les systèmes, les formats et l’interprétation des dates](https://support.microsoft.com/es-es/excel/change-the-date-system-format-or-two-digit-year-interpretation) (source en espagnol).

C’est pourquoi il ne faut pas considérer l’affichage visuel comme un contrat d’intégration. Avant l’export, repérez les cellules contenant des dates, vérifiez les valeurs qu’elles représentent et convenez de la manière dont le système doit les recevoir. Le [guide des formats de date et de nombre de l’API Google Sheets](https://developers.google.com/workspace/sheets/api/guides/formats?hl=es-419) (source en espagnol) décrit des modèles de format pouvant être inclus dans les requêtes ; consultez la documentation du service concerné pour confirmer les formats qu’il accepte.

• Évitez les dates numériques où le jour et le mois peuvent être intervertis si le contrat n’en définit pas l’ordre.
• Ne partez pas du principe que le format visible d’une cellule détermine la façon dont l’API interprétera la donnée.

Déterminez si le champ est une date seule ou un instant

Avant de choisir un format, définissez le sens du champ. Dans ce guide, une date seule désigne un jour, comme la date d’échéance d’une tâche ; à elle seule, elle n’indique ni heure ni lieu. Un instant correspond à un point précis dans le temps, comme l’heure à laquelle une opération a été enregistrée. Même si ces deux valeurs s’affichent comme des dates dans une feuille, le contrat doit préciser laquelle est attendue.

Consignez cette distinction dans le contrat de données, et pas seulement dans une note informelle. Pour chaque colonne, indiquez son nom, sa signification, le type attendu, si les valeurs vides sont admises et un exemple valide. Si un champ représente uniquement un jour, n’ajoutez pas une heure fictive pour satisfaire une intégration. S’il représente un instant, précisez comment exprimer l’heure et le fuseau horaire ou le décalage attendu par le système destinataire.

• Demandez-vous : « La donnée doit-elle correspondre au même jour pour tous les utilisateurs ? » Si oui, définissez le champ comme une date seule.
• Demandez-vous : « Avons-nous besoin de savoir quand un événement a eu lieu ? » Si oui, définissez le traitement de l’heure et le fuseau horaire ou le décalage attendu pour cette intégration.

Utilisez une représentation explicite et un contrat de données

Pour le contrat de cette intégration, vous pouvez choisir un format explicite année-mois-jour, tel que « AAAA-MM-JJ » avec l’exemple « 2025-04-03 », plutôt que « 03/04/2025 ». Pour les instants, précisez également comment exprimer l’heure et le fuseau horaire ou le décalage attendu. Ne vous fiez pas aux paramètres régionaux d’une feuille : le producteur et le destinataire doivent convenir du même format et du même sens.

Documentez les exceptions pertinentes pour le service concerné : autorisation des secondes, précision, indication du fuseau horaire ou du décalage, et critères d’invalidité. Ne confondez pas format et signification : une cellule affichée comme une date peut contenir du texte ou une autre valeur. Le guide de l’API Google Sheets cité plus haut porte sur les modèles de format pouvant être inclus dans les requêtes ; il ne remplace pas la définition du contrat et ne détermine pas à lui seul la signification d’un champ dans votre intégration.

• Définissez pour chaque colonne le format, le type, le fuseau horaire ou le décalage le cas échéant, la précision, le caractère obligatoire et un exemple.
• Rejetez les valeurs qui ne respectent pas le contrat ou soumettez-les à vérification ; ne les « corrigez » pas silencieusement.

Précisez le fuseau horaire lorsque la donnée l’exige

Si le champ exprime uniquement une date seule, indiquez si le processus nécessite des informations horaires supplémentaires. Pour un événement associé à une heure précise, convenez du fuseau horaire ou du décalage utilisé par le producteur et le destinataire, puis consignez cette décision dans le contrat. Évitez de mélanger une heure locale avec une interprétation différente ailleurs dans le flux.

Si le flux doit conserver l’heure locale d’un événement, documentez la règle et testez les cas importants pour cette intégration, notamment ceux qui se situent près de minuit. Un changement de jour à l’affichage ne suffit pas, à lui seul, pour conclure que la valeur d’origine a été altérée : comparez le résultat au sens et aux règles définis dans le contrat. Si le champ exprime uniquement une date, évitez d’ajouter des informations horaires inutiles au processus.

• Pour chaque instant, documentez le fuseau horaire ou le décalage convenu entre le producteur et le destinataire.
• Vérifiez les cas proches de minuit pertinents pour votre flux ; comparez le résultat au contrat avant de conclure à une erreur.

Testez les cas définis pour votre intégration

Pour vérifier le comportement d’un flux donné, préparez des cas de test conformes à son contrat. Vous pouvez inclure des dates où le jour et le mois risquent d’être confondus, des valeurs proches d’un changement de jour, une cellule vide, du texte qui n’est pas une date, ainsi qu’une valeur dont la précision ou le fuseau horaire est inattendu. Décidez à l’avance si chaque cas doit être accepté, rejeté ou soumis à vérification. Cette liste est une pratique de validation propre à l’intégration ; elle ne prétend pas énoncer les exigences d’une norme externe.

Le traitement des valeurs vides mérite une règle à part entière. Définissez ce que signifie une cellule vide et évitez que le processus lui attribue automatiquement une autre valeur non convenue. Si le flux doit distinguer « absent », « inconnu » et « sans objet », documentez ces possibilités. Pour les valeurs invalides, définissez une réponse identifiable ou interrompez l’envoi afin de corriger la source ; ne remplacez pas les données silencieusement.

• Liste de tests possible : date ambiguë, fin de mois, changement d’année, minuit, cellule vide et texte invalide.
• Vérifiez ce que reçoit le destinataire et ce que voit l’opérateur lorsqu’une validation échoue.

Vérifiez le parcours des données avant de l’utiliser

Pour vérifier concrètement le flux concerné, préparez un petit ensemble d’enregistrements représentatifs et conservez une copie de leurs valeurs initiales. Faites-les suivre le parcours prévu et examinez les valeurs reçues ; si le processus prévoit de les recharger dans une feuille, vérifiez également le résultat. Comparez le sens, pas seulement l’apparence : une date réaffichée dans un autre style visuel peut rester correcte, tandis qu’un changement de jour ou d’heure peut enfreindre le contrat.

Répétez la vérification avec les cas sélectionnés et notez les résultats attendus et observés. Si une différence apparaît, cherchez à quelle étape elle survient : interprétation par la feuille, transformation, requête API ou présentation de la réponse. Ajustez le contrat ou la conversion, puis relancez le même ensemble pour vérifier le résultat de la modification.

• Conservez les valeurs d’entrée, les valeurs envoyées, la réponse et le résultat affiché afin de comparer chaque étape.
• Considérez la vérification comme réussie uniquement si le sens convenu est préservé et si les erreurs prévues sont détectées.

Organisez la vérification et l’intégration dans Apification

Comme méthode de travail, gardez une feuille de test distincte des données opérationnelles. Dans Apification Cloud, vous pouvez organiser fichiers et projets dans un espace de travail versionné, et créer ou modifier des feuilles de calcul avec ONLYOFFICE sans les sortir du stockage Cloud. Vérifiez-y les en-têtes, les formats visibles, les cellules vides et les exemples avant de préparer l’intégration. La feuille facilite l’inspection par l’équipe, mais ne remplace pas les règles de validation du service qui reçoit ou envoie les données.

Apification permet d’intégrer Cloud et ses services au moyen de REST API, OpenAPI, webhooks, iframe et JavaScript. Consultez la documentation API pertinente pour définir l’échange réel : ne présumez pas d’un point de terminaison ou d’un comportement précis à partir de ces capacités. Après une modification importante, l’historique des éléments Cloud permet de consulter les versions précédentes, de les télécharger et de restaurer leur contenu. Cette fonctionnalité peut aider à récupérer une feuille de travail, mais elle ne remplace ni les vérifications du contrat ni l’examen des résultats.

• Avant de connecter des données réelles, validez une copie de travail à l’aide d’exemples représentatifs et de règles convenues.
• Vérifiez dans la documentation de l’API quelle opération et quel format le service concerné accepte.
• Si une feuille est modifiée, consultez son historique et conservez une version connue afin de faciliter la récupération.

Questions fréquentes