Réintégration de la gestion des horaires

Depuis 2018, la gestion des horaires complexes avait été déléguée à un module externalisé (apiHours) :

  • Le SIT continuait de proposer 2 champs horaires : ouverture.periodesOuvertures[].horaireOuverture et ouverture.periodesOuvertures[].horaireFermeture
  • Les utilisateurs pouvaient utiliser apiHours pour saisir des données plus riches :
    • plusieurs plages horaires possibles
    • découpage jour par jour
    • plusieurs types d’ouverture possibles (Ouverture, Visite guidée, Petit déjeuner…) selon les types objets
  • Elles pouvaient également être fournies dans les API d’écriture,
  • Ces données « riches » pouvaient être consultable par une API spécialisée, ou grâce aux API enrichies.

Depuis juin 2025, ces données sont réintégrées comme une donnée classique : il n’est donc plus nécessaire de réaliser des appels séparés pour récupérer ces informations.

Le format change légèrement mais s’appuie très largement sur le format multihoraire mis en place en 2018 sur apiHours.

Conséquences en API de consultation

Une période se présentait jusque là sous cette forme :

{
    "identifiant": 34525986,
    "dateDebut": "2025-02-01",
    "dateFin": "2025-02-28",
    "complementHoraire": {},
    "type": "OUVERTURE_SAUF",
    "tousLesAns": true,
    "ouverturesJournalieres": [
        {
            "jour": "DIMANCHE"
        }
    ],
    "identifiantTechnique": 34525986,
}

L’identifiantTechnique permettait ensuite de consulter les API apiHours dédiées.

Désormais, les périodes se présentent sur ce format :

{
    "identifiant": 34492028,
    "dateDebut": "2025-01-01",
    "dateFin": "2025-12-31",
    "nom": "Vacances scolaires",
    "type": "OUVERTURE_SEMAINE", // DEPRECATED
    "ouverturesJournalieres": [{"jour": "JEUDI"},{"jour": "MERCREDI"},{"jour": "SAMEDI"}] // DEPRECATED
    "tousLesAns": false,
    "identifiantTechnique": 34492028,
    "horaires": [
        {
            "type": {
                "elementReferenceType": "HoraireType",
                "id": 7457,
                "libelleFr": "Ouverture",
                "description": "Horaires d'ouverture"
            },
            "timePeriods": [
                {
                    "closed": false,
                    "weekdays": ["MON","TUE","THU","FRI","SAT"],
                    "timeFrames": [
                      {"startTime": "08:00","endTime": "12:00"},
                      {"startTime": "14:00","endTime": "18:00"}
                    ]
                },
              {
                    "closed": true,
                    "weekdays": ["WED","SUN","HOL"],
                    "timeFrames": []
                }
            ]
        }
    ]
}

Un nouveau noeud ouverture.periodesOuvertures[].horaires est désormais présent. Son format est très proche d’apiHours.

Le type horaire est devenu un élément de référence du SIT, et a été déplacé en dehors des timePeriods pour en faciliter la compréhension.

Le format des timePeriods est relativement similaire, deux changements sont à noter :

  • Apparition d’une information « closed » (true|false) : elle permet d’être plus explicite sur les jours de fermeture, mais son usage est facultatif
    • Si aucun timePeriod ne contient le samedi et le dimanche, ils sont considérés comme fermés sans précisions dans les ouvertures en clair, qui indiqueront simplement « ouvert du lundi au vendredi ».
    • Si un timePeriod contient le mercredi et le dimanche avec closed=true, l’utilisateur a spécifiquement souhaité indiquer les jours de fermeture : « fermé le mercredi et le dimanche » sera ajouté dans les ouvertures en clair.
  • Les weekdays sont enrichis d’un HOL pour Holiday : il s’agit d’indiquer les horaires d’ouverture (ou la fermeture) pour les jours fériés. Son utilisation est principalement dédiée à apporter des précisions dans les ouvertures en clair :
    • Fermé le mercredi et les jours fériés
    • Ouvert du lundi au samedi de 9h à 18h, le dimanche et les jours fériés de 14h à 18h

Dépréciation des API enrichies et de consultation directe

La donnée concernant les horaires étant désormais intégrée au SIT, la consultation des données apiHours via les API (enrichies et directe) est dépréciée :

  • https://api.apihours.apidae-tourisme.com/apidae_period?id=
  • https://api.apihours.apidae-tourisme.com/apidae_period?ids=
  • https://api.apihours.apidae-tourisme.com/apidae_period?ref=
  • https://api.apihours.apidae-tourisme.com/apidae_period?refs=
  • https://api.plateforme.apidae-tourisme.cooking/apidae/objetenrich/

Elles restent accessibles durant la phase de dépréciation, mais leur usage est déconseillé et doit être arrêté dès que possible.

Conséquences en API d’écriture

Les API d’écriture proposaient déjà le support du multihoraire d’apiHours, par l’ajout d’un noeud ouverture.periodesOuvertures[].timePeriods.

Ce format est rétrocompatible, mais déprécié.

Il faudra désormais lui préférer l’usage du noeud ouverture.periodesOuvertures[].horaires. Le format est proche mais a légèrement changé, raison pour laquelle il était préférable de changer le nom du noeud d’origine.

Retrait du formulaire de saisie JS

https://form.apihours.apidae-tourisme.com/0.6.0/bundle.js

Un plugin Javascript apiHours avait été mis à disposition des développeurs réalisant des écritures, qui proposent des interfaces de saisie à leurs utilisateurs, pour faciliter la gestion des données associées : ce plugin n’était pas ou peu utilisé et sera retiré dès livraison de l’évolution (pas de dépréciation).

Notez que l’interface de saisie utilisée sur l’IHM du SIT est désormais également développée en javascript, et peut être utilisée en dehors du SIT si nécessaire : elle n’est pas mise à disposition officiellement et ne dispose pas d’une documentation associée, mais vous pouvez faire la demande à hotline.dev@apidae-tourisme.com.

Son utilisation est visible sur le SIT, et sur https://event.apidae-tourisme.com/?horaires=1.