Vevent API

Les vevents (ou « Évènements ») sont de plusieurs types :

1 – Les RDV :

Les RDV sont obligatoirement associés à un objet de type « Fiche » via l'attribut fiche_id et à un objet de type « Intervention » via l'attribut intervention_id.

Important Il ne peuvent pas être répétés !

2 – Les Plages :

Les plages sont de simples évènements texte (ex: "Pause déjeuner").

Important Pour créer une plage, il faut que les attributs intervention_id et fiche_id soient à la valeur 0.

3 – Les Disponibilités Internet :

Les disponibilités sont des plages d'ouverture à Internet, c.à.d que les disponibilités proposées sur l'Interface de prise de RDV par Internet sont basées sur ces plages.

Important L'attribut type doit valoir VfreebusyEvent.

4 - Les Notes :

Les Notes sont des évènements ayant lieu un jour particulier mais ne bloquant pas de temps sur les agendas.

  • Ils doivent posséder l'attribut note à 1.

  • Les attributs start et end doivent tous les deux valoir minuit pour le jour de la note (ex: start = end = "2010-01-22 00:00:00"), la durée de la note peut donc être considérée comme nulle.

Liste de tous les vevents sur un groupe

GET /api/v1/groups/:group_id/vevents
Note Puisque la requête ne précise pas un agenda en particulier, les vevents renvoyés pourront appartenir à n'importe quel agenda du groupe d'id :group_id.

Liste des vevents sur un agenda en particulier

GET /api/v1/groups/:group_id/vevents?calendar_id=:calendar_id

Création d'un vevent

POST /api/v1/groups/:group_id/vevents

Modification d'un vevent

PUT /api/v1/groups/:group_id/vevents/:id

Suppression d'un vevent

DELETE /api/v1/groups/:group_id/vevents/:id

Important Cette opération ne supprime pas complètement le vevent ! Elle passe l'attribut deleted à true. Le vevent peut ainsi être restauré plus tard.

Liste des RDV d'une fiche

Les vevents liés à une fiche sont nécessairement des RDV :

GET /api/v1/groups/:group_id/vevents?fiche_id=:fiche_id

Champs standards

Ces champs sont communs aux 4 types de Vevents.

Champ Type Description
calendar_id integer (obligatoire) ID de l'objet de type «Calendar» auquel il est lié
start datetime Date et heure de début de l’événement ( ex: 2010-01-22 15:00:00 ). Pour un événement récurrent, il s'agit de la première occurrence.
end datetime Date et heure de la fin de l’événement ( ex: 2010-01-22 15:15:00 ). Pour un événement récurrent, il s'agit de la première occurrence.
taker string(255) Nom / Prénom de la personne ayant crée le Vevent. Soit un professionnel ayant un accès à l'Interface Pro, soit un utilisateur de l'Interface de prise de RDV par Internet.
colorref string(7) Code couleur de l’événement telle que visible sur l'Interface Pro, au format hexadécimal #RRGGBB (exemple: #FF6600)
text text Texte de l’événement. Dans le cas d’un RDV, le texte contiendra les noms et prénoms de l'objet de type « Fiche » lié.
deleted boolean Indique si un Vevent est supprimé (0 par défaut)

Champs liés au cas où le Vevent est de type « RDV »

Champ Type Description
intervention_id integer ID de l'objet de type «Intervention» auquel il est lié
fiche_id integer ID de l'objet de type «Fiche» auquel il est lié
state integer Indique le statut du RDV, parmi les valeurs suivantes :
  • 0 (aucune valeur) - valeur par défaut
  • 1 (venu)
  • 2 (pas venu)
  • 3 (en attente)
mailtime datetime Date et Heure à laquelle l’email de rappel doit être envoyé.
smstime datetime Date et Heure à laquelle le SMS de rappel doit être envoyé Important Le SMS ne sera envoyé que si l'attribut « smsreminder » du même Vevent est égal à 1, et si le Groupe concerné par ce Vevent est paramétré pour l'envoi de SMS (smsreminder != 0).
smsreminder boolean Envoyer un SMS de rappel pour ce RDV (0 par défaut)
from_web boolean Indique si le RDV à été noté depuis l'Interface de prise de RDV par Internet. (0 par défaut)
comments text Commentaire lié au RDV

Champs personnalisés des RDV

Voir page : Customfields API

Champs liés au cas où le Vevent est de type « Disponibilité Internet »

Champ Type Description
availableInterventions text Liste des ID des objets de type « intervention » séparés par des virgules. Ces Interventions seront disponibles à la prise de RDV par Internet, les autres n'apparaitront pas sur l'Interface de prise de RDV Internet pour ce Vevent spécifiquement. Si cette liste est vide (NULL ou chaîne de caractère vide), toutes les interventions seront proposées (exemple : ",23,343,") (NULL par défaut).
type string(20) Important Doit valoir « VfreebusyEvent » dans ce cas uniquement, sinon il doit être vide (Vide par défaut)

Champs liés au cas où le Vevent est de type « Note »

Champ Type Description
note boolean Indique si cet événement est une note journée. Important start et end doivent tous les deux valoir minuit pour le jour de la note (ex: start : 2010-01-22 00:00:00) (0 par défaut)

Répétition des Vevents

Important Les Vevent de type « RDV » ne peuvent pas être répétés !

Les Vevents de type « Plage », « Disponibilité Internet », et « Note », peuvent être répétés pour plus de commodité, par exemple pour éviter de devoir noter tous les jours une plage horaire symbolisant l'heure de la pause déjeuner.

Une règle de répétition est paramétrée à l'aide de l'attribut rrule, dont le fonctionnement est défini par le champ RRULE du standard iCalendar. Nous ne gérons néanmoins pas tous les motifs de répétition du standard (seulement les répétitions quotidiennes, hebdomadaires, mensuelles et annuelles).

Les exceptions à la règle de répétition sont définies par l'attribut repeat_exceptions.

Champs liés aux répétitions

Important Les champs repeat_freq, repeat_intervall, repeat_count et repeat_byday sont obsolètes et ne doivent plus être utilisés (voir Annexe ancien format de répétition).

Champ Type Description
rrule text Définit le motif de répétition (fréquence, durée, etc.), à partir d'une ou plusieurs clés et valeurs dans la liste suivante :
  • FREQ (obligatoire) : valeur parmi "DAILY", "WEEKLY", "MONTHLY", "YEARLY"
  • INTERVAL : entier supérieur ou égal à 1
  • COUNT : entier supérieur ou égal à 2
  • UNTIL : date au format YYYYmmddTHHMMSSZ, exprimée dans le fuseau horaire UTC (GMT+0).
  • BYDAY :
    • si FREQ=WEEKLY : valeur parmi "MO", "TU", "WE", "TH", "SA", "SU" ou combinaison de jours séparés par des virgules (ex: "MO,TU,WE,TH,FR")
    • si FREQ=MONTHLY : valeur composée d'un entier compris entre -5 et 5 et d'un jour de la semaine (ex: "1FR", "2MO" ou "-1WE")
Chaque clé et sa valeur sont associés avec le signe "égal" = et chaque paire clé/valeur est séparée des autres par un point-virgule ; (ex: FREQ=WEEKLY;INTERVAL=2;BYDAY=TU,TH).

Voir exemples de répétitions.
repeat_exceptions text Liste de dates séparées par des virgules, au format YYYY-mm-dd 00:00:00, qui seront exclues du motif de répétition. L'événement ne sera donc pas répété ces jours-ci.
(ex : "2016-03-22 00:00:00,2016-03-23 00:00:00")
repeat_until datetime Date de fin de répétition (convertie dans le fuseau horaire du groupe)
Important le champ repeat_until est disponible en lecture seule, il est automatiquement calculé à partir de la valeur de la clé UNTIL dans le champ rrule, si présente.

Exemples de répétitions

1 Répétition tous les 2 jours, sans limite 

  rrule = "FREQ=DAILY;INTERVAL=2"

On choisit :

  • la fréquence de répétition avec la clé FREQ, ici "DAILY" (= répétition quotidienne)
  • l'intervalle de répétition avec la clé INTERVAL, ici 2 (= tous les 2 jours)


2 Répétition toutes les semaines, les lundi et mercredi, 5 fois 

  rrule = "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,WE;COUNT=5"

Dans cet exemple, si on suppose de plus que start = "2016-01-18 10:00:00" (début d'événement le lundi 18 janvier 2016 à 10h), l'événement sera également répété à 10h les mercredi 20 janvier 2016, lundi 25 janvier 2016, mercredi 27 janvier 2016 et lundi 1er février 2016 (on a bien 5 occurrences en tout en comptant l'événement d'origine).

On choisit :

  • la fréquence de répétition avec la clé FREQ, ici "WEEKLY"
  • l'intervalle de répétition avec la clé INTERVAL, ici 1 (= toutes les semaines)
  • les jours de la semaine à répéter avec la clé BYDAY (valeurs possibles du lundi au dimanche : "MO", "TU", "WE", "TH", "FR", "SA", "SU"). Il est également possible de répéter plusieurs jours de la semaine, en les séparant par des virgules (ex : BYDAY=MO,WE pour une répétition les lundi et mercredi).
  • le nombre d'occurrences avec la clé COUNT (entier >= 2)
    Important l'événement d'origine compte comme une occurrence (donc "COUNT=2" correspond à l'événement d'origine + 1 répétition).


3 Répétition tous les 3 mois, le 10 du mois, jusqu'au 10 février 2017 (inclus)

On suppose ici que start = "2016-02-10 16:00:00" et end = "2016-02-10 18:00:00", et de plus que le groupe a un fuseau horaire configuré sur timezone = "Paris".

Alors, rrule s'écrit :

  rrule = "FREQ=MONTHLY;INTERVAL=3;UNTIL=20170201T170000Z"

Dans cet exemple, l'événement du 10 février 2016 sera ainsi répété les 10 mai 2016, 10 août 2016, 10 novembre 2016, et 10 février 2017.

On choisit :

  • la fréquence de répétition avec la clé FREQ, ici "MONTHLY"
  • l'intervalle de répétition avec la clé INTERVAL, ici 3 (= tous les 3 mois)
  • la date et heure de fin de répétition avec la clé UNTIL, qui est au format YYYYmmddTHHMMSSZ, dans la timezone UTC. Ici nous avons "20170210T170000Z" qui doit se lire : année 2017, mois 02 (= février), jour 10 (= 10ème jour du mois), à 17h (dans le fuseau UTC). En effet, l'heure de fin du dernier événement répété étant 18h dans le fuseau horaire "Paris" (GMT+1 en heure d'hiver), cela correspond à 17h dans le fuseau UTC. Ainsi nous indiquons bien que le motif de répétition prend fin le 10 février 2017 à 18h dans le fuseau horaire "Paris", après la dernière répétition de l'événement ayant eu lieu ce jour.


Important Dans ce mode, le Vevent doit commencer à une date antérieure à la valeur de UNTIL.

Important Les clés COUNT et UNTIL sont exclusives, on ne peut utiliser qu'une seule de ces clés à la fois.


4 Répétition le 2ème mardi de chaque mois 

  rrule = "FREQ=MONTHLY;INTERVAL=1;BYDAY=2TU"

Si, de plus, on suppose que l'événement commence le mardi 9 février 2016 à 9h30 (start = "2016-02-09 09:30:00"), alors l'événement sera répété à 9h30 les mardi 8 mars 2016, mardi 12 avril 2016, mardi 10 mai 2016, etc.

On choisit :

  • la fréquence de répétition avec la clé FREQ, ici "MONTHLY"
  • l'intervalle de répétition avec la clé INTERVAL, ici 1 (= tous les mois)
  • le motif de répétition avec la clé BYDAY, ici "2TU" qui doit se lire "2ème mardi du mois". De même, "1MO" siginifie "premier lundi du mois", "3WE" siginifie "troisième mercredi du mois", et "-1FR" signifie "dernier vendredi du mois".


5 Répétition annuelle le 21 juin, sauf le 21 juin 2018 

  rrule = "FREQ=YEARLY;INTERVAL=1"
  repeat_exceptions = "2018-06-21 00:00:00"

Si, de plus, on suppose que l'événement commence le mardi 21 juin 2016 à 19h (start = "2016-06-21 19:00:00"), alors l'événement sera répété à 19h les 21 juin 2017, 21 juin 2019, 21 juin 2020, etc.

On choisit :

  • la fréquence de répétition avec la clé FREQ, ici "YEARLY"
  • l'intervalle de répétition avec la clé INTERVAL, ici 1 (= tous les ans)

On présice :

  • les exceptions dans le champ repeat_exceptions, au format YYYY-mm-dd 00:00:00
  • si plusieurs exceptions sont ajoutées dans le champ repeat_exceptions, il faut séparer les valeurs par des virgules, par exemple : repeat_exceptions = "2018-06-21 00:00:00,2019-06-21 00:00:00"


Annexe ancien format de répétition

Important Les champs repeat_freq, repeat_intervall, repeat_count et repeat_byday décris ci-dessous sont obsolètes et ne doivent plus être utilisés.

Méthode de conversion vers le nouveau format

Par exemple, la répétition suivante dans l'ancien format : 

  start = "2016-02-01 08:00:00"
  end   = "2016-02-01 09:00:00"
  repeat_freq = "weekly"
  repeat_intervall = 2
  repeat_until = "2016-06-01 09:00:00"
  repeat_byday = 62

devra désormais être envoyée au nouveau format : 

  start = "2016-02-01 08:00:00"
  end   = "2016-02-01 09:00:00"
  rrule = "FREQ=WEEKLY;INTERVAL=2;BYDAY=MO,TU,WE,TH,FR;UNTIL=20160601T070000Z"

Comment convertir la valeur de repeat_byday dans le nouveau format BYDAY ?

Il faut interpréter repeat_byday comme un nombre binaire et relever les jours de la semaine qui correspondent à la valeur 1. Par exemple, la valeur repeat_byday = 62 se lit en binaire 0111110 :

SA FR TH WE TU MO SU
Samedi Vendredi Jeudi Mercredi Mardi Lundi Dimanche
0 1 1 1 1 1 0

On relève alors dans le tableau (de droite à gauche), les jours suivants : BYDAY=MO,TU,WE,TH,FR.