La maison
Le format de vos données.
Vos données vous appartiennent, et vous devez pouvoir les emporter ailleurs sans nous. Le règlement (UE) 2023/2854 (« Data Act ») demande à un fournisseur comme nous de tenir en ligne un registre à jour des structures et des formats dans lesquels vos données s’exportent (article 26). Le voici. Il décrit le service ; les engagements, eux, sont dans les conditions générales (§ 1, § 11 et § 12).
1La copie complète
La copie complète est un seul fichier JSON qui porte toutes les données d’un établissement pour un métier — la table, le séjour ou le rendez-vous. Le propriétaire du carnet la télécharge lui-même, à tout moment pendant le contrat : « Toutes les données (JSON) » dans les statistiques de la table et du séjour, « Télécharger toutes vos données (JSON) » dans les réglages du rendez-vous. À la fin du contrat, ou pendant une suspension pour défaut de paiement, le carnet est fermé : nous vous remettons alors la même copie sur demande écrite, dans les conditions des § 6 et § 12 des conditions générales.
Chaque téléchargement depuis le carnet — de la copie complète, ou de l’un de ses exports CSV (§ 6 ci-dessous) — est noté : quand, quoi, depuis quel compte. Il reste visible douze mois des administrateurs de votre espace, sur l’écran Équipe de convivos.be, et de notre équipe.
2L’enveloppe
Le fichier est un objet JSON, encodé en UTF-8, dont les clés de premier niveau sont toujours les mêmes :
- format
- la version du format : convivos-copie/1 aujourd’hui.
- module
- le métier copié : table, nuitee ou rendezvous.
- genereLe
- l’instant où la copie a été lue, en UTC (voir § 3).
- etablissement
- la fiche de l’établissement : nom, adresse de réservation, fuseau horaire, réglages du carnet.
- donnees
- les rubriques : chacune est un tableau de lignes, décrit au § 4.
- logo
- votre logo, s’il y en a un : un objet dont typeDeContenu donne le type (PNG, JPEG, WebP ou GIF), taille la taille en octets, empreinte son empreinte, et octets le fichier encodé en base64. Sinon, null.
- nonIncluses
- ce que la copie ne porte pas, et pourquoi, en toutes lettres (voir § 5).
Le fichier est lu en une seule fois : toutes les rubriques décrivent le même instant, sans qu’une réservation prise pendant la lecture n’y figure à moitié.
3Comment lire les valeurs
- Chaque ligne d’une rubrique est un objet dont les champs portent le nom qu’ils ont dans notre code, en anglais et en « camelCase » (par exemple startsAt, partySize). Une valeur absente vaut null.
- Les lignes ont un identifiant (id, un UUID), et les rubriques se relient par ces identifiants : une réservation porte l’identifiant du convive qui l’a prise. Trois rubriques de liaison n’en ont pas : une ligne de tablesAttribuees, de nuits ou de competences se reconnaît à la paire qu’elle relie (une réservation et une table, un séjour et sa date, un praticien et une prestation).
- Un instant — l’heure d’une réservation, d’une annulation, d’un paiement — est écrit en UTC, au format ISO 8601 : « 2026-09-30T18:30:00.000Z ». Pour l’afficher à l’heure locale, utilisez le fuseau de l’établissement (timezone).
- Une date civile — une nuitée, une fermeture — s’écrit « AAAA-MM-JJ », sans heure ni fuseau. Une heure d’horaire est à l’heure locale de l’établissement : « HH:MM:SS » pour les services de la table, « HH:MM » pour l’arrivée et le départ du séjour (checkInTime, checkOutTime), et, pour les praticiens du rendez-vous (startMinute, endMinute), des minutes depuis minuit : 540 vaut 9 h.
- Un jour de la semaine (weekday) est un entier de 0 (dimanche) à 6 (samedi). Au séjour, les jours d’arrivée et de départ permis d’un logement sont un masque de sept bits, le bit 0 pour le dimanche : 127 vaut tous les jours, 64 le samedi seul.
- Un montant est un nombre entier de centimes d’euro, dans un champ dont le nom contient Cents : 2500 vaut 25,00 €.
4Les rubriques
Chaque rubrique reprend une table de notre base, toutes ses lignes pour l’établissement, et tous ses champs hormis les secrets (§ 5) — sauf messages, un relevé dont la ligne dit les champs. Dans ce relevé, l’état sent — et sentAt, pour Table et Rendez-vous — dit que notre prestataire d’envoi a accepté le message, pas qu’il a été reçu ; et, pour Table et Rendez-vous, un message refait ou retiré après le déplacement d’une réservation n’y garde que sa dernière ligne, ou n’y figure plus. Les noms de rubriques sont des clés du fichier : ils ne se traduisent pas.
4.1Table
| Rubrique | Table d’origine | Ce qu’elle porte |
|---|---|---|
| services | service | les services récurrents : jour, heures, intervalle des créneaux, capacité. |
| fermetures | closure | les fermetures, capacités réduites et privatisations. |
| convives | customer | vos convives : nom, coordonnées, langue, absences, opposition au suivi des absences. |
| reservations | reservation | toutes les réservations : instant, couverts, statut, origine, notes, annulation. |
| tables | dining_table | les tables du plan de salle et leur place sur la grille. |
| tablesAttribuees | reservation_table | quelle réservation est posée sur quelle table. |
| paiements | reservation_payment | les acomptes payés en ligne : montant, état, remboursement — jamais un numéro de carte. |
| personnel | staff_user | les comptes du carnet créés avant le compte unique de convivos.be, s’il en reste — sans mot de passe. |
| sms | sms_usage | les rappels par SMS envoyés, mois par mois (mois, envoyes, plafond) : la base de la facture de l’option. |
| messages | email_outbox, sms_outbox (un relevé) | les e-mails et les SMS de vos réservations et du carnet : channel (email ou sms), réservation (reservationId, vide pour un message qui n’en concerne aucune), type, état (status), essais (attempts), posé, dernier changement et envoi (createdAt, updatedAt, sentAt) — ni destinataire ni contenu (§ 5). |
4.2Séjour
| Rubrique | Table d’origine | Ce qu’elle porte |
|---|---|---|
| logements | rentable_unit | vos chambres et logements : nom, capacité, prix de base. |
| tarifs | unit_rate_season | les périodes tarifaires de chaque logement. |
| voyageurs | guest | vos voyageurs : nom, coordonnées, langue. |
| blocages | unit_block | les logements fermés à la réservation, et pourquoi. |
| sejours | booking | tous les séjours : arrivée, départ, voyageurs, prix, taxe de séjour, arrhes, statut, notes. |
| nuits | booking_night | une ligne par nuit vendue, avec son prix figé à la réservation. |
| fluxIcal | ical_feed | les calendriers de plateformes branchés : leur nom et leur hôte (hote) — pas leur adresse complète (§ 5). |
| conflitsIcal | ical_import_conflict | les chevauchements relevés entre une plateforme et votre carnet. |
| paiements | payment | les arrhes payées en ligne : montant, état, remboursement — jamais un numéro de carte. |
| personnel | staff_user | les comptes du carnet créés avant le compte unique de convivos.be, s’il en reste — sans mot de passe. |
| messages | email_outbox (un relevé) | les e-mails de vos séjours et du carnet : channel (toujours email), séjour (bookingId, vide pour un message qui n’en concerne aucun), type, état (status), essais (attempts), posé et dernier changement (createdAt, updatedAt) — ni destinataire ni contenu (§ 5). |
4.3Rendez-vous
| Rubrique | Table d’origine | Ce qu’elle porte |
|---|---|---|
| praticiens | resource | les membres de l’équipe qui reçoivent des rendez-vous. |
| horaires | resource_hours | les heures de travail de chaque praticien. |
| prestations | service_offering | votre carte : durée, battement, prix, acompte, « chez le client », le véhicule demandé, et sa section (sectionId, et son nom dans category). |
| sections | service_section | les sections de votre carte, dans leur ordre. |
| competences | resource_service | qui sait faire quelle prestation. |
| conges | time_off | les absences et congés des praticiens. |
| clients | salon_client | les fiches de vos clients : nom, coordonnées, note de l’établissement, absences, opposition au suivi des absences — et la fiche commune des clients de passage. |
| rendezVous | appointment | tous les rendez-vous : instant, prestation, praticien, statut, adresse d’intervention, véhicule, notes de l’établissement et du client. |
| acomptes | appointment_payment | les acomptes payés en ligne : montant, état, remboursement — jamais un numéro de carte. |
| sms | sms_usage | les rappels par SMS envoyés, mois par mois (mois, envoyes, plafond) : la base de la facture de l’option. |
| messages | email_outbox, sms_outbox (un relevé) | les e-mails et les SMS de vos rendez-vous et du carnet : channel (email ou sms), rendez-vous (appointmentId, vide pour un message qui n’en concerne aucun), type, état (status), essais (attempts), posé, dernier changement et envoi (createdAt, updatedAt, sentAt) — ni destinataire ni contenu (§ 5). |
5Ce qui n’y figure pas, et pourquoi
Ce qui suit détaille les exclusions du § 12 des conditions générales :
- Les secrets, retirés par le nom de leur champ : jetons d’annulation et de gestion, empreintes, mots de passe, clés d’abonnement aux notifications, adresses de paiement encore ouvertes, clés d’idempotence. Ce ne sont pas des données : ce sont des moyens d’agir — annuler une réservation, rejouer une écriture, écrire à un appareil.
- La file d’envoi des e-mails et des SMS, la « file technique d’envoi des messages » que le § 12 des conditions générales exclut : ses destinataires, le contenu des messages et les réponses de notre prestataire d’envoi. Seul son relevé est repris (rubrique messages, § 4). La file efface un message terminé quatre-vingt-dix jours après son dernier changement — un SMS, au plus tard quatre-vingt-dix jours après avoir été posé — : le relevé ne porte que ce qu’elle garde encore.
- Les sessions et les abonnements aux notifications des appareils de votre personnel : des moyens d’accès.
- Pour le séjour, l’adresse complète d’un calendrier de plateforme : elle porte un jeton qui ouvre ce calendrier chez la plateforme. Vous l’avez chez elle ; la copie dit de laquelle il s’agit.
- Les comptes de votre équipe et leurs accès : ils vivent sur convivos.be, pas dans le carnet ; l’écran Équipe de votre espace les montre, mais ils ne font pas partie de la copie. Les données de votre compte et nos journaux sont décrits aux mentions légales (§ 4).
6Les fichiers CSV
À côté de la copie complète, le carnet exporte deux fichiers CSV, lisibles dans un tableur : vos clients, en entier, et vos réservations — les quatre-vingt-dix derniers jours et tout ce qui est à venir. Pour le rendez-vous, les notes de l’établissement n’y figurent pas : elles sont dans la copie complète et dans le fichier de chaque client.
- séparateur « ; », encodage UTF-8 avec sa marque d’ordre d’octets (BOM), lignes terminées par CRLF — ce qu’un tableur réglé en français ouvre sans conversion ;
- la première ligne nomme les colonnes ; une valeur qui contient le séparateur, un guillemet ou un retour à la ligne est entre guillemets ;
- une valeur qui commence par « = », « + », « - » ou « @ » est précédée d’une apostrophe, pour qu’un tableur ne l’exécute jamais comme une formule ; c’est pourquoi un téléphone s’y écrit avec « 00 » plutôt qu’avec « + » ;
- les dates et les heures y sont à l’heure locale de l’établissement.
7Un format qui ne change pas sans le dire
Un ajout — une rubrique, un champ — laisse le numéro de version inchangé : un programme qui lit la version 1 continue de la lire. Si un champ disparaît, change de nom ou de sens, le numéro change, et cette page le décrit. Nos tests figent la liste des champs de chaque rubrique : aucun ne change sans que sa version soit décidée.