Le kit complet, 108 Ko : belle-prog-kit-v1.zip · ce guide, la spécification, OpenAPI, les schémas, les exemples PHP, Node et WordPress, le validateur. Version du 13/11/2026.
Vous développez le site d'une salle, d'un théâtre ou d'un festival, et ce lieu veut apparaître dans Belle Prog, l'application qui rassemble les agendas des lieux culturels. Ce guide explique, dans l'ordre, ce que vous avez à faire. Il complète la spécification (docs/CONTRAT-V1.md, qui fait foi) et le README du kit, qui est le pense-bête une fois le guide lu.
Si le site est sous WordPress, l'extension Belle Prog fait tout cela sans code. Ce guide est pour les autres sites, et pour les WordPress où l'extension ne peut pas être installée (voir alors l'exemple WordPress).
1. En une page
Ce que fait Belle Prog. Toutes les 15 minutes, le backend de Belle Prog vient lire la programmation sur le site de chaque lieu partenaire, la vérifie, copie les visuels et la montre au public dans l'application : agenda par lieu, favoris, rappels, notification quand une date est annulée ou complète.
Ce que vous avez à faire. Exposer sur le site deux adresses en lecture, en JSON, protégées par une clé :
| Adresse | Contenu | Lue |
|---|---|---|
GET <base>/venue | la fiche du lieu : nom, adresse, coordonnées, visuel, site | une fois par jour |
GET <base>/events | les dates à venir, avec quelques filtres | toutes les 15 minutes |
GET <base>/pages | optionnel : pages d'infos pratiques, gardées hors connexion (surtout pour un festival, section 8.4) | une fois par jour |
Rien à installer, aucune bibliothèque imposée, aucun compte à créer. Belle Prog appelle votre site ; vous n'envoyez rien, hormis un « ping » optionnel après une publication (section 7).
Ce que Belle Prog vous donne : l'identifiant du lieu (par exemple ma-salle) et une clé d'API. Pour le ping optionnel, une adresse et un secret.
Ce que vous rendez : la base de vos deux adresses (par exemple https://www.ma-salle.fr/api/belle-prog/v1), une fois que le validateur du kit affiche « Conforme ».
Combien de temps. Une demi-journée à une journée pour un site qui a déjà une base d'événements propre. L'essentiel du travail est la correspondance entre vos données et les champs du contrat (section 4).
2. Ce qu'il vous faut
- Un site servi en HTTPS avec un certificat valide : le backend refuse HTTP.
- La possibilité d'ajouter deux routes à l'application du site, dans n'importe quel langage (PHP, Node, Python, Ruby, Go…). Les exemples du kit sont en PHP et en Node.
- Dans vos données, pour chaque événement, de quoi remplir les champs requis du contrat. Vérifiez-les avant de coder, c'est là que se cachent les surprises :
| Il faut | Chez vous, typiquement |
|---|---|
| un identifiant interne stable | la clé primaire de l'événement, jamais son titre ni son slug |
| le titre | |
| le premier jour, et l'heure si elle est connue | date de début, heure ; une date de fin pour une exposition ou un stage |
| un visuel en HTTPS, avec sa largeur et sa hauteur en pixels | l'image de l'événement et ses dimensions (à lire dans le fichier ou en base) |
| la page de l'événement sur le site | son adresse publique |
| gratuit ou payant, dit explicitement | une case « gratuit », ou le texte des tarifs |
| le statut : programmé, complet, reporté, annulé | un champ ou une case ; à défaut, tout est « programmé » |
| la date de dernière modification | updated_at de l'enregistrement |
| ce qui est publié et ce qui ne l'est pas | votre champ de publication : rien d'autre ne doit sortir |
Un événement auquel il manque un champ requis (un visuel, le plus souvent) ne peut pas être affiché : il sera rejeté à l'import, les autres passent. Voyez avec le lieu comment compléter ses fiches, ou prévoyez un visuel de repli.
3. Étape 1 : la base et la clé
La base est libre. Seuls les chemins /venue, /events et /pages font partie du contrat. Choisissez une base claire et durable, par exemple https://www.ma-salle.fr/api/belle-prog/v1 ; elle sera déclarée telle quelle chez Belle Prog, et la changer plus tard demande de les prévenir.
La clé. Chaque appel du backend porte la clé d'API dans l'en-tête Authorization: Bearer <clé> et, en double, dans l'en-tête X-Belle-Prog-Key: <clé> (certains hébergeurs retirent l'en-tête Authorization avant qu'il n'atteigne votre code : acceptez l'un ou l'autre). Sans clé ou avec une mauvaise clé, répondez 401, avec un seul et même message dans les deux cas.
// PHP : la clé vient d'une variable d'environnement ou d'un fichier hors du dossier servi, jamais du code.
$auth = $_SERVER['HTTP_AUTHORIZATION'] ?? $_SERVER['REDIRECT_HTTP_AUTHORIZATION'] ?? '';
$given = preg_match( '/^Bearer\s+(.+)$/i', trim( $auth ), $m ) ? trim( $m[1] ) : trim( $_SERVER['HTTP_X_BELLE_PROG_KEY'] ?? '' );
if ( '' === $given || ! hash_equals( $apiKey, $given ) ) {
http_response_code( 401 );
header( 'Content-Type: application/json' );
exit( '{"error":"unauthorized"}' );
}
// Node (Express) : même chose, comparaison en temps constant.
import { timingSafeEqual } from 'node:crypto';
function keyOk(req) {
const given = (req.get('authorization') || '').replace(/^Bearer\s+/i, '').trim() || (req.get('x-belle-prog-key') || '').trim();
const a = Buffer.from(given), b = Buffer.from(process.env.API_KEY);
return a.length === b.length && timingSafeEqual(a, b);
}
app.use('/api/belle-prog/v1', (req, res, next) => (keyOk(req) ? next() : res.status(401).json({ error: 'unauthorized' })));
Les règles de sécurité, détaillées dans le README du kit : la clé hors du dépôt et hors du dossier servi (variable d'environnement ou fichier de configuration au-dessus du webroot) ; comparaison en temps constant (hash_equals, timingSafeEqual), jamais == ; ne jamais journaliser l'en-tête Authorization ; faire bloquer les 401 répétés par fail2ban ou le pare-feu de l'hébergeur. La clé ne protège qu'un agenda public, mais un endpoint mal protégé est une porte d'entrée sur le site.
Pour essayer à la main :
curl -i -H "Authorization: Bearer VOTRE_CLE" https://www.ma-salle.fr/api/belle-prog/v1/venue
4. Étape 2 : /venue, la fiche du lieu
Elle change rarement et le backend la lit une fois par jour. Vous pouvez l'écrire en dur dans le code ou la lire dans votre base, peu importe.
{
"schema_version": "1.0",
"generated_at": "2026-10-03T10:15:00+02:00",
"venue": {
"id": "ma-salle",
"name": "Ma Salle",
"address": "12 rue de la Musique",
"postal_code": "53000",
"city": "Laval",
"lat": 48.0733,
"lng": -0.7689,
"description": "Salle de musiques actuelles de 600 places au cœur de Laval. Concerts, découvertes et soirées club de septembre à juin.",
"image": { "url": "https://www.ma-salle.fr/images/facade.jpg", "width": 1200, "height": 675 },
"logo": { "url": "https://www.ma-salle.fr/images/logo-carre.png", "width": 512, "height": 512 },
"website": "https://www.ma-salle.fr",
"ticket_url": "https://billetterie.ma-salle.fr",
"socials": { "instagram": "https://www.instagram.com/masalle", "facebook": "https://www.facebook.com/masalle" },
"event_types": ["musique", "humour"]
}
}
L'enveloppe (schema_version, generated_at) est la même partout : "1.0" pour la version, et l'heure de génération avec son décalage horaire. Champ par champ :
| Champ | Requis | Ce qu'il faut savoir |
|---|---|---|
id | oui | exactement l'identifiant transmis par Belle Prog |
name | oui | 100 caractères au plus |
address, postal_code, city | address et city oui | rue et numéro ; la ville sert aux listes et à la carte |
lat, lng | oui | coordonnées du lieu, en degrés décimaux. Pour les trouver : adresse.data.gouv.fr (API gratuite, sans clé) |
description | oui | 1 000 caractères au plus, texte brut, montré sur la fiche du lieu |
notice, notice_at | non | message du lieu aux spectateurs (contrat 1.4), mêmes règles que sur un événement sans la limite des 30 jours : visible sept jours sur la fiche du lieu ; notifié seulement aux personnes qui ont allumé « Alertes de ce lieu » dans l'app. Quand il change, envoyez le webhook avec "sync_venue": true pour une prise en compte dans la minute (sinon le lendemain) |
image | oui | photo du lieu, horizontale, en HTTPS, avec ses dimensions réelles (section 5.3 pour les tailles) |
logo | non | carré, 512 × 512 au moins, sur fond plein : il s'affiche sur fond clair et sur fond sombre, la transparence rend mal. Absent, l'app affiche les initiales du nom |
website | oui | la page d'accueil du site |
ticket_url | non | billetterie générale ou abonnements, en bouton sur la fiche du lieu. Ce n'est pas un repli pour les événements : chaque événement porte son propre lien |
socials | non | liens instagram, facebook, tiktok, youtube, x, linkedin, bluesky, spotify, deezer, qobuz, tous optionnels |
event_types | non | ce que programme le lieu, du plus fréquent au plus rare, parmi les types de la section 5.1 (sauf festival et autre). Sert aux filtres « Lieux » et à la carte ; absent, le lieu n'apparaît dans aucun filtre par type |
Un festival ajoute kind: "festival" et un objet festival (édition, dates, scènes, couleurs) : section 8.
5. Étape 3 : /events, les dates
C'est le cœur du travail. Le backend l'appelle toutes les 15 minutes avec des filtres, et une fois par nuit sans filtre de modification pour retirer ce qui a disparu.
5.1 La requête
Quatre paramètres, tous optionnels. Les ignorer n'est pas une erreur, mais les respecter rend l'import plus léger pour vous comme pour Belle Prog.
| Paramètre | Défaut | À faire |
|---|---|---|
from=2026-10-03 | aujourd'hui, dans le fuseau du lieu | ne renvoyer que les événements dont le dernier jour (end_date, sinon le jour de start_date) est ≥ from. Un événement commencé hier qui finit demain doit sortir |
updated_since=2026-10-01T00:00:00+02:00 | aucun | ne renvoyer que ce dont updated_at ≥ cette valeur. Attention au + de l'offset, qui arrive parfois en espace s'il n'a pas été encodé dans l'adresse |
page=2, per_page=100 | 1, 100 | pagination ; per_page va de 1 à 500. Le backend enchaîne les pages lui-même |
5.2 La réponse
{
"schema_version": "1.0",
"generated_at": "2026-10-03T10:15:00+02:00",
"venue_id": "ma-salle",
"page": 1,
"per_page": 100,
"total": 3,
"events": [
{
"id": "ma-salle-4821",
"venue_id": "ma-salle",
"title": "Apéro-concert : Les Voisins d'en Face",
"start_date": "2026-10-09T19:00:00+02:00",
"image": { "url": "https://www.ma-salle.fr/images/voisins-den-face.jpg", "width": 1200, "height": 800 },
"event_url": "https://www.ma-salle.fr/agenda/apero-concert-les-voisins-den-face",
"is_free": true,
"status": "scheduled",
"updated_at": "2026-09-01T14:22:10+02:00",
"event_type": "musique",
"price": "Gratuit",
"excerpt": "Chanson française énergique pour lancer la saison, verre à la main.",
"doors_time": "18:30",
"genres": ["Chanson", "Pop"]
},
{
"id": "ma-salle-4835",
"venue_id": "ma-salle",
"title": "Sœurs Malsaines + Kalamity",
"start_date": "2026-10-17T20:30:00+02:00",
"image": { "url": "https://www.ma-salle.fr/images/soeurs-malsaines.jpg", "width": 1200, "height": 1200, "alt": "Sœurs Malsaines sur scène" },
"event_url": "https://www.ma-salle.fr/agenda/soeurs-malsaines-kalamity",
"ticket_url": "https://billetterie.ma-salle.fr/evenement/4835",
"is_free": false,
"status": "sold_out",
"updated_at": "2026-10-02T09:03:44+02:00",
"event_type": "musique",
"price": "14 € / 10 € réduit",
"description": "## Sœurs Malsaines\n\nRock garage rennais, deux guitares et une batterie qui ne s'excusent de rien.\n\n## Kalamity\n\nPunk rock lavallois en première partie."
},
{
"id": "ma-salle-expo-12",
"venue_id": "ma-salle",
"title": "Exposition : 20 ans d'affiches",
"start_date": "2026-11-03",
"end_date": "2026-11-28",
"image": { "url": "https://www.ma-salle.fr/images/expo-affiches.jpg", "width": 900, "height": 1200 },
"event_url": "https://www.ma-salle.fr/agenda/exposition-20-ans-daffiches",
"is_free": true,
"status": "scheduled",
"updated_at": "2026-08-20T11:00:00+02:00",
"event_type": "exposition",
"schedule_note": "Du mardi au samedi, 10h à 18h",
"location": { "name": "Médiathèque Albert Legendre", "city": "Laval" }
}
]
}
total est le nombre d'événements qui correspondent aux filtres, toutes pages confondues. L'ordre n'a pas d'importance : le backend trie lui-même. Les événements passés peuvent être omis, même sans from.
5.3 Champ par champ
Les neuf champs requis d'abord. Un seul qui manque, et l'événement est rejeté (les autres passent).
id — l'identifiant transmis par Belle Prog, un tiret, votre identifiant interne : ma-salle-4821. Minuscules, chiffres, ., _, -, 100 caractères au plus. La règle qui compte : il ne change jamais pour un même événement, même reporté, renommé ou modifié. C'est lui qui porte les favoris et les rappels des utilisateurs ; un id qui change, c'est un favori perdu et un doublon dans l'app. Jamais de slug, de titre ou de date dedans.
venue_id — l'identifiant du lieu, le même sur chaque événement et dans l'enveloppe.
title — 1 à 200 caractères, texte brut : pas de HTML, entités décodées (& devient &).
start_date — deux écritures possibles. Heure connue : date et heure avec le décalage horaire, 2026-10-17T20:30:00+02:00 (+02:00 en été, +01:00 en hiver, pour un lieu en France). Heure inconnue : le jour seul, 2026-11-03, et l'app n'affiche que le jour. Une heure sans décalage est rejetée ; une heure convertie en UTC (Z) est acceptée mais signale presque toujours un fuseau mal réglé côté serveur.
image — un objet { url, width, height }, et alt si vous l'avez. L'adresse est en HTTPS, accessible sans authentification, en JPEG, PNG ou WebP. width et height sont les dimensions réelles du fichier envoyé, pas celles d'une vignette ni d'une taille théorique. Taille recommandée : au moins 800 pixels de large et au plus 1 200 pixels sur le plus grand côté ; c'est ce que le téléphone affiche, et le backend n'a alors rien à redimensionner. Si vous avez plusieurs tailles, envoyez celle-là plutôt que l'original. Le backend copie l'image chez lui à l'import et la sert à l'app : votre serveur n'est pas sollicité par les utilisateurs.
event_url — la page publique de l'événement sur le site. Bouton « Voir sur le site », et lien de partage.
is_free — true ou false, toujours présent. Belle Prog ne déduit jamais la gratuité de l'absence d'un lien de billetterie ni d'un tarif vide. Si vous n'avez qu'un texte de tarifs, décidez d'une règle (« gratuit », « entrée libre ») et appliquez-la. Gratuit veut dire gratuit pour tout le monde : « gratuit pour les moins de 12 ans » sous « Tarif plein : 27 € » est une date payante, avec son texte de tarifs ; l'app n'afficherait sinon que « Gratuit » et la classerait parmi les dates gratuites.
status — scheduled (programmé), sold_out (complet), postponed (reporté), cancelled (annulé). Un changement vers cancelled, postponed ou sold_out, ou un retour à scheduled, notifie les utilisateurs qui ont la date en favori, comme un changement d'heure : c'est la raison d'être du champ, mettez-le à jour dès que le site le sait. Un événement annulé reste envoyé jusqu'à sa date, avec son statut ; ne le supprimez pas.
updated_at — la date de dernière modification, avec décalage. Elle doit changer à chaque modification visible : titre, heure, statut, visuel, tarif. C'est elle que lit le filtre updated_since.
Les optionnels ensuite. Envoyez-les seulement quand ils ont une valeur ; un champ absent ou null n'est jamais une erreur.
| Champ | Ce qu'il faut savoir |
|---|---|
end_date | le dernier jour d'un événement sur plusieurs jours (exposition, stage, festival), au format jour seul. Pas d'heure de fin dans le contrat. C'est elle qui décide quand l'événement disparaît de l'app |
event_type | un seul parmi musique, theatre, danse, cirque, arts-rue, humour, exposition, atelier, festival, conference, projection, autre. Absent = autre, qui n'apparaît dans aucun filtre : renseignez-le. Le public visé (jeune public, famille) n'est pas un type |
ticket_url | lien de billetterie de cet événement, en HTTPS ; un lien en http:// est retiré avec un avertissement. Présent, il donne le bouton « Billetterie » ; is_free et ticket_url peuvent coexister (gratuit sur réservation) |
price | texte libre, 200 caractères au plus : « 14 € / 10 € réduit » |
excerpt | résumé, 300 caractères au plus, texte brut |
description | texte complet de la fiche, 4 000 caractères au plus, texte brut avec une mise en forme légère : paragraphes séparés par une ligne vide, ## Titre et ### Sous-titre sur une ligne, - item pour une liste, **gras** et _italique_. Pas de HTML : convertissez-le, ou n'envoyez que le texte |
schedule_note | précision d'horaires sous la date, 300 caractères : « Ven. 20h30, sam. 18h et 20h30 » |
doors_time | ouverture des portes, HH:MM |
genres | jusqu'à 10 étiquettes de 40 caractères |
location | pour un événement hors les murs : { name, address?, postal_code?, city?, lat?, lng? }. Absent = dans le lieu. lat et lng vont ensemble |
media_url | un lien d'écoute ou de visionnage |
stage, country | scène d'un passage de festival ; pays de l'artiste |
notice, notice_at | message aux spectateurs de cette date (contrat 1.4) : 200 caractères de texte brut, sans lien, adresse ni numéro, posé au plus tôt 30 jours avant la date. L'app l'affiche en bandeau sur la fiche de la date et le notifie aux personnes qui l'ont en favori. notice_at est la date du message et doit changer à chaque modification du texte : c'est elle qui déclenche l'envoi. Un message vide ou absent retire le précédent. Un lieu peut envoyer un message par jour et cinq par semaine, tous messages confondus ; au-delà, le message est gardé mais pas notifié |
Vous pouvez ajouter vos propres champs : ils sont ignorés.
5.4 Ce qu'il ne faut pas envoyer
Le backend n'a aucun autre moyen de savoir ce qui ne doit pas être dans l'app. Filtrez chez vous : brouillons, dépubliés, événements privés, séances scolaires, répétitions, locations de salle, tout ce que le lieu ne veut pas voir affiché. Un événement qui cesse d'être envoyé est retiré de l'app à l'import complet suivant, dans la nuit.
5.5 Les cas qui reviennent
- Plusieurs représentations d'un même spectacle. Si votre modèle a une ligne par séance, envoyez un événement par séance, chacun avec son
id. Sinon un seul événement :start_datede la première,end_datede la dernière, et le détail dansschedule_note. - Heure pas encore connue. La date seule, puis la date et l'heure quand elles le sont ; le même
id, etupdated_atqui change. - Événement reporté. Même
id, nouvellestart_date,status: "postponed"tant que la nouvelle date n'est pas confirmée, puisscheduled. - Pas de visuel. L'événement sera rejeté. Un visuel de repli (celui du lieu, une image par type) vaut mieux qu'une absence, à condition d'avoir ses dimensions.
- Visuel sur un CDN ou un autre domaine. Possible, si l'adresse est en HTTPS et publique, et si Belle Prog connaît le domaine : les images ne sont copiées que depuis le site du lieu et les domaines autorisés, sinon l'événement garde son image précédente ou celle du lieu. Prévenez Belle Prog du domaine avant le premier import.
- Site multilingue. Une seule langue, chaque événement une seule fois.
- Gros agenda. Paginez (500 au plus par page) et gardez la réponse sous 2 Mo et 10 secondes ; le backend abandonne à 30 secondes. Vous pouvez mettre la réponse en cache jusqu'à 5 minutes.
6. Étape 4 : vérifier avec le validateur
Le kit contient un validateur en ligne de commande qui fait, en une minute, ce que fera le backend. Il faut Node 18 ou plus.
cd tools && npm install
node validate.mjs https://www.ma-salle.fr/api/belle-prog/v1 VOTRE_CLE
Il teste : la base en HTTPS ; 401 sans clé et avec une mauvaise clé ; /venue, /pages et /events contre les schémas JSON ; la cohérence des venue_id ; l'unicité et la stabilité des id entre deux appels ; le filtre from ; le décalage horaire des dates ; les images en HTTPS et leur accessibilité (il en télécharge l'en-tête) ; la validité des adresses ; la pagination ; le filtre updated_since ; le temps et la taille de la réponse. Il finit par « Conforme » ou par la liste de ce qui bloque. Options : --from 2024-01-01 pour tester sur des dates passées quand l'agenda à venir est vide, --allow-http pour un serveur local, --json pour une sortie machine.
En ligne, sans rien installer. La même vérification se fait sur belle-prog.fr/verifier : le choix « Le point d'accès du kit » est déjà fait, collez la base et la clé. Les contrôles et les messages sont ceux de la ligne de commande, au mot près. Deux différences : la base doit être en HTTPS et joignable depuis Internet, et le début d'une réponse en erreur n'est pas cité. La clé sert le temps de la vérification, elle n'est ni gardée ni journalisée. Pour un site encore sur votre poste, gardez la ligne de commande et --allow-http.
Ce que signifient les messages les plus fréquents :
| Message | Cause probable | Correction |
|---|---|---|
Sans clé → 401 — Reçu 200 | la route répond avant la vérification de la clé | vérifier la clé avant tout traitement, sur les deux routes |
/events conforme au schéma — /events/0/start_date must match pattern | heure sans décalage, ou format maison | 2026-10-17T20:30:00+02:00, ou le jour seul |
… /events/2/image must have required property 'width' | dimensions absentes | lire la largeur et la hauteur du fichier et les envoyer en entiers |
… /events/4/is_free must be boolean | "oui", 1, null | true ou false, toujours |
Filtre from respecté — 3 événement(s) terminés avant … | filtre sur le premier jour au lieu du dernier, ou from ignoré | comparer end_date sinon start_date à from |
Images en HTTPS | adresses d'images en http:// | servir les images en HTTPS |
Images accessibles — 2 sur 5 … ne répondent pas en HEAD | images protégées, absentes, ou serveur qui refuse HEAD | rendre les images publiques, autoriser HEAD |
Identifiants stables — N identifiant(s) ont changé | id calculé depuis la position, un hachage du contenu ou un slug | l'identifiant interne, préfixé |
Offset sur les datetimes | dates stockées sans fuseau et renvoyées telles quelles | formater avec le fuseau du lieu |
Fuseau horaire — Tous les horaires sont en UTC (avertissement) | conversion en UTC côté serveur | formater dans le fuseau du lieu : +01:00 / +02:00 |
Pagination (avertissement) | page ou per_page ignorés, ou total qui change avec la page | appliquer les deux ; total compte toutes les pages |
Filtre updated_since — Paramètre ignoré (avertissement) | le filtre n'est pas appliqué | acceptable, mais chaque import relira tout l'agenda |
Un avertissement n'empêche pas la mise en service ; une erreur, oui.
7. Étape 5 : mise en service
- Quand le validateur dit « Conforme », envoyez la base à Belle Prog.
- Belle Prog déclare le lieu avec cette base et lance un premier import en mode essai : les données sont importées et contrôlées, mais invisibles dans l'app. Belle Prog vérifie quelques dates au hasard avec vous, puis passe le lieu en actif : il apparaît dans l'app.
- Ensuite, tout est automatique :
/eventstoutes les 15 minutes avecupdated_since, un import complet chaque nuit pour retirer ce qui a disparu,/venueet/pagesune fois par jour. Un événement sort de l'app après la fin de sa journée (end_date, sinonstart_date), quel que soit son statut. - Si votre site répond en erreur (
5xx, délai dépassé, JSON invalide), rien n'est modifié : le backend garde les données du dernier import réussi. Trois imports consécutifs en échec déclenchent une alerte chez Belle Prog, qui vous contacte. - Si vous changez la base, ou si la clé a pu fuiter (vue dans un dépôt, un ticket, une capture d'écran), prévenez Belle Prog : la clé se régénère depuis leur tableau de bord et prend effet immédiatement.
7.1 Optionnel : le webhook, pour une mise à jour dans la minute
Sans lui, une modification est visible dans l'app dans le quart d'heure. Avec lui, dans la minute. Après chaque publication, modification, dépublication ou changement de statut, envoyez un POST à l'adresse fournie par Belle Prog pour votre lieu, avec ce corps :
{ "venue_id": "ma-salle", "event_id": "ma-salle-4821", "sent_at": "2026-10-03T10:15:00+02:00" }
event_id est optionnel. L'en-tête X-Agenda-Signature porte le HMAC-SHA256 du corps brut, avec le secret webhook de votre lieu, en hexadécimal. Le backend vérifie la signature, refuse un sent_at de plus de 5 minutes, répond 202 et importe votre lieu dans la minute. Il ne lit aucune donnée d'événement dans le webhook : c'est un simple signal, il relit ensuite /events. Un import par lieu et par minute au plus, quel que soit le nombre de webhooks.
Retrait immédiat (contrat 1.5). L'import de la minute ne lit que ce qui a changé : un événement que vous cessez d'envoyer lui est invisible, et il ne disparaît qu'à l'import complet de la nuit. Pour qu'il parte tout de suite, ajoutez "removed": ["ma-salle-4821"] au corps du webhook quand un événement quitte votre flux (dépublié, supprimé, passé en privé, exclu par une règle) : le backend le retire sur-le-champ, avec ses représentations (ma-salle-4821-2). Cent identifiants au plus, les vôtres seulement. S'il revient dans votre flux, l'import suivant le réécrit.
$body = json_encode( [ 'venue_id' => 'ma-salle', 'event_id' => 'ma-salle-4821', 'sent_at' => date( 'c' ) ] );
$signature = hash_hmac( 'sha256', $body, $webhookSecret );
// POST $webhookUrl, en-têtes : Content-Type: application/json et X-Agenda-Signature: $signature
import { createHmac } from 'node:crypto';
const body = JSON.stringify({ venue_id: 'ma-salle', event_id: 'ma-salle-4821', sent_at: new Date().toISOString() });
const signature = createHmac('sha256', process.env.WEBHOOK_SECRET).update(body).digest('hex');
await fetch(process.env.WEBHOOK_URL, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Agenda-Signature': signature }, body });
8. Festivals
Un festival est une source comme une autre : mêmes adresses, même clé, même cadence d'import. Ce qui change tient en quatre points : la fiche dit qu'elle est un festival et décrit l'édition ; chaque passage porte sa scène ; le programme couvre toute l'édition, jours passés compris ; et /pages sert les infos pratiques. Dans l'app, un festival a son propre écran, à ses couleurs, avec trois onglets : Programme (par jour, par scène ou alphabétique, filtre par scène, cœur favori sur chaque ligne), Favoris et Infos (pages, réseaux, lieu, bouton « Billetterie » vers le site). Un passage mis en favori déclenche un rappel 15 minutes avant, et une notification s'il est annulé, déplacé ou si son horaire change.
8.1 La fiche : kind et festival
{
"schema_version": "1.1",
"generated_at": "2027-06-01T10:00:00+02:00",
"venue": {
"id": "festival-demo",
"kind": "festival",
"name": "Festival Démo",
"address": "Fort Saint-Père",
"postal_code": "35430",
"city": "Saint-Père-Marc-en-Poulet",
"lat": 48.5836,
"lng": -1.9302,
"description": "Trois jours de musiques actuelles sur les remparts.",
"image": { "url": "https://www.festival-demo.fr/img/festival.jpg", "width": 1200, "height": 675 },
"website": "https://www.festival-demo.fr",
"ticket_url": "https://www.festival-demo.fr/billetterie/",
"socials": { "instagram": "https://www.instagram.com/festivaldemo" },
"festival": {
"edition": "2027",
"start_date": "2027-08-13",
"end_date": "2027-08-15",
"day_cutoff_hour": 6,
"stages": ["Scène des Remparts", "Scène du Fort"],
"theme": {
"accent": "#FF4100",
"background": "#1D0E2A",
"hero_image": { "url": "https://www.festival-demo.fr/img/affiche-2027.jpg", "width": 1200, "height": 675 }
}
}
}
}
Les champs de la fiche sont ceux d'un lieu (section 4) : le site du festival, son lieu principal, sa billetterie générale (l'app n'intègre aucune billetterie : le bouton ouvre votre site). S'y ajoutent kind et l'objet festival :
| Champ | Requis | Ce qu'il faut savoir |
|---|---|---|
kind | oui | "festival" |
festival.edition | oui | le libellé de l'édition servie, 40 caractères au plus : « 2027 », « 25e édition » |
festival.start_date, festival.end_date | non | premier et dernier jour de l'édition servie, au format jour seul. À omettre toutes les deux tant que la prochaine édition n'a pas de dates : l'app affiche alors « Prochaine édition à venir » |
festival.day_cutoff_hour | non, défaut 6 | entier de 0 à 11. Un passage qui commence avant cette heure appartient à la journée de la veille : un set à 1 h 15 le dimanche est programmé « samedi » |
festival.stages | non | les scènes, dans l'ordre d'affichage, 30 au plus, 60 caractères chacune. Chaque passage reprend l'une d'elles dans stage, écrite à l'identique |
festival.theme | non | accent et background en hexadécimal #RRGGBB (fond sombre, accent vif et lisible dessus) ; hero_image, l'affiche ou le visuel d'accueil, objet Image comme les autres |
8.2 Les passages
Un passage est un événement ordinaire (section 5), avec deux champs en plus : stage et country. Deux soirées, trois passages :
[
{
"id": "festival-demo-2027-412",
"venue_id": "festival-demo",
"title": "Orbital Sisters",
"start_date": "2027-08-13T23:30:00+02:00",
"image": { "url": "https://www.festival-demo.fr/img/orbital-sisters.jpg", "width": 1200, "height": 1200 },
"event_url": "https://www.festival-demo.fr/programmation/orbital-sisters/",
"is_free": false,
"status": "scheduled",
"updated_at": "2027-06-01T10:00:00+02:00",
"event_type": "musique",
"stage": "Scène des Remparts",
"country": "France",
"genres": ["Électro"],
"excerpt": "Deux sœurs, deux machines, une heure sans reprendre son souffle.",
"media_url": "https://www.youtube.com/watch?v=xxxxxxxxxxx"
},
{
"id": "festival-demo-2027-418",
"venue_id": "festival-demo",
"title": "Kalamity",
"start_date": "2027-08-14T01:15:00+02:00",
"image": { "url": "https://www.festival-demo.fr/img/kalamity.jpg", "width": 1200, "height": 1200 },
"event_url": "https://www.festival-demo.fr/programmation/kalamity/",
"is_free": false,
"status": "scheduled",
"updated_at": "2027-06-01T10:00:00+02:00",
"event_type": "musique",
"stage": "Scène du Fort",
"country": "Belgique",
"genres": ["Punk rock"]
},
{
"id": "festival-demo-2027-431",
"venue_id": "festival-demo",
"title": "Fanfare du Fort",
"start_date": "2027-08-14T18:00:00+02:00",
"image": { "url": "https://www.festival-demo.fr/img/fanfare.jpg", "width": 1200, "height": 800 },
"event_url": "https://www.festival-demo.fr/programmation/fanfare-du-fort/",
"is_free": true,
"status": "scheduled",
"updated_at": "2027-06-01T10:00:00+02:00",
"event_type": "musique",
"stage": "Place du village",
"location": { "name": "Place du village", "city": "Saint-Père-Marc-en-Poulet", "lat": 48.5861, "lng": -1.9240 }
}
]
Ce qui compte pour un passage :
start_dateest l'heure réelle du set, avec son décalage horaire. Kalamity joue à 1 h 15 dans la nuit du 13 au 14 : la date est bien le 14 août, et c'est l'app qui, avecday_cutoff_hour, le range dans la soirée du samedi 13. N'écrivez jamais « 25h15 » ni la date de la veille.titleest le nom de l'artiste,genresson genre,countryson pays,excerptsa bio courte etdescriptionsa bio complète,media_urlun clip ou une écoute,imagesa photo (le carré passe bien).stagereprend l'un des noms defestival.stages, écrit à l'identique : c'est la clé du tri par scène. Un passage sans scène reste affiché, sans filtre.is_free:falsepour les passages compris dans le billet,truepour une scène gratuite ou un off en accès libre. Pas besoin deticket_urlsur chaque passage : la billetterie du festival est sur la fiche.- Festival sur plusieurs lieux (une ville, plusieurs salles) :
stageporte le nom du lieu, etlocationses coordonnées. L'app affiche alors les adresses sans champ supplémentaire. - Un seul
idpar passage, unique d'une édition à l'autre : votre identifiant interne, avec l'édition si vos identifiants se répètent d'une année sur l'autre (festival-demo-2027-412). Un artiste qui revient l'an prochain est un nouveau passage. - Annulation, changement de scène ou d'horaire : même
id,statusoustart_datemis à jour,updated_atqui change. Les favoris sont prévenus. Pendant l'édition, le webhook (section 7.1) fait passer le délai de quinze minutes à une minute : c'est le moment où il compte.
Tout le programme, jours passés compris. Tant qu'une édition est servie, renvoyez tous ses passages depuis son premier jour, même ceux déjà joués ; le filtre from ne s'applique qu'en dehors de l'édition. Le backend les conserve tant que l'édition est servie, l'app montre les jours passés dans le programme, et le validateur accepte les passages à partir de festival.start_date. Une salle, elle, ne renvoie que l'avenir.
8.3 Le cycle d'une édition
Le contrat ne sert qu'une édition à la fois : celle en cours, la prochaine, ou la dernière terminée.
- Avant l'annonce des dates :
festivalaveceditionseule, sansstart_dateniend_date, eteventsvide. L'app affiche « Prochaine édition à venir ». - Dates connues : les deux bornes, et les passages au fil des annonces. Chaque nom annoncé est un passage de plus ; les horaires et les scènes peuvent venir après (la date seule, puis la date et l'heure, même
id). - Pendant : statuts, horaires et scènes à jour, webhook actif.
- Après : continuez de servir l'édition terminée, dates et passages compris, jusqu'à l'annonce de la suivante. L'app affiche « Édition 2027 terminée : son programme reste consultable jusqu'à l'annonce de la suivante ». Le lendemain de la clôture, le festival ne doit pas se vider.
- Bascule : quand la suivante est annoncée, changez
editionet les dates, et cessez d'envoyer les anciens passages ; le backend les retire à l'import complet suivant.
Un festival à deux éditions par an (été et hiver, par exemple) est une seule source : servez l'édition en cours ou la plus proche, puis l'autre.
8.4 /pages : les infos pratiques
Accès, camping, horaires, restauration, contact… des pages courtes que l'app garde hors connexion, précieuses sur un site de festival sans réseau. Lues une fois par jour avec la fiche. Une salle peut aussi s'en servir (accès, accessibilité). Sans pages : 404, ou une liste vide.
{
"schema_version": "1.1",
"generated_at": "2027-06-01T10:00:00+02:00",
"pages": [
{
"id": "acces",
"title": "Accès et parkings",
"order": 1,
"icon": "access",
"kind": "page",
"content_html": "<h2>Venir au festival</h2><p>Navettes gratuites depuis la gare toutes les 20 minutes, de 17h à 3h.</p><ul><li>Parking P1 : voitures</li><li>Parking P2 : covoiturage</li></ul>",
"url": "https://www.festival-demo.fr/infos/acces/",
"updated_at": "2027-06-01T10:00:00+02:00"
},
{
"id": "camping",
"title": "Camping",
"order": 2,
"icon": "camping",
"kind": "page",
"content_html": "<p>Ouvert du vendredi 14h au dimanche 14h. Gratuit avec un billet.</p><img src=\"https://www.festival-demo.fr/img/camping.jpg\" alt=\"Le camping\">",
"updated_at": "2027-06-01T10:00:00+02:00"
},
{
"id": "billetterie",
"title": "Billetterie",
"order": 3,
"icon": "tickets",
"kind": "link",
"url": "https://www.festival-demo.fr/billetterie/",
"updated_at": "2027-06-01T10:00:00+02:00"
}
]
}
| Champ | Requis | Ce qu'il faut savoir |
|---|---|---|
id | oui | stable, même motif que les autres identifiants (acces, camping) |
title | oui | 100 caractères au plus |
order | non | ordre d'affichage |
icon | non | parmi info, access, parking, camping, food, schedule, map, safety, accessibility, contact, tickets, faq, kids, eco, shop, volunteer, press, partners, other. Inconnue : icône générique |
kind | oui | page : contenu embarqué dans l'app ; link : simple lien, ouvert dans le navigateur du téléphone |
content_html | si page | 200 000 caractères au plus, dans un sous-ensemble HTML : h2 à h4, p, ul, ol, li, a, img, strong, em, br. Tout le reste est retiré par le backend ; pas de script, de vidéo intégrée ni de formulaire : un lien à la place. Les images, en HTTPS et sur le domaine du festival, sont copiées pour le hors connexion |
url | si link | pour une page, facultatif : la même page sur votre site, derrière « Voir cette page sur le site » |
updated_at | oui | date de dernière modification |
Cinquante pages au plus. Une page de type page sans content_html s'affiche « Page indisponible » : si vous préférez renvoyer vers le site, déclarez-la en link.
8.5 Ce que le validateur vérifie en plus
La cohérence de l'édition (end_date après start_date), le nombre de scènes, le schéma de /pages quand l'endpoint existe, et le filtre from avec le plancher au premier jour de l'édition. Sur WordPress, l'exemple du kit couvre tout cela : bloc « festival » en tête de fichier, scène depuis une taxonomie ou un champ, pages depuis des pages WordPress. Exemples complets : examples/venue-festival.json, examples/pages.json. Le modèle en détail : docs/FESTIVALS.md.
9. Questions fréquentes
Mon hébergeur retire l'en-tête Authorization. Lisez X-Belle-Prog-Key, envoyé à chaque appel.
Je n'ai pas d'heure de fin. Le contrat n'en veut pas. end_date est le dernier jour, sans heure.
Je n'ai pas les dimensions de mes images. Lisez-les une fois (getimagesize en PHP, sharp ou image-size en Node) et stockez-les ; ne les devinez pas.
Mes dates sont stockées en UTC. Convertissez-les dans le fuseau du lieu avant de les formater : 2026-10-17T20:30:00+02:00, pas 18:30:00Z.
Un événement a été supprimé du site. Ne l'envoyez plus : il sera retiré à l'import complet de la nuit. Pour que ce soit immédiat, envoyez le webhook avec son identifiant dans removed (section 7.1).
Mon festival a deux éditions par an. Une seule source, qui sert l'édition en cours ou la plus proche, puis l'autre : le contrat n'expose qu'une édition à la fois (section 8.3).
Puis-je tester sans données à venir ? Oui, node validate.mjs <base> <clé> --from 2024-01-01 teste sur des dates passées. Et les exemples du kit (PHP, Node) se lancent tels quels avec des données de démonstration.
Puis-je développer en local, en HTTP ? Pour le validateur, oui, avec --allow-http. Le backend, lui, n'appelle qu'une base en HTTPS.
Que vaut schema_version ? "1.0" pour une salle, "1.1" si vous servez un festival ou /pages. Le backend accepte toute version 1.x ; les champs ajoutés au fil des versions (festivals, description, event_types…) sont tous optionnels.
Je veux ajouter mes propres champs. Ils sont ignorés.
Combien d'appels recevrai-je ? Environ une centaine par jour : /events toutes les 15 minutes, /venue et /pages une fois par jour, plus un appel par webhook (un par minute au plus).
10. Avant d'envoyer la base
- Les deux adresses répondent en HTTPS, en JSON, et
401sans clé comme avec une mauvaise clé. schema_versionvaut"1.0"etvenue_idvaut l'identifiant transmis, partout.- Chaque
idest stable : la même valeur à chaque appel, même après modification ; votre identifiant interne, préfixé. - Toutes les dates avec heure ont un décalage horaire ; les dates sans heure sont au format jour seul.
updated_atchange à chaque modification ;is_freeetstatussont toujours présents.- Les images sont en HTTPS, publiques, avec leurs dimensions réelles ; 800 à 1 200 px de préférence.
- Les textes sont sans HTML, entités décodées.
- Rien de dépublié, de privé ou de scolaire ne sort.
from,updated_since,pageetper_pagesont pris en compte, ou à défaut ignorés sans erreur.- Festival :
kind,festival.editionet les dates de l'édition ; tous les passages de l'édition, même passés, avecstageparmifestival.stages; l'édition terminée reste servie jusqu'à la suivante. node tools/validate.mjs <base> <clé>affiche « Conforme », ou la vérification en ligne de belle-prog.fr/verifier.
Les fichiers du kit
| Fichier | Rôle |
|---|---|
GUIDE.html | ce guide en une page, à ouvrir dans un navigateur, à imprimer ou à envoyer tel quel |
README.md | le pense-bête : règles, sécurité, questions fréquentes |
CONTRAT-V1.md | la spécification, qui fait foi |
openapi.yaml | la description OpenAPI 3.1, à importer dans Postman, Insomnia ou un générateur de client |
*.schema.json | les schémas JSON (2020-12) pour valider vos réponses dans vos tests |
examples/*.json | des réponses conformes, salle et festival |
examples/implementation-php/, examples/implementation-node/ | deux implémentations complètes à adapter, qui se lancent telles quelles |
examples/implementation-wordpress/ | un WordPress sans l'extension Belle Prog |
tools/validate.mjs | le validateur ; ses contrôles sont dans tools/validate-core.mjs, que la vérification en ligne utilise aussi |