h1. Réservation d'un créneau

La réservation d'un créneau s'effectue par un appel à l’adresse @/api/agenda/SLUG-DE-LAGENDA/fillslot/IDENTIFIANT-DU-CRENEAU/@ via la méthode @HTTP POST@.

Cette procédure est commune aux agendas de type rendez-vous et évènement, seul le format de l'identifiant du créneau diffère.

Cette adresse est mentionnée dans le champ @fillslot_url@ obtenu en demandant la [[Obtenir_les_créneaux_d’un_agenda#Exemple|liste des créneaux disponibles]], ce qui évite la plupart du temps d'avoir à la construire manuellement.

h3. Paramètres JSON, corps de la requête

La plupart des paramètres sont communs aux deux types d’agenda.

| Nom | Description | Exemple |
| backoffice_url | URL de la démarche effectuant la réservation | {{form_url_backoffice}} |
| form_url | URL de la demande | {{form_url}} |
| cancel_callback_url | URL à appeler lors d’une annulation |     |
| cancel_booking_id | Identifiant de réservation à annuler | 45  |
| count | Nombre de places à réserver | 2   |
| label | Texte arbitraire pour l’affichage en backoffice | {{form_name<notextile>|</notextile>safe}} |
| user_display_label | Texte pour affichage dans export ics | {{form_name<notextile>|</notextile>safe}} |
| user_name | Nom complet l’utilisateur (peut être décomposé et remplacé par user_first_name et user_last_name) | {{form_user_display_name}} |
| user_first_name | Prénom de l’utilisateur | {{form_user_var_first_name}} |
| user_last_name | Nom de l’utilisateur | {{form_user_var_last_name}} |
| user_email | Adresse de courriel de l’utilisateur | {{form_user_email}} |
| user_phone_number | Numéro de téléphone de l’utilisateur | {{form_user_var_phone}} |
| user_external_id | Identifiant unique de l’utilisateur | {{form_user_nameid}} |
| exclude_user | Interdire à l’utilisateur d’avoir plusieurs réservations en même temps | true (false par défaut) |
| bypass_delays |  Ne pas prendre en compte les délais de réservation | true (false par défaut) |
| extra_emails | Adresses de courriel supplémentaires où envoyer un rappel | {{form_var_emails_raw}} ou "a@example.com,b@example.com" |
| extra_phone_numbers | Numéros de téléphone supplémentaires où envoyer un rappel  | {{form_var_numbers_raw}} ou "+33122334455,+33122334466" |
| absence_callback_url | URL à appeler lorsque l’événement est marqué comme pointé, en cas d’absence |  |
| presence_callback_url | URL à appeler lorsque l’événement est marqué comme pointé, en cas de présence |  |

Il est possible de passer n’importe quel paramètre en plus de ceux ci-dessus : ils seront enregistrés et apparaîtront dans la clé @extra_data@ de l’API qui retourne les [[Gestion_des_réservations#Exemple-2|informations d’une réservation]].

Les appels à absence_callback_url et presence_callback_url se feront en POSTant un objet avec les clés user_was_present (booléen), user_check_type_slug (identifiant du motif d’absence), user_check_type_label (libellé du motif d’absence).

Le cancel_booking_id permet de combiner l’annulation d’un créneau et la réservation d’un nouveau (par exemple sur un agenda différent).

h2. Agenda évènement

Certains paramètres supplémentaires peuvent être inclus :

| Nom | Description | Exemple |
| events | Restreindre la réservation aux évènements passés ou futurs ("future" par défaut) | "future", "past", "all" |
| force_waiting_list | Forcer le passage en liste d’attente | true |

h3. Exemple

<pre>
POST /api/agenda/foo-bar/fillslot/event-slug/

{
    "agenda": {
	"label": "Foo bar",
	"slug": "foo-bar"
     },
     "api": {
	 "accept_url": "http://chrono.dev.publik.love/api/booking/8/accept/",
	 "anonymize_url": "http://chrono.dev.publik.love/api/booking/8/anonymize/",
	 "booking_url": "http://chrono.dev.publik.love/api/booking/8/",
	 "cancel_url": "http://chrono.dev.publik.love/api/booking/8/cancel/",
	 "ics_url": "http://chrono.dev.publik.love/api/booking/8/ics/",
	 "suspend_url": "http://chrono.dev.publik.love/api/booking/8/suspend/"
      },
     "booking_id": 8,
     "datetime": "2017-05-21 17:00:00",
     "end_datetime": null,
     "err": 0,
     "in_waiting_list": False,
     "places": {
	  "available": 19,
	  "full": False,
	  "has_waiting_list": False,
	  "reserved": 1,
	  "total": 20
     }
}
</pre>


h2. Agenda rendez-vous

Certains paramètres supplémentaires peuvent être inclus :

| Nom | Description | Exemple |
| use_color_for | Libellé auquel associer la couleur d’un rendez-vous dans le backoffice |    |

h3. Exemple

<pre>
POST /api/agenda/rdv-pref/fillslot/18:2020-06-16-1000/

{
    "agenda": {
        "label": "rdv pref",
        "slug": "rdv-pref"
    },
    "api": {
        "anonymize_url": "https://chrono.dev.publik.love/api/booking/50/anonymize/",
        "cancel_url": "https://chrono.dev.publik.love/api/booking/50/cancel/",
        "ics_url": "https://chrono.dev.publik.love/api/booking/50/ics/",
        "suspend_url": "https://chrono.dev.publik.love/api/booking/50/suspend/"
    },
    "booking_id": 50,
    "datetime": "2020-06-16 10:00:00",
    "desk": {
        "label": "ds",
        "slug": "ds"
    },
    "duration": 30,
    "end_datetime": "2020-06-16 10:30:00",
    "err": 0,
    "in_waiting_list": false,
    "resources": []
}
</pre>


h2. Agenda évènement : poser plusieurs réservations

Il est possible de réserver plusieurs évènements en une seule fois via un appel @POST@ à l’adresse @/api/agenda/SLUG-DE-LAGENDA/events/fillslots/@.

h3. Paramètres JSON, corps de la requête

Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.

| Nom | Description | Exemple |
| user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
| slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | {{form_var_event_raw<notextile>|</notextile>join:","}} |

h3. Exemple

<pre>
POST /api/agenda/foo-bar/events/fillslots/

{
     "err": 0,
     "booking_count": 3,
     "waiting_list_events": [
	 {
	    "id": "event-slug",
	    "slug": "event-slug",
	    ...
	 }
     ],
     "cancelled_booking_count": 0
}
</pre>


h2. Agenda évènement : poser plusieurs réservations sur plusieurs agendas

Il est possible de réserver plusieurs évènements qui se trouvent sur des agendas différents via un appel @HTTP POST@ à l’adresse @/api/agendas/events/fillslots/@.

h3. Paramètres de l’URL

| Nom | Description | Exemple |
| agendas | Slugs des agendas concernés par l’appel. Ils permettent de savoir quelles réservations mettre à jour. | agenda-slug,agenda2-slug,agenda3-slug |

h3. Paramètres JSON, corps de la requête

Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.

| Nom | Description | Exemple |
| user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
| slots | Slugs des évènements à réserver. Une valeur vide aura pour effet d’annuler les réservations de l’utilisateur. | agenda-slug@event-slug,agenda2-slug@event-slug |

h3. Exemple

<pre>
POST /api/agendas/events/fillslots/?agendas=agenda-slug

{
     "err": 0,
     "booking_count": 3,
     "waiting_list_events": [
	 {
	    "id": "event-slug",
	    "slug": "event-slug",
	    ...
	 }
     ],
     "cancelled_booking_count": 0
}
</pre>


h2. Agenda évènement : réserver toutes les occurrences d’évènements récurrents

Il est possible de réserver un ou plusieurs évènements récurrents, en totalité ou sur une plage temporelle définie, via un appel @POST@ à l’adresse @/api/agendas/recurring-events/fillslots/@.

h3. Paramètres de l’URL

| Nom | Description | Exemple |
| agendas | Slugs des agendas concernés par l’appel. | agenda-slug,agenda2-slug,agenda3-slug |
| action | Action à réaliser sur les évènements. | @update@, @book@ ou @unbook@ |
| date_start | Réserver seulement les évènements commençant après cette date. | 2021-09-04 |
| date_end | Réserver seulement les évènements commençant avant cette date. | 2022-06-21 |

h3. Paramètres JSON, corps de la requête

Par rapport à l’appel classique de réservation d’un évènement, deux paramètres doivent obligatoirement être présents.

| Nom | Description | Exemple |
| user_external_id | Identifiant unique de l’utilisateur. Grâce à cet identifiant, chaque appel aura pour effet de mettre à jour les réservations. | {{form_user_nameid}} |
| slots | Slugs et jours des évènements à réserver. | agenda-slug@event-slug:0,agenda-slug@event2-slug:1 pour réserver le premier évènement tous les lundis et le second tous les mardis. |

h3. Exemple

<pre>
POST /api/agendas/recurring-events/fillslots/?agendas=agenda-slug

{
     "err": 0,
     "booking_count": 142,
     "full_events": [
	 {
	    "id": "event-slug",
	    "slug": "event-slug",
	    ...
	 }
     ],
     "cancelled_booking_count": 0
}
</pre>