Aide — API pour développeur

Afficher le planning d'une association sur son site

L'API de BenevolOps lit les événements et les créneaux que l'association a choisi de diffuser : horaires, lieu, places prises et restantes, lien d'inscription. Elle ne permet ni d'écrire, ni de lire des données personnelles. Il vous faut une clé, que l'administrateur de l'association crée dans Réglages › API & intégrations et vous transmet.

Adresse de base : https://benevolops.com/api/public/v1

Démarrer

Un premier appel en une minute

Remplacez la clé par celle de l'association, puis lancez cette commande depuis un terminal :

Depuis un serveur ou un terminal (clé secrète)Shell
curl -H "Authorization: Bearer bvo_live_VOTRE_CLE" \
  "https://benevolops.com/api/public/v1/slots?from=2026-12-01&to=2026-12-31&limit=50"

Depuis la page d'un site sans serveur (WordPress, Wix…), avec une clé publique :

Depuis un navigateur (clé publique)JavaScript
// Page d'un site déclaré dans l'écran « API & intégrations ».
// La clé publique (bvo_pub_…) peut figurer dans ce code.
const API = 'https://benevolops.com/api/public/v1'
const KEY = 'bvo_pub_VOTRE_CLE_PUBLIQUE'

async function creneaux(from, to) {
  const res = await fetch(`${API}/slots?from=${from}&to=${to}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  })
  if (res.status === 429) {
    const attente = res.headers.get('Retry-After') // secondes
    throw new Error(`Réessayez dans ${attente} s`)
  }
  if (!res.ok) {
    const { error } = await res.json()
    throw new Error(error.message)
  }
  return res.json() // { data, page, meta }
}
Authentification

Une clé dans l'en-tête, jamais dans l'adresse

Chaque appel envoie la clé dans l'en-tête Authorization: Bearer <clé>. Une clé placée dans l'adresse (?key=…) n'est pas lue : elle finirait dans les journaux des serveurs intermédiaires. La clé donne accès à une seule association, celle qui l'a créée.

Clé secrète

Commence par bvo_live_. Elle reste sur votre serveur : jamais dans le code d'une page, d'une application mobile ou d'un dépôt public. C'est la seule qui peut recevoir les prénoms des inscrits, si l'administrateur a coché l'option sur la clé. Quota : 60 appels par minute.

Clé publique

Commence par bvo_pub_. Faite pour un site sans serveur : elle peut figurer dans le code de la page. Elle ne répond qu'aux navigateurs ouverts sur les sites déclarés par l'administrateur, ne lit que le planning diffusé et jamais les prénoms. Quota : 120 appels par minute et par visiteur, 1 200 par minute pour l'ensemble des visiteurs.

Clé publique depuis un navigateur

  • Le navigateur ajoute seul l'en-tête Origin. Il doit correspondre exactement à un site déclaré (https://www.monclub.fr, sans chemin) : le www compte, et il faut déclarer les deux formes si le site répond aux deux.
  • Un autre site reçoit 403 ORIGIN_NOT_ALLOWED. Une clé publique envoyée sans Origin (depuis un script serveur, par exemple) est refusée de la même façon.
  • La réponse porte Access-Control-Allow-Origin avec le site appelant, jamais *, et aucun cookie n'est échangé. Les en-têtes que vous pouvez envoyer sont Authorization et If-None-Match ; ceux que votre script peut lire sont ETag, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After et X-Request-Id.
  • La vérification de l'origine ne protège que dans un navigateur : un programme peut imiter l'adresse d'un site. C'est pourquoi une clé publique ne sert qu'à ce que tout visiteur du site voit déjà.

Bonnes pratiques de sécurité

  • Ne mettez jamais une clé secrète dans une page web, une application ou un dépôt : n'importe quel visiteur pourrait la lire. Pour une page, utilisez une clé publique.
  • Une clé qui a pu être vue doit être révoquée tout de suite par l'administrateur, qui en crée une nouvelle. La révocation est immédiate.
  • Une clé a une date d'expiration (6 ou 12 mois) ou aucune. À l'échéance elle est refusée : prévoyez son renouvellement. L'administrateur est prévenu par e-mail 15 jours avant.
  • N'interrogez pas l'API à chaque affichage de page : mettez la réponse en cache de votre côté une minute ou deux (voir plus bas).
Conventions

Ce qui vaut pour toutes les adresses

Dates et fuseau horaire

Tout est exprimé à l'heure de Paris (Europe/Paris, rappelé dans meta.timezone). Les instants (start, end, updatedAt) sont au format ISO 8601 avec le décalage du moment, par exemple 2026-12-12T10:00:00+01:00 en hiver et +02:00 en été. Les jours (from, to, startDate) sont au format AAAA-MM-JJ.

Période et pagination

Les listes demandent une période from / to (jours inclus) de 93 jours au plus, et remontent à 12 mois dans le passé. Une liste rend limit éléments (100 par défaut, 500 au plus) et, s'il y en a d'autres, un curseur dans page.next à repasser tel quel dans cursor.page.next vaut null sur la dernière page.

Ce qui est diffusé

L'API ne rend que ce que l'association a allumé avec « Diffuser sur mon site » : un événement et ses créneaux, ou une série de créneaux récurrents (permanences). Un créneau annulé ou masqué du lien public n'est jamais servi, ni les cours. Un identifiant d'une autre association, ou d'un élément non diffusé, répond simplement 404. Un paramètre inconnu ou répété est refusé en 400 : une faute de frappe ne passe pas en silence.

Erreurs

Toute erreur a la même forme : un objet error avec un code stable, à tester dans votre programme, et un message en français, à afficher ou à journaliser.

Réponse d'erreurHTTP
HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "PERIOD_TOO_LONG",
    "message": "La période demandée couvre 365 jours : 93 jours au plus par appel, « from » et « to » inclus. Découpez-la en plusieurs appels."
  }
}
  • 400INVALID_PARAMETER (paramètre manquant, inconnu, répété ou mal formé) ou PERIOD_TOO_LONG (plus de 93 jours).
  • 401INVALID_KEY : clé absente, inconnue, expirée ou révoquée. Le message est le même dans tous les cas, volontairement. La réponse porte WWW-Authenticate: Bearer.
  • 403MODULE_DISABLED (l'association a éteint le module « API & intégrations ») ou ORIGIN_NOT_ALLOWED (clé publique appelée depuis un site non déclaré).
  • 404NOT_FOUND : identifiant inconnu, d'une autre association ou non diffusé, ou adresse inconnue.
  • 405METHOD_NOT_ALLOWED : l'API est en lecture seule, seules les requêtes GET sont acceptées.
  • 429RATE_LIMITED : quota dépassé. L'en-tête Retry-After donne le nombre de secondes à attendre.
  • 500INTERNAL_ERROR : erreur de notre côté, réessayez dans un instant.
Quotas et cache

Limites d’appels et mise en cache

Quotas

  • 60 appels par minute et par clé secrète.
  • 120 appels par minute et par visiteur (adresse IP) pour une clé publique, et au plus 1 200 par minute pour la clé, tous visiteurs confondus : un visiteur trop pressé ne prive pas les autres du planning.
  • Au plus 300 appels par minute depuis une même adresse IP, toutes clés confondues.
  • Chaque réponse indique RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes avant la prochaine minute).
  • L'écran de l'association montre l'usage de chaque clé sur 30 jours.

Cache et ETag

  • Les données sont à jour à une minute près : une inscription ou une modification apparaît au plus tard après ce délai.
  • Chaque réponse porte un ETag. Rappelez la même adresse avec If-None-Match: <ETag> : si rien n'a changé, la réponse est un 304 sans contenu, et cet appel ne compte pas dans votre quota.
  • Cache-Control: private, max-age=60 : votre navigateur ou votre serveur peut réutiliser la réponse pendant une minute.
Les adresses

Six adresses, toutes en lecture

Les exemples ci-dessous suivent la forme réelle des réponses ; les valeurs sont illustratives. Les adresses sont relatives à https://benevolops.com/api/public/v1.

GET

/organization

Tester la clé

Rend le nom de l'association, son fuseau horaire et la description de la clé utilisée (nom, préfixe, droits, échéance) avec son quota par minute. Pratique pour vérifier qu'une clé fonctionne. Aucun paramètre.

Exemple de réponseJSON
{
  "name": "Mon association",
  "slug": "mon-asso",
  "timezone": "Europe/Paris",
  "key": {
    "name": "Site du club",
    "prefix": "bvo_live_ab12cd",
    "scopes": [ "read:planning" ],
    "expiresAt": null
  },
  "rateLimit": { "perMinute": 60 }
}
GET

/sites

Les lieux

Les lieux de l'association où se tient au moins un événement ou un créneau diffusé, sur les 12 derniers mois et à venir, par ordre alphabétique. Pratique pour proposer un filtre par lieu : son id se passe ensuite en siteId. Aucun paramètre.

Exemple de réponseJSON
{
  "data": [
    {
      "id": "cm0site0salle0001",
      "name": "Salle des fêtes",
      "address": "1 rue de la Mairie"
    },
    { "id": "cm0site0gymnase01", "name": "Gymnase", "address": null }
  ],
  "page": { "next": null },
  "meta": { "timezone": "Europe/Paris", "generatedAt": "2026-11-21T22:05:26+01:00" }
}
GET

/events

Les événements diffusés d'une période

Un événement est rendu s'il a lieu, en tout ou partie, dans la période, trié par date. Le champ totals additionne ses créneaux diffusés : capacity vaut null si l'un des créneaux n'a pas de plafond. description est du texte brut. image (l'affiche) n'est présent que si l'événement en a une et que son lien public est actif ; signupUrl (page d'inscription) vaut null si le lien public est désactivé.

Paramètres

  • fromobligatoirePremier jour, AAAA-MM-JJ (pas avant 12 mois).
  • toobligatoireDernier jour inclus. 93 jours au plus depuis from.
  • siteIdGarde les événements tenus (au moins en partie) sur ce lieu.
  • limit1 à 500, 100 par défaut.
  • cursorLa valeur page.next de la réponse précédente.
Exemple de réponseJSON
{
  "data": [
    {
      "id": "cm0evt0marche0001",
      "name": "Marché de Noël",
      "description": "Le rendez-vous annuel de l'association.",
      "startDate": "2026-12-12",
      "endDate": "2026-12-13",
      "start": "2026-12-12T09:00:00+01:00",
      "end": "2026-12-13T18:00:00+01:00",
      "site": {
        "id": "cm0site0salle0001",
        "name": "Salle des fêtes",
        "address": "1 rue de la Mairie"
      },
      "color": "#E35D6A",
      "image": "https://benevolops.com/api/public-events/mon-asso/cm0evt0marche0001/image?kind=photo",
      "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
      "totals": { "slots": 12, "capacity": 36, "taken": 20, "remaining": 16 },
      "updatedAt": "2026-11-20T18:42:10+01:00"
    }
  ],
  "page": { "next": null },
  "meta": {
    "from": "2026-12-01",
    "to": "2026-12-31",
    "timezone": "Europe/Paris",
    "generatedAt": "2026-11-21T22:05:26+01:00"
  }
}
GET

/events/{id}

Un événement avec ses créneaux

Les mêmes champs que dans la liste, plus activities : les activités de l'événement dans l'ordre de leur premier créneau, chacune avec ses créneaux (forme décrite plus bas). Pas de pagination. Un événement non diffusé répond 404.

Paramètres

  • includeparticipants : ajoute les prénoms des inscrits à chaque créneau (clé secrète autorisée seulement, voir plus bas).
Exemple de réponseJSON
{
  "data": {
    "id": "cm0evt0marche0001",
    "name": "Marché de Noël",
    "description": "Le rendez-vous annuel de l'association.",
    "startDate": "2026-12-12",
    "endDate": "2026-12-13",
    "start": "2026-12-12T09:00:00+01:00",
    "end": "2026-12-13T18:00:00+01:00",
    "site": {
      "id": "cm0site0salle0001",
      "name": "Salle des fêtes",
      "address": "1 rue de la Mairie"
    },
    "color": "#E35D6A",
    "image": "https://benevolops.com/api/public-events/mon-asso/cm0evt0marche0001/image?kind=photo",
    "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
    "totals": { "slots": 12, "capacity": 36, "taken": 20, "remaining": 16 },
    "updatedAt": "2026-11-20T18:42:10+01:00",
    "activities": [
      {
        "id": "cm0act0buvette01",
        "name": "Buvette",
        "slots": [
          {
            "id": "cm0slot0buvette01",
            "kind": "event",
            "title": "Buvette",
            "activity": { "id": "cm0act0buvette01", "name": "Buvette" },
            "event": { "id": "cm0evt0marche0001", "name": "Marché de Noël" },
            "start": "2026-12-12T10:00:00+01:00",
            "end": "2026-12-12T13:00:00+01:00",
            "site": {
              "id": "cm0site0salle0001",
              "name": "Salle des fêtes",
              "address": "1 rue de la Mairie"
            },
            "capacity": { "mode": "capped", "min": 2, "max": 4, "taken": 3, "remaining": 1 },
            "availability": "open",
            "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
            "updatedAt": "2026-11-20T18:42:10+01:00"
          }
        ]
      }
    ]
  },
  "meta": { "timezone": "Europe/Paris", "generatedAt": "2026-11-21T22:05:33+01:00" }
}
GET

/slots

Les créneaux diffusés d'une période

Triés par heure de début. Vous obtenez tout ce dont une vue semaine ou mois a besoin sans autre appel : horaire, lieu, places, lien d'inscription.

Paramètres

  • fromobligatoirePremier jour, AAAA-MM-JJ.
  • toobligatoireDernier jour inclus (93 jours au plus).
  • kindevent (créneaux d'événements), recurring (permanences) ou all (défaut).
  • eventIdLes créneaux de cet événement seulement.
  • siteIdLes créneaux tenus sur ce lieu (celui de l'événement si le créneau n'a pas le sien).
  • availabilityopen (il reste de la place) ou full (complet).
  • includeparticipants : ajoute les prénoms des inscrits.
  • limit1 à 500, 100 par défaut.
  • cursorLa valeur page.next de la réponse précédente.
Exemple de réponseJSON
{
  "data": [
    {
      "id": "cm0slot0buvette01",
      "kind": "event",
      "title": "Buvette",
      "activity": { "id": "cm0act0buvette01", "name": "Buvette" },
      "event": { "id": "cm0evt0marche0001", "name": "Marché de Noël" },
      "start": "2026-12-12T10:00:00+01:00",
      "end": "2026-12-12T13:00:00+01:00",
      "site": {
        "id": "cm0site0salle0001",
        "name": "Salle des fêtes",
        "address": "1 rue de la Mairie"
      },
      "capacity": { "mode": "capped", "min": 2, "max": 4, "taken": 3, "remaining": 1 },
      "availability": "open",
      "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
      "updatedAt": "2026-11-20T18:42:10+01:00"
    }
  ],
  "page": {
    "next": "eyJ0IjoiMjAyNi0xMi0xMlQwOTowMDowMC4wMDBaIiwiaSI6ImNtMHNsb3QwYnV2ZXR0ZTAxIn0"
  },
  "meta": {
    "from": "2026-12-01",
    "to": "2026-12-31",
    "timezone": "Europe/Paris",
    "generatedAt": "2026-11-21T22:05:26+01:00"
  }
}
GET

/slots/{id}

Un créneau

Un créneau diffusé, avec la forme décrite ci-dessous. Un créneau inconnu, annulé ou non diffusé répond 404.

Paramètres

  • includeparticipants : ajoute les prénoms des inscrits.
Exemple de réponseJSON
{
  "data": {
    "id": "cm0slot0buvette01",
    "kind": "event",
    "title": "Buvette",
    "activity": { "id": "cm0act0buvette01", "name": "Buvette" },
    "event": { "id": "cm0evt0marche0001", "name": "Marché de Noël" },
    "start": "2026-12-12T10:00:00+01:00",
    "end": "2026-12-12T13:00:00+01:00",
    "site": {
      "id": "cm0site0salle0001",
      "name": "Salle des fêtes",
      "address": "1 rue de la Mairie"
    },
    "capacity": { "mode": "capped", "min": 2, "max": 4, "taken": 3, "remaining": 1 },
    "availability": "open",
    "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
    "updatedAt": "2026-11-20T18:42:10+01:00"
  },
  "meta": { "timezone": "Europe/Paris", "generatedAt": "2026-11-21T22:05:33+01:00" }
}

La forme d'un créneau

Créneau d'un événementJSON
{
  "id": "cm0slot0buvette01",
  "kind": "event",
  "title": "Buvette",
  "activity": { "id": "cm0act0buvette01", "name": "Buvette" },
  "event": { "id": "cm0evt0marche0001", "name": "Marché de Noël" },
  "start": "2026-12-12T10:00:00+01:00",
  "end": "2026-12-12T13:00:00+01:00",
  "site": {
    "id": "cm0site0salle0001",
    "name": "Salle des fêtes",
    "address": "1 rue de la Mairie"
  },
  "capacity": { "mode": "capped", "min": 2, "max": 4, "taken": 3, "remaining": 1 },
  "availability": "open",
  "signupUrl": "https://benevolops.com/public/evenements/mon-asso/cm0evt0marche0001",
  "updatedAt": "2026-11-20T18:42:10+01:00"
}
  • kindevent ou recurring.
  • titleLe titre à afficher.
  • activity / seriesL'activité d'un créneau d'événement (activity), ou la série d'un créneau récurrent (series) : { id, name } ou null. Un seul des deux est présent.
  • event{ id, name } de l'événement, ou null pour une série.
  • start / endDébut et fin, ISO 8601 à l'heure de Paris.
  • site{ id, name, address } ou null ; address peut être null.
  • capacitymode : capped (places limitées) ou open (inscription ouverte à tous, éventuellement sans plafond). min : nombre de personnes visé. max : plafond, ou null s'il n'y en a pas. taken : places prises. remaining : places restantes, ou null sans plafond.
  • availabilityopen ou full.
  • signupUrlPage d'inscription de l'événement, ou null (lien public désactivé, ou série récurrente : on s'y inscrit dans l'application).
  • updatedAtDernière modification, pour savoir si votre copie est à jour.
Créneau d'une série récurrente (permanence)JSON
{
  "id": "cm0slot0perm00042",
  "kind": "recurring",
  "title": "Permanence du local",
  "series": { "id": "cm0ser0permanence", "name": "Permanence du local" },
  "event": null,
  "start": "2026-12-02T14:00:00+01:00",
  "end": "2026-12-02T17:00:00+01:00",
  "site": null,
  "capacity": { "mode": "open", "min": 1, "max": null, "taken": 1, "remaining": null },
  "availability": "open",
  "signupUrl": null,
  "updatedAt": "2026-11-20T18:42:10+01:00"
}

Les prénoms des inscrits

Par défaut, un créneau ne donne que des comptages. Avec include=participants, il porte aussi la liste participants, triée par prénom. C'est possible seulement avec une clé secrète dont l'administrateur a coché « Inclure les prénoms des inscrits » ; sinon la réponse est 400 INVALID_PARAMETER.

  • Seuls le prénom et l'initiale du nom sont rendus : jamais le nom complet, l'e-mail ou le téléphone.
  • Un mineur n'est jamais nommé : son entrée porte minor: true et des valeurs null. Sa place est comptée.
  • Une personne dont la fiche a été anonymisée garde sa place dans le comptage, sans nom.
Dans un créneau, avec include=participantsJSON
"participants": [
  { "firstName": "Camille", "lastInitial": "D." },
  { "firstName": "Victor", "lastInitial": "B." },
  { "firstName": null, "lastInitial": null, "minor": true }
]

Exemple : une vue semaine

Une semaine tient dans une seule période (7 jours, bien sous la limite de 93). L'exemple suit le curseur tant qu'il en reste un et regroupe les créneaux par jour. Comme start est déjà à l'heure de Paris, ses dix premiers caractères donnent le jour sans calcul de fuseau.

Vue semaineJavaScript
// Vue semaine : les créneaux du lundi au dimanche, regroupés par jour.
// « start » porte déjà l'heure de Paris : ses 10 premiers caractères
// donnent le jour, sans calcul de fuseau horaire.
async function semaine(lundi, dimanche) {
  const parJour = {}
  let cursor = null
  do {
    const url = new URL(`${API}/slots`)
    url.searchParams.set('from', lundi)      // ex. 2026-12-07
    url.searchParams.set('to', dimanche)     // ex. 2026-12-13
    if (cursor) url.searchParams.set('cursor', cursor)
    const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } })
    const page = await res.json()
    for (const s of page.data) {
      const jour = s.start.slice(0, 10)
      ;(parJour[jour] ??= []).push(s)
    }
    cursor = page.page.next
  } while (cursor)
  return parJour // { "2026-12-12": [créneau, …], … }
}
Lien d'agenda

Pour Google Agenda, Outlook ou un bloc agenda

Un agenda ne sait pas envoyer d'en-tête : le lien d'agenda porte donc son propre code secret dans l'adresse, distinct des clés API. L'administrateur le crée dans la même page de Réglages ; il suffit de le coller dans l'application d'agenda, qui se met à jour seule.

Adresse du lien d'agenda (GET /calendar/<code>.ics)URL
https://benevolops.com/api/public/v1/calendar/bvo_cal_VOTRE_CODE.ics
  • Il rend un fichier iCalendar (text/calendar) des créneaux diffusés, du mois précédent aux six mois à venir (2 000 créneaux au plus).
  • Paramètres facultatifs : kind (event, recurring, all) et siteId, comme pour /slots. Exemple : ajoutez ?kind=recurring pour un agenda des seules permanences.
  • Chaque créneau porte son lieu, et son titre indique les places restantes (« Buvette — 1 place », « Complet ») ; le lien d'inscription est dans la description.
  • Aucun prénom n'y figure, même si une clé en reçoit : un agenda se partage plus largement qu'une page.
  • Un lien régénéré ou inconnu répond 404 : recollez le nouveau lien. Quota : 30 appels par minute et par lien. Le fichier se met en cache cinq minutes (ETag pris en charge).
Extrait du fichieriCalendar
BEGIN:VEVENT
SUMMARY:Buvette — 1 place
LOCATION:Salle des fêtes\, 1 rue de la Mairie
DESCRIPTION:Marché de Noël\nPlaces restantes : 1\nS’inscrire : https://…
END:VEVENT
Questions fréquentes

Avant de se lancer

Oui, de deux façons. Sans aucun développement : collez le lien d’agenda dans un bloc agenda ou un agenda Google intégré à la page. Pour une vue sur mesure (semaine, mois, places restantes) : une clé publique appelle l’API directement depuis la page, et ne répond qu’aux adresses de site déclarées par l’association.
Non pour le lien d’agenda : il suffit de le coller, les créneaux diffusés se mettent à jour seuls. Oui pour une présentation sur mesure : votre prestataire lit les événements et créneaux avec une clé, en suivant les exemples de cette page.
Non par défaut : l’API ne sert que les horaires, le lieu, les places prises et restantes et le lien d’inscription. Le prénom et l’initiale des inscrits ne sont lisibles qu’avec une clé secrète pour laquelle l’association l’a autorisé, jamais avec une clé publique ni dans le lien d’agenda, et un mineur n’est jamais nommé.
Oui, à une minute près : une nouvelle inscription ou un créneau modifié apparaît sur le site au plus tard une minute après.
L’administrateur de l’association la révoque en un clic dans Réglages, API et intégrations : elle est refusée dès l’appel suivant, sans toucher aux autres clés. Il en crée ensuite une nouvelle pour son prestataire.

Une question sur l'intégration ?

Écrivez-nous en précisant l'adresse appelée et le message d'erreur reçu : le code d'erreur suffit souvent à trouver la cause.

Cette page peut être transmise telle quelle à votre prestataire : elle ne demande aucune connexion.