Rendez-vous #

L’API Appointments vous permet de réserver des rendez-vous pour vos contacts sur vos types d’événements, puis de les récupérer, de les lister, de les mettre à jour, de les annuler ou de les supprimer. Elle répond également à la question qui se pose en premier dans la plupart des flux de réservation — quels créneaux sont réellement libres — et couvre le volet calendrier : lister les agendas Google que vous avez connectés et importer les événements qui y figurent déjà. Lorsqu’une connexion Google Calendar est active, l’événement de calendrier correspondant est créé et maintenu synchronisé automatiquement en arrière-plan. Les restaurants utilisant Zenchef, Formitable, OpenTable ou TheFork pour leur propre système de réservation peuvent également être vérifiés et connectés ici, afin que l’agent IA réserve de vraies tables au lieu de rendez-vous internes — et les entreprises de services sur rendez-vous gérant leur planning dans Trafft peuvent se connecter de la même manière.

Tous les chemins sur cette page sont relatifs à l’URL de base https://api.youraiconnector.com/v1. Chaque requête nécessite votre clé API — consultez Authentification pour obtenir la liste complète des méthodes pour l’envoyer. Les exemples ci-dessous utilisent l’en-tête X-API-Key, avec un exemple cURL montrant également le formulaire de requête ?apiKey=.

Événements vs rendez-vous : Un type d’événement est une définition de créneau réservable (le type de réunion, sa durée, ses salles). Un rendez-vous est une instance réservée d’un type d’événement pour un contact spécifique. Vous réservez un rendez-vous en référençant le contact et le type d’événement.

L’objet rendez-vous #

Chaque point de terminaison qui renvoie un rendez-vous utilise la même structure :

À propos de la synchronisation du calendrier : Juste après avoir réservé ou modifié un rendez-vous, google_calendar_event_id peut encore être null et calendar_synced peut être false car la synchronisation s’exécute en arrière-plan un instant plus tard. Récupérez à nouveau le rendez-vous peu après pour voir les champs de calendrier renseignés.

Trouver les créneaux disponibles #

GET /appointments/available-slots

Renvoie les heures réellement libres pour un type d’événement donné entre deux moments. Il s’agit normalement du premier appel dans un flux de réservation : affichez ces créneaux, laissez la personne en choisir un, puis envoyez l’heure choisie à Réserver un rendez-vous.

La réponse prend déjà en compte les heures d’ouverture et la durée des créneaux du type d’événement, ses salles, les rendez-vous que vous avez déjà réservés, ainsi que tout ce qui est bloqué sur les agendas Google connectés — un créneau renvoyé ici est donc un créneau que vous pouvez réserver.

Les résultats sont renvoyés regroupés par jour — et, lorsque le type d’événement utilise des salles, un groupe par salle et par jour :

Chaque entrée dans available_slots contient :

Les heures sont locales au type d’événement, et non en UTC. date, start_time et end_time sont des valeurs d’horloge dans le fuseau horaire propre au type d’événement (son remplacement, ou le fuseau horaire de votre compte s’il n’en a pas). Réserver un rendez-vous attend un instant UTC ISO 8601, convertissez donc le créneau que vous avez choisi avant de l’envoyer.

cURL

curl "https://api.youraiconnector.com/v1/appointments/available-slots?event_id=event_xyz789&start_time=2026-06-15T00:00:00.000Z&end_time=2026-06-19T00:00:00.000Z" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  event_id: "event_xyz789",
  start_time: "2026-06-15T00:00:00.000Z",
  end_time: "2026-06-19T00:00:00.000Z",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments/available-slots?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/available-slots",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T00:00:00.000Z",
        "end_time": "2026-06-19T00:00:00.000Z",
    },
)
print(res.json()["data"])

Réponse (200 OK) :

{
  "success": true,
  "data": [
    {
      "date": "15/06/2026",
      "day": "monday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "10:00", "end_time": "10:30", "available": true },
        { "start_time": "10:30", "end_time": "11:00", "available": true }
      ]
    },
    {
      "date": "16/06/2026",
      "day": "tuesday",
      "room_name": "Room A",
      "available_slots": [
        { "start_time": "09:00", "end_time": "09:30", "available": true, "spots_left": 2 }
      ]
    }
  ]
}

Un jour sans aucune disponibilité n’apparaît tout simplement pas. L’absence de event_id, start_time ou end_time renvoie 400 ; un type d’événement qui n’est pas sur votre compte renvoie 404.

Réserver un rendez-vous #

POST /appointments

Crée un rendez-vous pour l’un de vos contacts. Il existe deux façons de l’utiliser :

• Sur l’un de vos types d’événement — envoyez event_id, et la réservation fonctionne exactement comme d’habitude : la disponibilité et la capacité sont respectées, l’heure de fin est calculée à partir de la durée du créneau du type d’événement, et le rendez-vous est synchronisé avec votre Google Calendar lorsqu’il est connecté.
• En tant que réservation externe — omettez event_id et envoyez un title à la place. Cela enregistre une réservation effectuée ailleurs (votre propre CRM, un emploi du temps de cours, un autre outil de réservation) afin qu’elle apparaisse sur la page Rendez-vous avec les autres.

Une réservation pour un type d’événement avec salles doit être effectuée à une heure proposée par Trouver des créneaux disponibles : pendant les heures d’ouverture de la salle, en dehors du délai de préavis, dans la limite de la période de réservation autorisée pour le type d’événement, sur la grille des créneaux, pas dans le passé, et non bloquée sur un calendrier connecté. Toute autre heure est refusée avec une 400 et rien n’est créé. Il en va de même pour une room_name qui ne correspond à aucune des salles du type d’événement (le message liste les noms valides). Les temps de battement définis sur le type d’événement (Battement avant et Battement après dans l’éditeur de type d’événement, buffer_before et buffer_after en minutes) sont maintenus libres autour de chaque réservation.

Une réservation sur un type d’événement fait également l’objet d’une vérification de conflit : si le créneau est déjà complet, la demande échoue avec une 409 et rien n’est créé. Une réservation externe n’est associée à aucun type d’événement, donc rien n’est vérifié par rapport à votre disponibilité ou votre capacité et rien n’est synchronisé avec un calendrier.

Il est sûr de réessayer. Si le même contact a déjà une réservation confirmée sur le même type d’événement au même début (dans la même salle, lorsque vous en nommez une), par exemple parce que votre première demande a expiré après avoir été traitée, vous récupérez cette réservation avec une 200 et "replayed": true au lieu d’une seconde réservation ou d’une 409.

Un external_reference fonctionne comme une clé d’idempotence. Il est unique sur votre compte : si un rendez-vous porte déjà la référence que vous envoyez, ce rendez-vous est renvoyé avec un 200 et un "replayed": true et rien de nouveau n’est créé, même si la nouvelle tentative indique une heure ou un contact différent et quel que soit le statut de ce rendez-vous. Utilisez-le pour les réservations payantes (envoyez votre ID de paiement ou de commande), et envoyez une nouvelle référence pour une réservation réellement nouvelle.

Envoyez event_id et title ensemble, ou aucun des deux, et la requête renvoie une 400 — tout comme l’envoi simultané de end_time et duration_minutes.

cURL (utilisant le formulaire de requête ?apiKey=)

curl -X POST "https://api.youraiconnector.com/v1/appointments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "start_time": "2026-06-15T10:00:00.000Z",
    "room_name": "Room A"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    event_id: "event_xyz789",
    start_time: "2026-06-15T10:00:00.000Z",
    room_name: "Room A",
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "event_id": "event_xyz789",
        "start_time": "2026-06-15T10:00:00.000Z",
        "room_name": "Room A",
    },
)
print(res.json()["appointment_id"])

Réponse (201 Created) :

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Enregistrement d’une réservation effectuée ailleurs #

Même point de terminaison, sans type d’événement : un title et un start_time suffisent, et duration_minutes définit la durée de la réservation.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "title": "Beginner guitar class",
    "start_time": "2026-06-15T10:00:00.000Z",
    "duration_minutes": 90,
    "external_reference": "class-slot-4812"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contact_id: "contact_abc123",
    title: "Beginner guitar class",
    start_time: "2026-06-15T10:00:00.000Z",
    duration_minutes: 90,
  }),
});
const data = await res.json();
console.log(data.appointment_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "contact_id": "contact_abc123",
        "title": "Beginner guitar class",
        "start_time": "2026-06-15T10:00:00.000Z",
        "duration_minutes": 90,
    },
)
print(res.json()["appointment_id"])

Réponse (201 Created) :

{
  "success": true,
  "appointment_id": "eFgH5678aBcD1234",
  "appointment": {
    "id": "eFgH5678aBcD1234",
    "contact_id": "contact_abc123",
    "event_id": null,
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T11:30:00.000Z",
    "created_at": "2026-06-10T09:00:00.000Z",
    "last_modified_at": "2026-06-10T09:00:00.000Z",
    "summary": "Beginner guitar class",
    "google_calendar_event_id": null,
    "calendar_synced": false
  }
}

Les réservations externes sont ensuite des rendez-vous ordinaires : ils apparaissent sur la page Rendez-vous et dans Lister les rendez-vous, ils peuvent être reprogrammés, annulés ou supprimés dans l’application ou via cette API, l’e-mail de notification de réservation est envoyé comme d’habitude, et le déclencheur d’automatisation Rendez-vous réservé ainsi que le webhook se déclenchent pour eux comme pour toute autre réservation effectuée via l’API. Les seules différences sont celles mentionnées ci-dessus — aucune vérification de disponibilité ou de capacité, aucune synchronisation de calendrier, et event_id reste null.

Obtenir un rendez-vous #

GET /appointments/{appointmentId}

Renvoie un rendez-vous unique par son ID, y compris son état de synchronisation avec le calendrier.

cURL

curl "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["appointment"])

Réponse (200 OK) :

{
  "success": true,
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-15T10:00:00.000Z",
    "end_time": "2026-06-15T10:30:00.000Z",
    "room_name": "Room A",
    "google_calendar_event_id": "abc123googleevent",
    "calendar_synced": true
  }
}

Lister les rendez-vous #

GET /appointments

Liste les rendez-vous de votre compte, du plus récent au plus ancien, avec une pagination basée sur un curseur.

Quelques règles à garder à l’esprit :

• Sans filtres, vous obtenez tous les rendez-vous du compte, page par page.
• Par contact — définissez contact_id pour voir les rendez-vous confirmés d’un seul contact. Vous pouvez restreindre cela à une seule journée en transmettant également date.
• Par statut — définissez status (sans contact_id) pour lister uniquement les rendez-vous Confirmed ou uniquement Canceled sur l’ensemble du compte.
• Le filtre date sans contact_id, ou status=Canceled avec contact_id, renvoie une 400.

cURL

curl "https://api.youraiconnector.com/v1/appointments?contact_id=contact_abc123&date=2026-06-15" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  contact_id: "contact_abc123",
  date: "2026-06-15",
});
const res = await fetch(
  `https://api.youraiconnector.com/v1/appointments?${params}`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.appointments, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"contact_id": "contact_abc123", "date": "2026-06-15"},
)
data = res.json()
print(data["appointments"], data["next_cursor"])

Réponse (200 OK) :

{
  "success": true,
  "appointments": [
    {
      "id": "aBcD1234eFgH5678",
      "contact_id": "contact_abc123",
      "event_id": "event_xyz789",
      "status": "Confirmed",
      "start_time": "2026-06-15T10:00:00.000Z",
      "end_time": "2026-06-15T10:30:00.000Z",
      "calendar_synced": true
    }
  ],
  "next_cursor": null
}

Pour parcourir les résultats, transmettez le next_cursor d’une réponse en tant que cursor de la requête suivante. Continuez jusqu’à ce que next_cursor soit null. Consultez Erreurs et pagination pour le modèle de pagination partagé.

Mettre à jour un rendez-vous #

PUT /appointments/{appointmentId}

Reprogrammez un rendez-vous ou modifiez ses détails. Envoyez uniquement les champs que vous souhaitez modifier — au moins un est requis. La combinaison du début et de la fin doit rester dans l’ordre chronologique (end_time doit être après start_time). Les modifications sont automatiquement synchronisées avec l’événement du calendrier lié.

Le déplacement d’une réservation confirmée sur un type d’événement (un nouveau start_time ou room_name) fait l’objet d’une vérification de conflit comme pour une nouvelle réservation : un créneau déjà complet répond 409 et rien ne change, et une room_name qui ne correspond à aucune des salles du type d’événement répond 400. Envoyez uniquement start_time et la réservation conserve sa durée. Vos propres heures d’ouverture et période de préavis ne sont pas appliquées ici, vous pouvez donc toujours déplacer une réservation à n’importe quel moment libre.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      start_time: "2026-06-16T10:00:00.000Z",
      end_time: "2026-06-16T10:30:00.000Z",
    }),
  }
);
const data = await res.json();
console.log(data.appointment);

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "start_time": "2026-06-16T10:00:00.000Z",
        "end_time": "2026-06-16T10:30:00.000Z",
    },
)
print(res.json()["appointment"])

Réponse (200 OK) :

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "appointment": {
    "id": "aBcD1234eFgH5678",
    "contact_id": "contact_abc123",
    "event_id": "event_xyz789",
    "status": "Confirmed",
    "start_time": "2026-06-16T10:00:00.000Z",
    "end_time": "2026-06-16T10:30:00.000Z",
    "calendar_synced": true
  }
}

Annuler un rendez-vous #

POST /appointments/{appointmentId}/cancel

Annule un rendez-vous confirmé, en enregistrant éventuellement un motif. Le rendez-vous reste dans votre compte avec le statut Canceled, et l’événement de calendrier associé est supprimé automatiquement en arrière-plan. L’annulation d’un rendez-vous déjà annulé renvoie une erreur 400.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "Client asked to reschedule next month"
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cancellation_reason: "Client asked to reschedule next month",
    }),
  }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/cancel",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"cancellation_reason": "Client asked to reschedule next month"},
)
print(res.json()["success"])

Réponse (200 OK) :

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678"
}

Renvoyer la confirmation de réservation #

POST /appointments/{appointmentId}/resend-confirmation

Renvoie au contact sa confirmation de réservation, par exemple s’il indique ne jamais l’avoir reçue ou qu’elle est arrivée dans ses courriers indésirables. Deux éléments sont envoyés, sauf si vous en désactivez un : l’e-mail de confirmation (le même que celui reçu par le contact lors de sa réservation) et, si le rendez-vous figure dans votre Google Agenda, l’invitation Google Agenda. Les deux sont envoyés à l’adresse e-mail du contact.

Chaque partie renvoie son propre résultat : sent, not_requested, no_contact_email, turned_off_for_event_type (l’option Envoyer un e-mail de rendez-vous au contact du type d’événement est désactivée), not_on_google_calendar, imported (les rendez-vous importés depuis votre calendrier ne reçoivent pas d’e-mail de confirmation) ou failed.

• 200 lorsqu’au moins une partie a été envoyée. recipient est l’adresse vers laquelle l’envoi a été effectué.
• 409 pour un rendez-vous annulé, un rendez-vous déjà passé, ou une réservation effectuée via Zenchef, Formitable, OpenTable, TheFork ou Trafft (ce système envoie sa propre confirmation). code est appointment_canceled, appointment_in_past ou managed_by_provider.
• 422 lorsqu’aucun envoi n’a pu être effectué, avec la raison dans error.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ calendar_invite: false }),
  }
);
const data = await res.json();
console.log(data.email, data.recipient);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678/resend-confirmation",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={},
)
print(res.json())

Réponse (200 OK) :

{
  "success": true,
  "appointment_id": "aBcD1234eFgH5678",
  "email": "sent",
  "calendar_invite": "sent",
  "recipient": "jane@example.com"
}

Supprimer un rendez-vous #

DELETE /appointments/{appointmentId}

Supprime définitivement un rendez-vous et ses références. Si vous souhaitez seulement annuler la réservation tout en conservant l’enregistrement, utilisez plutôt annuler.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.success);

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/appointments/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["success"])

Réponse (200 OK) :

{
  "success": true
}

Lister vos agendas Google connectés #

GET /appointments/google-calendars

Renvoie les agendas Google disponibles sur ce compte, directement depuis Google — utile pour montrer au titulaire du compte un sélecteur de l’agenda à partir duquel importer ci-dessous, ou simplement pour confirmer que la connexion est active.

Cela ne fonctionne qu’une fois que le compte a connecté Google Calendar (Paramètres → Intégrations) avec au moins un accès en lecture. Si ce n’est pas le cas, ou si l’accès accordé n’inclut plus la portée de lecture du calendrier, vous recevrez une 400 vous demandant de le (re)connecter.

cURL

curl "https://api.youraiconnector.com/v1/appointments/google-calendars" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/google-calendars", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
console.log(data.data);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/appointments/google-calendars",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json()["data"])

Réponse (200 OK) :

{
  "success": true,
  "data": [
    {
      "id": "primary",
      "summary": "jane@example.com",
      "timeZone": "America/New_York",
      "accessRole": "owner",
      "primary": true
    },
    {
      "id": "abcdefg1234567890@group.calendar.google.com",
      "summary": "Bookings",
      "timeZone": "America/New_York",
      "accessRole": "writer"
    }
  ]
}

Chaque entrée correspond à la forme CalendarListEntry de Google, donc les noms des champs suivent la camelCase de Google, et non la snake_case habituelle de cette API — il s’agit des données de Google transmises telles quelles, et non des nôtres. Une connexion manquante ou révoquée renvoie 400 avec une erreur expliquant que Google Calendar doit être (re)connecté.

Importer des événements depuis un Google Calendar #

POST /appointments/import-calendar-events

Récupère les événements déjà présents dans le ou les Google Calendar connectés d’une campagne ou d’un agent IA et les transforme en rendez-vous — utile la première fois que vous connectez un calendrier qui contient déjà des réservations. Cela peut prendre un certain temps (chaque événement passe par une extraction pour déterminer à qui il est destiné), donc cela ne s’exécute jamais en ligne : la requête met en file d’attente une tâche en arrière-plan et vous renvoie un job_id à interroger.

Envoyez exactement l’un des deux campaign_id / agent_id, jamais les deux et jamais aucun des deux — toute autre combinaison renvoie une 400. Celui que vous envoyez doit appartenir à votre compte, sinon vous recevrez une 404.

cURL

curl -X POST "https://api.youraiconnector.com/v1/appointments/import-calendar-events?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_abc123",
    "identifier": "EMAIL"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/appointments/import-calendar-events", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_abc123",
    identifier: "EMAIL",
  }),
});
const data = await res.json();
console.log(data.job_id);

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/appointments/import-calendar-events",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"agent_id": "agent_abc123", "identifier": "EMAIL"},
)
print(res.json()["job_id"])

Réponse (202 Accepted) :

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "queued",
  "campaign_id": null,
  "agent_id": "agent_abc123"
}

campaign_id et agent_id renvoient celui que vous avez envoyé ; l’autre est toujours null.

Interroger la tâche d’importation #

GET /appointments/import-calendar-events/{jobId}

curl "https://api.youraiconnector.com/v1/appointments/import-calendar-events/jK9mQ2xR7pL4wN1t" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) :

{
  "success": true,
  "job_id": "jK9mQ2xR7pL4wN1t",
  "status": "completed",
  "message": "Imported 12 events as appointments.",
  "error": null
}

GET sur un jobId qui n’existe pas (ou qui appartient à un compte différent) renvoie 404.

Intégrations de réservation externes (Zenchef / Formitable / OpenTable / TheFork / Trafft) #

Zenchef et Formitable sont des systèmes de réservation de restaurant via lesquels votre agent IA peut réserver de vraies tables ; Trafft est une plateforme de planification pour les entreprises fonctionnant sur rendez-vous, connectée une fois par compte plutôt que par restaurant. Les deux plateformes de restauration disposent chacune d’un widget de réservation public et non authentifié (https://api.youraiconnector.com/v1/zenchef-widget/... et https://api.youraiconnector.com/v1/formitable-widget/...) qui s’affiche dans le chat pour le client — ces routes de widget sont de simples pages HTML destinées à être ouvertes dans un navigateur, et non des points de terminaison d’API JSON, elles ne sont donc pas documentées ici. Ce qui suit concerne les points de terminaison de gestion de compte : vérifier qu’un identifiant de restaurant appartient au titulaire du compte, puis l’ajouter, le mettre à jour ou le supprimer.

Zenchef #

La connexion d’un restaurant Zenchef est une vérification en deux étapes, afin que le titulaire du compte prouve qu’il gère réellement le restaurant avant qu’il ne soit relié au bot : vérifiez d’abord que l’identifiant existe (sans révéler le nom), puis demandez-lui de saisir lui-même le nom du restaurant et vérifiez qu’il correspond.

Étape 1 — Vérifier l’existence d’un identifiant de restaurant

POST /appointments/zenchef-restaurants/check

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/check?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345" }'

Réponse (200 OK) :

{
  "success": true,
  "data": { "exists": true, "requiresNameVerification": true }
}

exists: false signifie qu’aucun restaurant Zenchef ne possède cet identifiant — rien d’autre à faire. Limité à 10 vérifications par tranche de 5 minutes par compte ; tout dépassement renvoie 429.

Étape 2 — Vérifier le nom du restaurant

POST /appointments/zenchef-restaurants/verify-name

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/verify-name?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "user_input_name": "The Blue Door Bistro" }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "id": "12345",
      "name": "The Blue Door Bistro",
      "address": "1 Rue de Rivoli, Paris",
      "status": "active"
    }
  }
}

verified: false signifie que le nom ne correspond pas — restaurantDetails est omis, demandez au titulaire du compte de réessayer. Limité à 3 tentatives par tranche de 5 minutes (plus strict que la vérification d’existence, car il s’agit de l’étape de preuve réelle). Un restaurant_id qui ne correspond plus sur Zenchef renvoie 404.

Étape 3 — Enregistrer le restaurant

POST /appointments/zenchef-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "12345", "restaurant_name": "The Blue Door Bistro" }'

Réponse (201 Created) :

{ "success": true, "data": { "restaurantId": "12345" } }

Mettre à jour un restaurant Zenchef enregistré

PUT /appointments/zenchef-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Réponse (200 OK) : même structure que la réponse d’enregistrement ci-dessus.

Supprimer un restaurant Zenchef

DELETE /appointments/zenchef-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/zenchef-restaurants/12345" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "12345" } }

Un restaurantId qui n’est pas actuellement sur le compte renvoie 404 lors d’une mise à jour ou d’une suppression.

Formitable #

Formitable n’a pas besoin de la vérification de nom en deux étapes comme Zenchef — ses identifiants de restaurant sont déjà limités par entreprise, donc un seul appel de vérification suffit. Il dispose également d’une recherche de détails utilisée pour mettre en cache l’URL du site web du restaurant lors de la configuration.

Vérifier un identifiant de restaurant

POST /appointments/formitable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "the-blue-door", "language": "en" }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "the-blue-door",
      "productCount": 4,
      "sampleProductTitle": "Dinner for two",
      "language": "en"
    }
  }
}

Un restaurant_id que Formitable ne reconnaît pas renvoie 404. Limité à 10 tentatives par tranche de 5 minutes par compte.

Obtenir les détails du restaurant

GET /appointments/formitable-restaurants/{restaurantId}/details?language=en

Récupère le profil public du restaurant depuis Formitable, y compris son site web — utilisé pour mettre en cache l’URL du site web lors de la configuration du restaurant. language est un paramètre de requête optionnel, dont la valeur par défaut est "en".

curl "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door/details?language=en" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "uid": "the-blue-door",
    "name": "The Blue Door Bistro",
    "website": "https://thebluedoorbistro.com",
    "email": "info@thebluedoorbistro.com",
    "telephone": "+31201234567",
    "streetAddress": "Prinsengracht 1",
    "zipcode": "1015 AB",
    "city": "Amsterdam",
    "country": "Netherlands",
    "countryCode": "NL",
    "currency": "EUR"
  }
}

Enregistrer le restaurant

POST /appointments/formitable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/formitable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "restaurant_id": "the-blue-door",
    "restaurant_name": "The Blue Door Bistro",
    "language": "en",
    "website_url": "https://thebluedoorbistro.com"
  }'

Réponse (201 Created) : { "success": true, "data": { "restaurantId": "the-blue-door" } }

Mettre à jour un restaurant Formitable enregistré

PUT /appointments/formitable-restaurants/{restaurantId}

curl -X PUT "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Réponse (200 OK) : même structure que la réponse d’enregistrement ci-dessus.

Supprimer un restaurant Formitable

DELETE /appointments/formitable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/formitable-restaurants/the-blue-door" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "the-blue-door" } }

Un restaurantId qui n’est pas actuellement sur le compte renvoie 404 lors d’une mise à jour ou d’une suppression.

OpenTable #

Les restaurants OpenTable sont accessibles via les identifiants de partenaire OpenTable de la plateforme, et OpenTable ne permet à ces identifiants de voir que les restaurants ayant connecté l’inscription de la plateforme dans la Marketplace d’intégrations d’OpenTable. Ainsi, tout comme pour Formitable, un appel de vérification suffit : un ID de restaurant accessible (le « RID » numérique) prouve à la fois que le restaurant existe et qu’il a connecté l’intégration. Tant que l’inscription partenaire OpenTable n’est pas activée sur la plateforme, l’appel de vérification répond 503.

Vérifier un restaurant OpenTable

POST /appointments/opentable-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007" }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "1038007",
      "diningAreaCount": 2,
      "diningAreaNames": ["Main Room", "Garden"],
      "tableTypes": ["default", "outdoor", "bar"]
    }
  }
}

verified: false signifie qu’aucun restaurant OpenTable ne possède cet ID. Un 403 signifie que le restaurant existe mais n’a pas encore connecté l’intégration de la plateforme dans OpenTable. Limité à 10 tentatives par tranche de 5 minutes par compte.

Ajouter un restaurant OpenTable

POST /appointments/opentable-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/opentable-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "1038007", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Réponse (201 Created) : { "success": true, "data": { "restaurantId": "1038007" } }

Mettre à jour un restaurant OpenTable enregistré

PUT /appointments/opentable-restaurants/{restaurantId}

Envoyez l’un des éléments suivants : restaurant_name, is_active (mettez en pause avec false) ou website_url (une chaîne vide efface le champ) ; les champs omis restent inchangés.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "1038007" } }

Supprimer un restaurant OpenTable

DELETE /appointments/opentable-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/opentable-restaurants/1038007" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "1038007" } }

Un restaurantId qui n’est pas actuellement sur le compte renvoie 404 lors d’une mise à jour.

TheFork #

Les restaurants TheFork sont accessibles via les identifiants de partenaire TheFork de la plateforme, et TheFork ne permet à ces identifiants de voir que les restaurants ayant activé le partenaire de la plateforme sur leur compte TheFork. Ainsi, tout comme pour Formitable et OpenTable, un seul appel de vérification suffit : un ID de restaurant accessible prouve à la fois que le restaurant existe et que le partenaire est activé pour celui-ci. L’ID est l’UUID que TheFork attribue au restaurant dans TheFork Manager, envoyé sous forme de chaîne de caractères. Tant que TheFork n’a pas approuvé la plateforme en tant que partenaire et n’a pas émis les identifiants, l’appel de vérification répond 503 — voir TheFork pour savoir ce que cela signifie aujourd’hui.

Vérifier un restaurant TheFork

POST /appointments/thefork-restaurants/verify

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/verify?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "verified": true,
    "restaurantDetails": {
      "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60",
      "partySizes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
  }
}

partySizes correspond aux tailles de groupe que le restaurant accepte en ligne au cours des 30 prochains jours. Un 404 ou 403 signifie que TheFork ne nous a pas fourni de restaurant avec cet ID — soit l’ID est incorrect, soit le partenaire de la plateforme n’est pas encore activé sur ce restaurant ; un 400 signifie que l’ID n’est pas un UUID. Limité à 10 tentatives par tranche de 5 minutes par compte.

Ajouter un restaurant TheFork

POST /appointments/thefork-restaurants

curl -X POST "https://api.youraiconnector.com/v1/appointments/thefork-restaurants?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "restaurant_id": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60", "restaurant_name": "The Blue Door", "website_url": "https://thebluedoor.example" }'

Réponse (201 Created) : { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Mettre à jour un restaurant TheFork enregistré

PUT /appointments/thefork-restaurants/{restaurantId}

Envoyez l’un des éléments suivants : restaurant_name, is_active (mettez en pause avec false) ou website_url (une chaîne vide efface le champ) ; les champs omis restent inchangés.

curl -X PUT "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Supprimer un restaurant TheFork

DELETE /appointments/thefork-restaurants/{restaurantId}

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/thefork-restaurants/9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) : { "success": true, "data": { "restaurantId": "9f2a1c34-5b6d-4e7f-8a90-1b2c3d4e5f60" } }

Un restaurantId qui n’est pas actuellement sur le compte renvoie 404 lors d’une mise à jour ou d’une suppression.

Trafft #

Trafft est connecté une fois pour l’ensemble du compte, et non par emplacement : une adresse d’entreprise plus les identifiants API provenant du panneau d’administration Trafft (Features & Integrations → API & Connectors, inclus dans le plan Business de Trafft). L’appel de connexion vérifie ces identifiants auprès de Trafft avant de stocker quoi que ce soit ; ainsi, une adresse erronée, des identifiants incorrects ou un plan sans accès API échoueront ici plutôt que lors d’une conversation avec un client. Le secret client est stocké de manière chiffrée et n’est jamais renvoyé par aucun point de terminaison.

Les trois appels d’écriture (POST, PUT, DELETE) nécessitent l’autorisation edit sur les intégrations ; le statut GET nécessite l’autorisation view sur les intégrations.

Connecter Trafft

POST /appointments/trafft/connect

curl -X POST "https://api.youraiconnector.com/v1/appointments/trafft/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subdomain": "acme",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "client_secret": "YOUR_TRAFFT_CLIENT_SECRET",
    "company_name": "Acme Salon"
  }'

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "subdomain": "acme",
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

Les décomptes sont renvoyés par Trafft lors de la vérification — c’est le moyen le plus rapide de confirmer que les identifiants pointent vers le compte souhaité.

Obtenir le statut de la connexion

GET /appointments/trafft

curl "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) :

{
  "success": true,
  "data": {
    "connected": true,
    "subdomain": "acme",
    "hostname": "acme.admin.trafft.com",
    "client_id": "YOUR_TRAFFT_CLIENT_ID",
    "company_name": "Acme Salon",
    "is_active": true,
    "service_count": 12,
    "employee_count": 4,
    "location_count": 2
  }
}

connected: false signifie que rien n’est encore configuré. Le secret client n’est jamais inclus dans cette réponse.

Mettre à jour la connexion

PUT /appointments/trafft

curl -X PUT "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Réponse (200 OK) : le même objet de connexion que le GET ci-dessus.

Déconnecter Trafft

DELETE /appointments/trafft

curl -X DELETE "https://api.youraiconnector.com/v1/appointments/trafft" \
  -H "X-API-Key: YOUR_API_KEY"

Réponse (200 OK) : { "success": true }

La déconnexion supprime uniquement les identifiants stockés. Les rendez-vous déjà présents dans Trafft ne sont pas modifiés.

Format d’erreur sur tous les endpoints Zenchef/Formitable/OpenTable/TheFork : contrairement au reste de cette page, les erreurs ici portent leur statut deux fois — une fois en tant que statut HTTP et une fois en tant que error_code dans le corps de la réponse — par exemple { "success": false, "error": "Restaurant not found", "error_code": 404 }. Gérez-les de la même manière que toute autre erreur : vérifiez success, lisez error pour le message.

Erreurs de l’API Rendez-vous #

Les points de terminaison des rendez-vous renvoient l’enveloppe d’erreur standard :

{
  "success": false,
  "error": "Appointment not found"
}

Les codes partagés que chaque point de terminaison peut renvoyer — 401, 403 (votre forfait n’inclut pas l’accès à l’API), 429 (limite de débit) et 500 — sont répertoriés avec des conseils de nouvelle tentative dans Erreurs et pagination.

Étapes suivantes #

• Contacts — créez et recherchez les contacts pour lesquels vous effectuez des réservations.
• Messages et conversations — envoyez une confirmation ou un rappel à un contact.
• Webhooks — soyez averti lorsque des rendez-vous sont modifiés.