# Synchronisation iCal et import/export

![ical-menu-item.png](./attachments/ical-menu-item.png)

HBook vous permet d**’importer**, **exporter** et de **synchroniser vos calendriers** grâce aux flux ou ficheirs iCal. HBook met à jour le planning de réservation avec les calendriers synchronisés, à une fréquence par défaut de toutes les heures. Vous pouvez modifier cette fréquence de synchronisation jusqu'à toutes les 5 minutes.

> [!INFO]
> Nous **recommandons fortement** d’utiliser HBook comme calendrier principal et de paramétrer la synchronisation **dans les deux sens** entre HBook et chacun de vos calendriers externes. Vous ne devez pas synchroniser vos calendriers externes entre eux directement, car ils sont déjà synchroniser grâce à HBook.

* * *

<a id="quest-ce-que-la-synchronisation-ical"></a>

## Qu'est-ce que la synchronisation iCal?

Ical est un format de fichiers très pratique pour échanger des calendriers. Ce format est utilisé par:

- des applications de type Agenda/Calendrier : iCal, Google Calendar, Outlook Calendar...
- des plateformes de réservations et OTA : AirBnb, booking.com, TripAdvisor, Expedia, VRBO, HomeAway, etc...

Ce que nous appelons synchronisation est en fait un import d'un flux de données ical qui est effectué à intervalle régulier par chaque calendrier/plateforme/OTA de façon indépendante. Voici ce qui se passe :

- Chaque heure (ou à la fréquence indiquée dans **HBook > Sync iCal > Paramètres de la sync iCal**), HBook vérifie les flux iCal de tous les calendriers ajoutés dans **HBook > Sync iCal > Calendriers synchronisés**. Vous pouvez rafraîchir vos calendriers manuellement (= lancer manuellement la sync) en cliquant sur le bouton "Mettre à jour les calendriers". Toute nouvelle réservation sera importée dans HBook et apparaîtra dans la liste de réservation. 
- À leur propre fréquence, les calendriers externes (AirBnb, TripAdvisor, booking.com, HomeAway, Expedia, VRBO, etc...) procèdent de la même manière et appellent les flux iCal de HBook afin de mettre à jour leurs calendriers. Il vous faut bien ajouter l'url des calendriers HBook dans chaque plateforme/calendrier externe. L'évènement/réservation sera importée (Google ou iCal ou toute application de calendriers) ou les dates seront bloquées (AirBnb, TripAdvisor, booking.com, HomeAway ou toute OTA/plateforme de réservation). Les informations affichées au sujet de ces réservations/dates non-disponibles importées dépendent de chaque plateforme. Certaines applications/plateformes de réservations ont un bouton/lien pour rafraîchir les calendriers (= lancer la synchronisation manuellement).

Vous pouvez consulter [cet article](https://maestrel.atlassian.net/wiki/spaces/BC/pages/43974784/Puis-je+synchroniser+HBook+avec+AirBnb+Expedia+VRBO+booking.com+TripAdvisor+Agoda+etc...) de notre base de connaissances pour voir une liste non-exhaustive des différentes applications, plateformes de réservations, OTA, calendriers... qui proposent la synchronisation iCal.

* * *

<a id="présentation-du-tableau-de-gestion-ical"></a>

## Présentation du tableau de gestion iCal

> [!INFO]
> Si vous avez une extension de type "Coming soon/Maintenance", il vous faudra la désactiver pour que la synchronisation soit opérationnelle. Sinon, les calendriers ical ne sont pas joignables (car la page de "Coming soon" est retournée au lieu du calendrier ical de l'hébergement.

![sync-table.png](./attachments/sync-table.png)

<a id="mise-à-jour-manuelle-des-calendriers-dernière-synchronisation"></a>

### Mise à jour manuelle des calendriers - Dernière synchronisation

1. Vous pouvez lancer manuellement la mise à jour des calendriers HBook avec vos calendriers externes, en cliquant sur “Mettre à jour les calendriers”.
2. Ici s’affiche la date et heure de la dernière mise à jour effectuée.

<a id="export-des-calendriers-hbook"></a>

### Export des calendriers HBook

3. **Télécharger le fichier .ics** du calendrier HBook de cet hébergement.
4. Cliquez ici afin d'**obtenir l'url** du calendrier. Vous pouvez copier et coller cet url pour entrer l'url de ce calendrier HBook dans vos calendriers externes.

> [!INFO]
> Si vous avez besoin d'obtenir une URL contenant **toutes les réservations d'un calendrier**, vous pouvez cliquer sur “Obtenir l'URL du calendrier contenant l’ensemble des calendriers HBook en un seul calendrier”. Ce lien se trouve sous le tableau de synchronisation iCal.

<a id="paramètres-de-requête-ajoutés-à-lurl"></a>

#### Paramètres de requête ajoutés à l'URL

L'URL d'exportation iCal de HBook est structurée à l'aide des paramètres `accom_id` et `accom_num`.

Par défaut, lors d'une nouvelle installation de HBook, nous activons automatiquement une **clé aléatoire** qui est également ajoutée à l'URL d'exportation. Vous verrez un paramètre nommé `key` lorsque vous obtiendrez l'URL d'exportation. Cette mesure vise à sécuriser l'accès à vos flux iCal HBook, qui seraient sinon facilement accessibles.

> [!INFO]
> Pour les installations plus anciennes, vous verrez un paramètre intitulé “Ajouter une clé aléatoire à l'URL iCal HBook” dans la section [Paramètres de l'export iCal](#inlineextensionparamètres-de-lexport-ical) de **HBook > Synchronisation iCal**.

<a id="paramètres-de-requête-supplémentaires-disponibles"></a>

#### Paramètres de requête supplémentaires disponibles

HBook fournit différents paramètres qui peuvent être ajoutés à la fin de l'URL d'exportation. Cela peut être utile dans les cas suivants :

- lorsque vous avez besoin d'un format différent pour une exportation spécifique : par défaut, HBook exporte les réservations sous forme de dates, mais vous pouvez avoir besoin de les exporter avec la date et l'heure. C'est généralement le cas lors de l'exportation vers un agenda (Google Calendar, etc.).
- lorsque vous souhaitez remplacer le comportement par défaut défini dans **HBook > Sync iCal > Paramètres de l'export**.

Vous pouvez ajouter jusqu'à 4 paramètres de requête à cette URL:

- **agenda**: par défaut, ce paramètre est à “no”. Vous le passerez à “oui” pour les agendas (Google Calendars, etc.). Avec ce paramètre à “yes”, la date est formatée avec une information supplémentaire sur l'heure (par défaut, 15h pour l’heure d'arrivée et 11h pour l’heure de départ). Ceci est utile pour les agendas, afin que vous puissiez voir la réservation au fil des jours. Vous pouvez modifier les valeurs par défaut pour l’heure d'arrivée et pour l’heure de départ en utilisant les [filtres HBook](../documentation-hbook/personnalisation-de-lextension.md#filtres-ical-sync).

- **future\_only**: par défaut, ce paramètre est à “yes”. Si vous souhaitez que toutes les réservations et dates bloquées antérieures soient incluses dans l'exportation (par défaut, jusqu'à 2 ans dans le passé), vous passerez ce paramètre avec la valeur "no". Vous pouvez modifier la valeur par défaut pour le nombre d'années d'historique à inclure, en utilisant les [filtres HBook](../documentation-hbook/personnalisation-de-lextension.md#filtres-ical-sync).
- **reservations\_only**: par défaut, ce paramètre est à “no”. Si vous avez indiqué dans vos paramètres d’export iCal (dans **HBook > Sync iCal > Paramètres de l’export**) que vous souhaitez inclure les dates bloquées dans l’export, mais que pour certains calendriers vous ne souhaitez avoir que les réservations (sans les dates bloquées), vous utiliserez ce paramètre et passerez la valeur “yes”.
- **website\_only** : par défaut, cette option est définie sur “non”. Vous la passerez à “yes” si vous avez choisi d'inclure toutes les réservations (et pas seulement celles provenant du site web) dans l'exportation (dans **HBook > Sync iCal > Paramètres de l'export**), mais que vous souhaitez remplacer ce paramètre pour un calendrier où vous souhaitez exporter uniquement les réservations provenant du site web.

> [!NOTE]
> **Exemples d’URL iCal avec paramètres de requête additionnels**
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&agenda=yes
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&agenda=yes&reservations\_only=yes
> - https://web-dom.com/?feed=hbook-calendar.ics&accom\_id=102&accom\_num=1&website\_only=yes
> - https://website.com/?feed=hbook-all-calendars.ics&future\_only=no
> - https://website.com/?feed=hbook-all-calendars.ics&&key=KBDEHAOEY25RPNO&agenda=yes

<a id="importer-un-calendrier"></a>

### Importer un calendrier

5. Cliquez sur **Importer un fichier .ics**
6. Donnez un **nom** à ce calendrier qui sera importé. Ce nom sera affiché comme origine des réservations importées.
7. Sélectionnez **le fichier .ics** qui doit être importé. Tout évènement futur de ce calendrier sera traité. Un message de notification vous indiquera le résultat de l'import.

**Synchroniser avec vos calendriers externes**

8. Pour synchroniser HBook avec un calendrier externe iCal, cliquez sur **Synchroniser avec un nouveau calendrier**.
9. Indiquez le **nom** que vous souhaitez donner à ce calendrier. Ce nom sera affiché comme origine des réservations importées.
10. Indiquez l'**URL** du calendrier externe.
11. Cliquez sur **Synchroniser**. Tout évènement futur de ce calendrier sera traité. Un message de notification vous indiquera le résultat de l'import.

**Calendriers synchronisés**

12. Cliquez sur **Editer** pour modifier le nom ou l'url du calendrier
13. Cliquez sur **Supprimer** si vous souhaitez stopper la synchronisation de HBook avec ce calendrier externe.

> [!INFO]
> Merci de prendre note que le format iCal est pensé pour **la synchronisation de calendriers uniquement**. Il n’y a pas de synchronisation des informations de paiement, client, nombre d’adultes/enfants, etc. Vous pourrez éditer ces informations directement dans la liste de réservation.

* * *

<a id="présentation-des-paramàtres-de-synchronisation-ical"></a>

## Présentation des paramàtres de synchronisation iCal

Afin de s'adapter à la diversité des calendriers exterenes proposant la synchronisation iCal et afin de vous offrir des options de synchronisation, vous trouverez les paramètres suivants :

<a id="paramètres-de-notifications"></a>

### Paramètres de notifications

HBook peut sauvegarder et afficher ces [notifications](#comprendre-notifications-ical) concernant la synchronisation.

![settings-ical-notif.png](./attachments/settings-ical-notif.png)

1. Indiquez si vous souhaitez qu'HBook **garde des logs** des notifications. Nous recommandons d'activer les notifications au moins lors de la mise en place de la synchronisation afin de pouvoir surveiller toute erreur et de faciliter le debug.
2. Indiquez si vous souhaitez **afficher** les notifications. Elles apparaîtront en haut de la page **Réservations**.

<a id="paramètres-des-prix"></a>

### Paramètres des prix

Lorsque vous modifiez une réservation dans la [liste des réservations](../documentation-hbook/reservations/liste-des-reservations.md), HBook met automatiquement à jour le prix de la réservation. Dans cette section, vous trouverez les paramètres permettant d'ajuster la mise à jour des prix pour les réservations importées depuis un calendrier iCal.

![settings-ical-prices.png](./attachments/settings-ical-prices.png)

1. Vous pouvez **désactiver** la mise à jour des prix pour les réservations importées depuis un calendrier externe.
2. Si vous avez activé la mise à jour des prix, vous pouvez sélectionner les **frais/taxes** à inclure dans le calcul du prix.

<a id="paramètres-de-limport-ical"></a>

### Paramètres de l'import iCal

![settings-ical-import-1.png](./attachments/settings-ical-import-1.png)

1. Indiquez la fréquence souhaitée de synchronisation. Merci de noter que cela affecte uniquement la fréquence à laquelle HBook met à jour ses calendriers en prenant en compte les modifications/nouvelles réservations reçues sur vos calendriers externes. Cela n'a aucun impact sur la fréquence de mise à jour des calendriers externes (AirBnb, booking.com, Expedia...), qui font cette mise à jour à leur propre fréquence, indépendamment d'HBook.
2. Si les **dates** d'une réservation ont été modifiées dans le calendrier externe, HBook peut **mettre automatiquement à jour** les dates de la réservation correspondante de la liste de réservation. Cette option devra être désactivée si un de vos calendriers externes ne suit pas les standards iCal (par exemple si l'UID n'est pas conservée).
3. Si les **une réservation a été annulée** dans le calendrier externe, HBook peut **mettre automatiquement à jour** le statut de la réservation correspondante importée dans HBook et les dates seront de nouveau disponibles. Cette option devra être désactivée si un de vos calendriers externes ne suit pas les standards iCal (par exemple si l'UID n'est pas conservée).
4. Le paramétrage par défaut de HBook est de ne pas importer **les dates bloquées**, indiquées comme “non-disponible” dans vos calendriers externes. Vous pouvez modifier ce paramètre, mais nous ne le vous recommandons pas. Si vous le modifiez, il vous faudra utiliser les paramètres additionnels décrits ci-après.

> [!INFO]
> Pour une synchronisation efficace et sans accrocs, nous recommandons d’utiliser HBook comme **calendrier principal**. En conséquence, vous ajouterez toute date non disponible à la réservation directement dans **HBook > Réservations > Bloquer hébergement**. Ceci n’est pas pour l’ajout de réservations, mais bien pour bloquer des dates non réservables (par exemple, si vous avez des travaux de peinture prévus).

<a id="paramètres-additionnels-pour-la-fenêtre-dimport-ical"></a>

#### **Paramètres additionnels pour la fenêtre d’import iCal**

Dans certains cas, il se peut que vous avez besoin d'empêcher HBook d'importer certaines dates qui sont incluses dans l'export d'un calendrier externe. Ceci peut arriver lorsque des calendriers externes ajoutent dans le contenu de l'export des dates non disponibles du fait de paramètres spécifiques à une plateforme.

Par exemple, il se peut qu'aucun tarif ne soit indiqué pour une période lointaine ou pour une date spécifique, certains jours peuvent être bloqués du fait d'un paramètre de fenêtre de réservation ou de délai (afin d'éviter les réservations de dernières minutes). Cela va créer des réservations "fausses" ou "fantômes" qui seront importées dans votre liste de réservations.

Vous utiliserez donc les paramètres suivants pour paramétrer la fenêtre d'import des réservations via iCal:

![settings-ical-import-2.png](./attachments/settings-ical-import-2.png)

3. Indiquez le **nombre de jours** à partir de la date du jour afin de déterminer la **date minimum d'import**.
4. Indiquez le **nombre de mois** maximum d'import à partir d'aujourd'hui comme **date maximum**.
5. Si vous n'acceptez pas de réservations d'une seule nuit **dans aucun de vos calendriers externes**, vous pouvez l'indiquer ici. HBook ignorera tout évènement d'une seule nuit lors de l'import iCal

<a id="paramètres-de-lexport-ical"></a>

### Paramètres de l'export iCal

![settings-ical-export.png](./attachments/settings-ical-export.png)

1. Vous pouvez choisir d’ajouter une **clé aléatoire** à l’URL d’export. C’est une mesure de sécurité que nous vous recommandons.
2. Vous pouvez choisir d'inclure ou non dans l'export les **dates bloquées** (ajoutées depuis **Réservations > Bloquer des hébergements**). Nous vous recommandons d’avoir ce paramètre à “Oui”.
3. Vous pouvez choisir d'inclure ou non dans l'export les **dates bloquées du fait d'un "Temps de préparation"**. Si vous gérez dans chaque plateforme ce temps de préparation, alors nous vous recommandons de mettre ce paramètre à “Non”.
4. Vous pouvez choisir d'inclure dans l'export uniquement les **réservations avec le statut "Confirmée"**.
5. La propriété iCal **Résumé (SUMMARY)** est une ligne courte de description de la réservation. Vous pouvez utiliser [les variables listées](../documentation-hbook/liste-des-variables.md) afin de personnaliser cette description de réservation. Certains calendriers externes peuvent afficher ce "Résumé" afin de vous aider à identifier la réservation.
6. La propriété **Description (DESCRIPTION)** est un champ plus détaillé qui permet de communiquer des informations au sujet de la réservation. Vous pouvez utiliser [les variables listées](../documentation-hbook/liste-des-variables.md) afin de personnaliser cette description de réservation. Certains calendriers externes peuvent afficher cette "Description", mais ce n'est pas toujours le cas.

> [!INFO]
> HBook est codé de manière à optimiser l'intégration de la synchronisation iCal avec les divers applications/calendriers possibles, dans le souci d'automatiser le plus possible les mises à jour (dates, réservations annulées) ainsi que d'optimiser les informations transmises. Cependant, tous les calendriers externes ne suivent pas les standards iCal. Ainsi, il est possible que vous deviez désactiver certaines fonctionnalités afin de faire fonctionner la synchronisation.

* * *

<a id="comprendre-les-notifications-ical"></a>

## Comprendre les notifications iCal

Une fois mise en place, la synchronisation est effectuée de manière automatique. Il est cependant important de vérifier de façon régulière que tout fonctionne comme il se doit. Nous affichons des notifications en haut de la page **Réservations** lorsqu'il y a des erreurs de synchronisation.

Ces messages sont ici pour vous aider à surveiller la synchronisation. Cela peut être :

- **une erreur de connexion** : cela signifie simplement qu'HBook n'a pas pu se connecter au serveur du calendrier externe. Comme la synchronisation est lancée toutes les heures (ou à votre fréquence préférée) vous pouvez ignorer ce message, sauf dans le cas où il serait répété à chaque synchronisation. Dans ce cas, nous vous invitons à choisir une fréquence moins élevée (certains serveurs considèrent les requêtes trop fréquentes comme potentiellement dangereuses et refusent l'accès) et à vous rapprocher de votre hébergeur afin de voir s'ils ont des logs de ces refus de connexions.
- **une réservation n'a pas pu être importée** : vous devriez vérifier pourquoi ces dates ne sont pas disponibles dans HBook. Les dates de la réservation non importée sont indiquées pour vous aider à vérifier cela.
- **une réservation a été modifiée** : vous devriez vérifier s'il est possible de modifier la réservation dans HBook et mettre à jour manuellement en conséquence.
- **une erreur de signature** : par mesure de sécurité, HBook vérifie la “signature” du calendrier lors de l’appel à l’URL du calendrier externe. Une erreur de signature indique que la signature du calendrier retourné diffère de celle attendue. Nous vous invitons dans ce cas à nous contacter.

* * *

<a id="ressources-guides-pas-à-pas-problèmes-fréquents"></a>

## Ressources : guides pas-à-pas, problèmes fréquents

Au vu de la complexité de la synchronisation iCal et du fait que des plateformes/calendriers tiers sont impliqués, la mise en place et le paramétrage de la synchronisation peuvent être complexes. Nous avons rédigé de nombreux articles dans notre base de connaissances afin de vous aider à établir les synchronisations avec chaque calendrier externe et afin de trouver des solutions aux problèmes fréquents:

- [Guides par plateforme - iCal](https://maestrel.atlassian.net/wiki/spaces/BC/pages/217808943/Guides+par+plateforme+-+iCal)
- [Troubleshooting - iCal](https://maestrel.atlassian.net/wiki/spaces/KB/pages/216629270/Troubleshooting+-+iCal)

N'hésitez pas à nous envoyer un message via notre page de contact que vous trouverez [ici](https://maestrel.com/contact-support/). Nous serons ravis de vous aider !