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
Un premier appel en une minute
Remplacez la clé par celle de l'association, puis lancez cette commande depuis un terminal :
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 :
// 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 }
}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) : lewwwcompte, 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 sansOrigin(depuis un script serveur, par exemple) est refusée de la même façon. - La réponse porte
Access-Control-Allow-Originavec le site appelant, jamais*, et aucun cookie n'est échangé. Les en-têtes que vous pouvez envoyer sontAuthorizationetIf-None-Match; ceux que votre script peut lire sontETag,RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,Retry-AfteretX-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).
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.
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é) ouPERIOD_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 porteWWW-Authenticate: Bearer.403MODULE_DISABLED(l'association a éteint le module « API & intégrations ») ouORIGIN_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êtesGETsont acceptées.429RATE_LIMITED: quota dépassé. L'en-têteRetry-Afterdonne le nombre de secondes à attendre.500INTERNAL_ERROR: erreur de notre côté, réessayez dans un instant.
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-RemainingetRateLimit-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 avecIf-None-Match: <ETag>: si rien n'a changé, la réponse est un304sans 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.
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.
/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.
{
"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 }
}/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.
{
"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" }
}/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 depuisfrom.siteIdGarde les événements tenus (au moins en partie) sur ce lieu.limit1 à 500, 100 par défaut.cursorLa valeurpage.nextde la réponse précédente.
{
"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"
}
}/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).
{
"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" }
}/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) ouall(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) oufull(complet).includeparticipants: ajoute les prénoms des inscrits.limit1 à 500, 100 par défaut.cursorLa valeurpage.nextde la réponse précédente.
{
"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"
}
}/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.
{
"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
{
"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"
}kindeventourecurring.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 }ounull. Un seul des deux est présent.event{ id, name }de l'événement, ounullpour une série.start / endDébut et fin, ISO 8601 à l'heure de Paris.site{ id, name, address }ounull;addresspeut êtrenull.capacitymode:capped(places limitées) ouopen(inscription ouverte à tous, éventuellement sans plafond).min: nombre de personnes visé.max: plafond, ounulls'il n'y en a pas.taken: places prises.remaining: places restantes, ounullsans plafond.availabilityopenoufull.signupUrlPage d'inscription de l'événement, ounull(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.
{
"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: trueet des valeursnull. Sa place est comptée. - Une personne dont la fiche a été anonymisée garde sa place dans le comptage, sans nom.
"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 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, …], … }
}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.
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) etsiteId, comme pour/slots. Exemple : ajoutez?kind=recurringpour 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 (ETagpris en charge).
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
Avant de se lancer
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.