Guide du développeur — brancher un site sur Belle Prog

Contrat de données v1 · kit développeur contract/v1/

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é :

AdresseContenuLue
GET <base>/venuela fiche du lieu : nom, adresse, coordonnées, visuel, siteune fois par jour
GET <base>/eventsles dates à venir, avec quelques filtrestoutes les 15 minutes
GET <base>/pagesoptionnel : 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

Il fautChez vous, typiquement
un identifiant interne stablela clé primaire de l'événement, jamais son titre ni son slug
le titre
le premier jour, et l'heure si elle est connuedate 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 pixelsl'image de l'événement et ses dimensions (à lire dans le fichier ou en base)
la page de l'événement sur le siteson adresse publique
gratuit ou payant, dit explicitementune 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 modificationupdated_at de l'enregistrement
ce qui est publié et ce qui ne l'est pasvotre 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 :

ChampRequisCe qu'il faut savoir
idouiexactement l'identifiant transmis par Belle Prog
nameoui100 caractères au plus
address, postal_code, cityaddress et city ouirue et numéro ; la ville sert aux listes et à la carte
lat, lngouicoordonnées du lieu, en degrés décimaux. Pour les trouver : adresse.data.gouv.fr (API gratuite, sans clé)
descriptionoui1 000 caractères au plus, texte brut, montré sur la fiche du lieu
notice, notice_atnonmessage 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)
imageouiphoto du lieu, horizontale, en HTTPS, avec ses dimensions réelles (section 5.3 pour les tailles)
logononcarré, 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
websiteouila page d'accueil du site
ticket_urlnonbilletterie 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
socialsnonliens instagram, facebook, tiktok, youtube, x, linkedin, bluesky, spotify, deezer, qobuz, tous optionnels
event_typesnonce 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ètreDéfautÀ faire
from=2026-10-03aujourd'hui, dans le fuseau du lieune 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:00aucunne 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=1001, 100pagination ; 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 (&amp; 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.

ChampCe qu'il faut savoir
end_datele 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_typeun 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_urllien 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)
pricetexte libre, 200 caractères au plus : « 14 € / 10 € réduit »
excerptrésumé, 300 caractères au plus, texte brut
descriptiontexte 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_noteprécision d'horaires sous la date, 300 caractères : « Ven. 20h30, sam. 18h et 20h30 »
doors_timeouverture des portes, HH:MM
genresjusqu'à 10 étiquettes de 40 caractères
locationpour un événement hors les murs : { name, address?, postal_code?, city?, lat?, lng? }. Absent = dans le lieu. lat et lng vont ensemble
media_urlun lien d'écoute ou de visionnage
stage, countryscène d'un passage de festival ; pays de l'artiste
notice, notice_atmessage 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

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 :

MessageCause probableCorrection
Sans clé → 401 — Reçu 200la 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 patternheure sans décalage, ou format maison2026-10-17T20:30:00+02:00, ou le jour seul
… /events/2/image must have required property 'width'dimensions absenteslire la largeur et la hauteur du fichier et les envoyer en entiers
… /events/4/is_free must be boolean"oui", 1, nulltrue 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 HTTPSadresses d'images en http://servir les images en HTTPS
Images accessibles — 2 sur 5 … ne répondent pas en HEADimages protégées, absentes, ou serveur qui refuse HEADrendre les images publiques, autoriser HEAD
Identifiants stables — N identifiant(s) ont changéid calculé depuis la position, un hachage du contenu ou un slugl'identifiant interne, préfixé
Offset sur les datetimesdates stockées sans fuseau et renvoyées telles quellesformater avec le fuseau du lieu
Fuseau horaire — Tous les horaires sont en UTC (avertissement)conversion en UTC côté serveurformater dans le fuseau du lieu : +01:00 / +02:00
Pagination (avertissement)page ou per_page ignorés, ou total qui change avec la pageappliquer 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

  1. Quand le validateur dit « Conforme », envoyez la base à Belle Prog.
  2. 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.
  3. Ensuite, tout est automatique : /events toutes les 15 minutes avec updated_since, un import complet chaque nuit pour retirer ce qui a disparu, /venue et /pages une fois par jour. Un événement sort de l'app après la fin de sa journée (end_date, sinon start_date), quel que soit son statut.
  4. 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.
  5. 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 :

ChampRequisCe qu'il faut savoir
kindoui"festival"
festival.editionouile libellé de l'édition servie, 40 caractères au plus : « 2027 », « 25e édition »
festival.start_date, festival.end_datenonpremier 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_hournon, défaut 6entier 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.stagesnonles 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.themenonaccent 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 :

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.

  1. Avant l'annonce des dates : festival avec edition seule, sans start_date ni end_date, et events vide. L'app affiche « Prochaine édition à venir ».
  2. 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).
  3. Pendant : statuts, horaires et scènes à jour, webhook actif.
  4. 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.
  5. Bascule : quand la suivante est annoncée, changez edition et 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"
    }
  ]
}
ChampRequisCe qu'il faut savoir
idouistable, même motif que les autres identifiants (acces, camping)
titleoui100 caractères au plus
ordernonordre d'affichage
iconnonparmi 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
kindouipage : contenu embarqué dans l'app ; link : simple lien, ouvert dans le navigateur du téléphone
content_htmlsi page200 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
urlsi linkpour une page, facultatif : la même page sur votre site, derrière « Voir cette page sur le site »
updated_atouidate 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 fichiers du kit

FichierRôle
GUIDE.htmlce guide en une page, à ouvrir dans un navigateur, à imprimer ou à envoyer tel quel
README.mdle pense-bête : règles, sécurité, questions fréquentes
CONTRAT-V1.mdla spécification, qui fait foi
openapi.yamlla description OpenAPI 3.1, à importer dans Postman, Insomnia ou un générateur de client
*.schema.jsonles schémas JSON (2020-12) pour valider vos réponses dans vos tests
examples/*.jsondes 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.mjsle validateur ; ses contrôles sont dans tools/validate-core.mjs, que la vérification en ligne utilise aussi