Merci de consulter la partie Compréhension générale si vous ne connaissez pas le fonctionnement du multihoraire sur Apidae, avant d’utiliser l’écriture multihoraire.
L’écriture sur le multihoraire se fait par l’ajout d’une entrée timePeriods dans une ouverture.periodesOuvertures, lors d’un appel API écriture classique
Si vous proposez un formulaire de saisie d’offres touristiques, Apidae met à disposition un module javascript permettant de faciliter la génération du timePeriods : https://form.apihours.apidae-tourisme.com/0.6.0/integration/
Création d’une période avec saisie multihoraire
Pour créer une période tout en précisant des données multihoraires :
- Ajouter les informations nécessaires pour la création de la période classique :
ouverture.periodesOuvertures[].dateDebutouverture.periodesOuvertures[].dateFinouverture.periodesOuvertures[].type(obligatoire)
- Ajoutez une entrée «
timePeriods» (array) en utilisant le format du multihoraire :ouverture.periodesOuvertures[].timePeriods[]
- Notez qu’il est préférable de ne pas renseigner les champs suivants, puisqu’ils feront doublons avec votre saisie multihoraire : considérez-les dans ce cas comme d’anciens champs obsolètes (à n’utiliser que lorsqu’il n’y a aucune saisie multihoraire) :
ouverture.periodesOuvertures[].horaireOuvertureouverture.periodesOuvertures[].horaireFermeture
{
"type": "RESTAURATION",
"nom": {
"libelleFr": "17667_exemple.php 2022-08-02 16:55:27"
},
"localisation": {
"adresse": {
"commune": {
"id": 14707
}
}
},
"ouverture": {
"periodesOuvertures": [
{
"dateDebut": "2023-01-01",
"dateFin": "2023-12-31",
"type": "OUVERTURE_SAUF",
"timePeriods": [
{
"type": "opening",
"weekdays": [
"TUE",
"WED",
"THU"
],
"timeFrames": [
{
"startTime": "18:00",
"endTime": "22:00"
}
]
},
{
"type": "opening",
"weekdays": [
"FRI"
],
"timeFrames": [
{
"startTime": "18:00",
"endTime": "23:00"
}
]
},
{
"type": "opening",
"weekdays": [
"SAT",
"SUN"
],
"timeFrames": [
{
"startTime": "12:00",
"endTime": "15:00"
},
{
"startTime": "18:00",
"endTime": "23:00"
}
]
}
]
}
]
}
}Ci-dessus, nous avons créé une période d’ouverture du 2023-01-01 au 2023-31-01 sur l’offre.
Nous avons ensuite associé à cette période, 3 entrées dans timePeriods :
- Ouverture du mardi au jeudi de 18h à 22h
- le vendredi, de 18h à 23h
- le samedi et le dimanche, de 12h à 15 puis de 18h à 23h
Bien sûr, comme pour tout appel API d’écriture, n’oubliez pas d’inclure le champ ouverture.periodesOuvertures dans le fieldlist :
[
"nom",
"localisation.adresse.commune",
"ouverture.periodesOuvertures"
]Modifier une saisie multihoraire
Pour modifier une saisie existante, vous devez repasser les valeurs précédentes de ouverture.periodesOuvertures[] en conservant bien l’identifiant de la période à modifier (récupéré au préalable sur l’objet par API) :
ouverture.periodesOuvertures[].identifiant
Dans l’exemple ci-dessous, nous modifions une période existante
{
"type": "RESTAURATION",
"ouverture": {
"periodesOuvertures": [
{
"identifiant": 21726215,
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"horaireOuverture": "12:02:00",
"horaireFermeture": "13:02:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false,
"identifiantTechnique": 21726215,
"timePeriods": [
{
"type": "opening",
"weekdays": [
"MON"
],
"timeFrames": [
{
"startTime": "12:02",
"endTime": "13:02"
}
]
}
]
}
]
}
}Notez en particulier la présence du champ ouverture.periodesOuvertures[].identifiant : c’est lui qui nous permet de modifier la période existante.
Supprimer une saisie multihoraire
La méthode la plus simple pour supprimer une saisie multihoraire est de renvoyer les ouverture.periodesOuvertures[] existantes sans repasser l’identifiant de la période concernée lors de votre appel de modification.
De cette façon, vous allez en réalité supprimer l’ancienne période (qui avait donc une saisie multihoraire) et en créer une nouvelle.
Objet initial existant (appel API)
{
"type": "RESTAURATION",
"ouverture": {
"periodeEnClair": {
"libelleFr": "Du 02\/02 au 11\/11\/2023 \nOuverture le lundi de 12h02 \u00e0 13h02.",
"libelleEn": "From 02\/02 to 11\/11\/2023 \nOpening hours on Monday between 12.02 pm and 1.02 pm."
},
"periodesOuvertures": [
{
"identifiant": 21726215,
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"horaireOuverture": "12:02:00",
"horaireFermeture": "13:02:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false,
"identifiantTechnique": 21726217
}
]
}
}Saisie multi-horaire existante (appel API multi-horaire)
{
"externalType": "RESTAURATION",
"externalRef": 5902207,
"externalId": 21726217,
"startDate": "2023-02-02",
"endDate": "2023-11-11",
"timePeriods": [
{
"type": "opening",
"weekdays": [
"MON"
],
"timeFrames": [
{
"startTime": "12:02",
"endTime": "13:02"
}
]
}
],
"type": "apidae_period",
"userId": 20320,
"updatedAt": 1659952943152
}On constate sur l’objet existant une saisie multihoraire (12:02>13:02) pour la période 21726215 (identifiant) / 21726217 (identifiantTechnique) (Rappel : la saisie multihoraire se récupère en appelant l’API multihoraire avec l’identifiantTechnique, dans le cas présent https://api.apihours.apidae-tourisme.com/apidae_period?id="21726217"
Pour la « supprimer », au lieu de modifier la période 21726215, on va envoyer une modification de l’objet en repassant la période sans son identifiant.
Payload de modification
{
"type": "RESTAURATION",
"ouverture": {
"periodesOuvertures": [
{
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"horaireOuverture": "12:02:00",
"horaireFermeture": "13:02:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false
}
]
}
}Constatez en particulier l’absence de ouverture.periodesOuvertures[].identifiant.
Sur l’API d’écriture, lorsque vous souhaitez modifier un nœud multi-valué (illustrations, périodes…) il est nécessaire de repasser le tableau complet à chaque modification.
Dans le cas présent, on demande en réalité la suppression de la période précédente 21726215, puisqu’on repasse un tableau ouverture.periodesOuvertures[] avec une nouvelle entrée (pas d’identifiant), sans repasser l’ancienne (21726215) qui sera donc supprimée.
Résultat après modification
{
"type": "RESTAURATION",
"ouverture": {
"periodeEnClair": {
"libelleFr": "Du 02\/02 au 11\/11\/2023 de 12h02 \u00e0 13h02.",
"libelleEn": "From 02\/02 to 11\/11\/2023 between 12.02 pm and 1.02 pm."
},
"periodesOuvertures": [
{
"identifiant": 21726221,
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"horaireOuverture": "12:02:00",
"horaireFermeture": "13:02:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false,
"identifiantTechnique": 21726221
}
]
}
}On constate donc que la période 21726215 n’est plus présente, une nouvelle (21726221) a été créée.
Un appel à https://api.apihours.apidae-tourisme.com/apidae_period?id="21726221" renverra logiquement une erreur 404.
Format d’une entrée timePeriods[]
timePeriods[].type: chaîne de caractères.
Les types sont administrables et ne sont donc pas figés, mais le type le plus communément utilisé est"opening".
Attention : passer un type inexistant ne générera pas d’erreur à l’enregistrement, mais l’édition du multihoraire ne sera pas possible sur l’interface d’Apidae.
timePeriods[].weekdays[]: tableau de chaînes de caractères.
Valeurs possibles : MON, TUE, WED, THU, FRI, SAT, SUNtimePeriods[].timeFrames[].startTime: chaîne de caractères au format 00:00 (double digit obligatoire)timePeriods[].timeFrames[].endTime: chaîne de caractères au format 00:00 (double digit obligatoire)timePeriods[].timeFrames[].recurrence
{
"type": "opening",
"weekdays": [
"MON"
],
"timeFrames": [
{
"startTime": "12:02",
"endTime": "13:02"
}
]
}Erreurs courantes
Modifier sans passer ouverture.periodesOuvertures[].identifiant
Si vous modifiez une période sans repasser l’identifiant : en réalité, vous allez supprimer l’ancienne période, et en créer une nouvelle. Si vous n’avez pas repassé de timePeriods dans votre nouvel enregistrement, alors la saisie multi-horaire sera perdue.
Format des horaires
Les horaires du timePeriod dans le multihoraire (timePeriods[].timeFrames[].startTime & endTime) sont au format 00:00 : le 0 en tête est indispensable (5:00 générera une erreur d’écriture).
Type inexistant
Le passage d’un timePeriods[].type inexistant ne générera pas d’erreur à l’enregistrement, mais l’offre ne pourra pas être modifié sur l’interface d’Apidae, il convient donc de vous assurer d’utiliser un type existant (le plus souvent : opening).
Modification d’une période existante disposant d’une saisie multihoraire sans repasser de timePeriods
Habituellement sur les API d’écriture, lorsqu’un bloc existant est renvoyé en modification, toute information manquante sera supprimée.
Exemple existant API :
[
{
"identifiant": 21726196,
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"horaireOuverture": "14:01:00",
"horaireFermeture": "15:01:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false
}
]Saisie multihoraire associée : https://api.apihours.apidae-tourisme.com/apidae_period?id="21726196"
{
"timePeriods": [
{
"type": "opening",
"weekdays": [
"MON"
],
"timeFrames": [
{
"startTime": "12:00",
"endTime": "14:00",
"recurrence": null
}
],
"labels": {
"ru": "часы открытия",
"fr": "Ouverture",
...
}
}
]Appel API de modification :
[
{
"identifiant": 21726196,
"dateDebut": "2023-02-02",
"dateFin": "2023-11-11",
"type": ""OUVERTURE_SAUF",
"tousLesAns": false
}
]Dans cet exemple, l’absence des champs horaireOuverture et horaireFermeture entraînera leur suppression lors de l’appel API (L’API considère qu’ils ont été retirés de la période d’ouverture 21726196).
En revanche, l’absence du champ timePeriods ne supprimera pas l’entrée multihoraire associée à la période 21726196.
Compréhension générale
Le Multihoraire (parfois appelé Apidate) est un module externalisé du SIT.
Les données qu’il contient (précisions sur les jours d’ouvertures et horaires) ne sont donc pas stockées directement sur Apidae mais sur un module externalisé.
Les horaires peuvent se présenter de plusieurs manières sur une offre :
Dans l’offre elle-même :
Données en provenance du SIT :
"ouverture": {
"periodesOuvertures": [
{
"identifiant": 21724236,
"dateDebut": "2023-01-01",
"dateFin": "2023-12-31",
"horaireOuverture": "10:12:00",
"horaireFermeture": "12:52:00",
"type": "OUVERTURE_SAUF",
"tousLesAns": false,
"identifiantTechnique": 21724236
}
]
}Ce format possède un inconvénient majeur : il ne propose qu’une seule plage horaire (horaireOuverture + horaireFermeture) pour chaque période.
Dans le module Multihoraire :
Des précisions peuvent donc être apportées pour chaque periodesOuvertures, en utilisant le module externalisé Multihoraire.
Côté interface, chaque utilisateur peut saisir des données dans ce module :
https://aide.apidae-tourisme.com/hc/fr/articles/360004603111-Saisie-l-onglet-Ouverture-Saisie-des-informations-Multihoraires
Il est donc normal que les API d’écriture proposent également cette fonctionnalité, dont l’usage est décrit ci-dessous.
Avant d’utiliser cette fonctionnalité, il convient de bien comprendre son fonctionnement :
- Chaque saisie Multihoraire est associée à une période de l’offre 1234, identifiée par
ouverture.periodesOuvertures[].identifiant(21724236dans l’exemple ci-dessus) - Vous pouvez consulter ces saisies de plusieurs façons :
- Par l’interface d’Apidae bien sûr
- En consultant directement l’API Multihoraire à l’aide de l’identifiant de la période (
ouverture.periodesOuvertures[].identifiant)
Ex : https://api.apihours.apidae-tourisme.com/apidae_period?id= »21724236″ - En utilisant l’API enrichie (appel du SIT + Multihoraire en 1 seule requête)
Le format du multihoraire est plus riche que celui utilisé ci-dessus sur le SIT, vous trouverez le format sur la page concernée.