Tout ce qu'il faut pour faire tourner Balisio.

Guides pas-à-pas, référence API, exemples copier-coller. Cette documentation reflète exactement ce qui est livré aujourd'hui · le calendrier des éléments en feuille de route est précisé en bas de chaque section concernée.

Introduction

Balisio est une plateforme de concertation citoyenne pour les communes, EPCI, métropoles et cabinets de concertation. Chaque projet vit dans un espace agent (création, configuration, ingestion, modération, synthèse) et expose une page publique mobile-first où les habitants contribuent en moins de deux minutes.

Trois acteurs · le résident dépose une contribution géolocalisée, l'IA Mistral modère et classe par thème en continu, l'agent territorial déclenche un rapport DOCX/PDF prêt à signer.

Créer un premier projet

1. Connectez-vous à l'espace agent depuis trame · espace client.
2. Cliquez sur + Nouveau projet. Renseignez · nom, format (libre / carte / signalement / questionnaire / etc.), type (PLU / mobilité / aménagement / etc.).
3. Vous arrivez sur la fiche projet. L'onglet Réglages contient les champs détaillés (dates, périmètre, base légale, signataire, thèmes, statut, FranceConnect).
4. L'onglet Carte du projet permet de dessiner zones, tracés et points qui apparaîtront sur la page publique.
5. L'onglet Documents publie les annexes téléchargeables visibles par les citoyens.
6. Quand vous êtes prêt, basculez le statut sur En cours. La page publique est instantanément accessible.

Pré-remplir depuis un document

Si vous disposez de la délibération, d'une note de cadrage ou d'un arrêté, l'IA peut pré-remplir la fiche projet pour vous.

1. Dans l'espace agent, ouvrez votre projet.
2. Cliquez sur Importer un dossier (en haut à droite, ou depuis la bannière bleue dans Réglages).
3. Glissez le PDF / DOCX / texte. mistral-large-latest extrait nom, dates, périmètre, base légale, signataire et thèmes.
4. Validez champ par champ · chaque proposition affiche un score de confiance (vert ≥ 85 %, orange 60-85 %, rouge < 60 %).
5. Cliquez Enregistrer. Tous les champs validés sont commités sur le projet.

Publier la consultation

La page publique est servie à /consultations/{slug}.html. Toutes les contributions y sont visibles dès qu'elles passent la modération (mistral-small en moins de 2 secondes).

Plusieurs canaux de partage depuis l'onglet Vue d'ensemble · lien direct, code embed iframe, QR code, code court à imprimer.

Documents publics

L'onglet Documents dans l'espace agent contient deux cartes ·

• Document de référence pour pré-remplissage IA · ouvre l'assistant d'import (cf. ci-dessus).
• Documents publics · annexes téléchargeables · plans, études, comptes rendus, vidéos. Limite 25 Mo par fichier. Liste des extensions acceptées · pdf, docx, jpg, png, mp4, csv, zip, etc.

Chaque fichier ajouté apparaît instantanément sur la page publique de la consultation, dans l'onglet Documents du projet, avec un lien de téléchargement nommé d'après le fichier original.

Sources de données

L'onglet Sources de données permet de relier Balisio à un sondage déjà lancé ou à votre système interne. 9 connecteurs configurables · 2 actifs aujourd'hui (CSV / Excel + Webhook entrant), 7 en cours de cablage (cf. API).

Carte du projet

L'éditeur cartographique de l'onglet Carte du projet propose trois outils ·

• Zone (polygone) · périmètres d'aménagement, secteurs sauvegardés.
• Tracé (polyligne) · pistes cyclables, voies piétonnes, lignes de tram.
• Point · écoles, commerces, arrêts, équipements clés.

Cinq couleurs DSFR · Bleu France, Vert (mobilité douce), Rouge Marianne (zone clé), Orange (travaux), Gris (référence). Cliquez Publier sur la page publique pour synchroniser. Export GeoJSON disponible pour vos services SIG.

Raccourcis clavier · Échap annule, Entrée ou double-clic termine un tracé.

Courriers automatisés

L'onglet Communication propose trois templates de courrier officiel ·

• Convocation à réunion publique · objet, date, lieu, ordre du jour structuré.
• Lettre d'information aux riverains · texte pré-rédigé + QR code de la consultation intégré.
• Accusé de réception · numéro de référence auto-généré, mention LCEN art. 6 + RGPD.

Chaque template propose Imprimer / PDF (ouvre une fenêtre A4 print-styled, vous choisissez votre imprimante ou « Enregistrer en PDF ») et Copier le texte (presse-papier, pour coller dans Word).

Rapports DOCX/PDF

Le bouton Générer la synthèse · Mistral-large sur la Vue d'ensemble déclenche le pipeline complet ·

1. Re-classification de toutes les contributions (mistral-small).
2. Synthèse multi-niveaux · résumé exécutif, top-thèmes pondérés, dissensions, 3-5 verbatims sourcés par thème (mistral-large).
3. Vérification que chaque citation correspond à une contribution réelle (sinon le rapport est bloqué).
4. Génération DOCX et PDF prêts pour le dossier de concertation, avec audit-id et fingerprint cryptographique.

Format libre · carte · signalement

Recueil ouvert. Chaque contribution est modérée puis classifiée dans 1 des 15 thèmes (sécurité, voirie, mobilité, propreté, espaces verts, bruit, etc.). Visible immédiatement sur la page publique.

Base légale · CGCT L. 2143-3 (comités consultatifs).

Votation officielle

Vote binaire ou QCM. FranceConnect obligatoire pour la validité juridique. Quorum et seuil paramétrables. Les bulletins sont anonymisés à la clôture.

L'onglet Format · Votation officielle affiche · question soumise au vote, KPIs (participation, quorum, statut), barres « Pour » / « Contre » avec %. Export PV PDF.

Base légale · CGCT L. 1112-15 (consultations locales).

Budget participatif

Les habitants notent les projets et répartissent une enveloppe (vote pondéré). Balisio respecte la sélection sous contrainte budgétaire à la clôture · les projets sont marqués retenu, en lice ou budget dépassé.

Pétition citoyenne

Collecte de signatures avec seuil légal. Suivi en temps réel, export CSV des signataires (date, prénom, nom, code postal). Une pétition au-delà du seuil déclenche une mise à l'agenda du conseil municipal.

Registre dématérialisé

Pour les enquêtes publiques. Chaque observation est horodatée et immuable conformément à R. 123-9 du Code de l'environnement. Les réponses du commissaire-enquêteur sont publiées sur le registre public.

API · vue d'ensemble

Tous les endpoints sont préfixés par https://<votre-instance> · en développement local par défaut http://127.0.0.1:8001.

Authentification · token Bearer pour les endpoints d'administration (cf. SDK). Les endpoints publics (page citoyenne, ingestion webhook signée) ne demandent pas de token.

Projets & consultations

IA Mistral · Atelier

Sources de données & pièces jointes

Observatoire (résident · agent)

Compte & SDK

Pilotage & recherche

Authentification (mode local · email à brancher)

Ingestion CSV / Excel

Téléverser un export tabulaire dont chaque ligne devient une contribution. Balisio détecte automatiquement la colonne du texte (préférences · reponse, commentaire, texte, avis, message, comment, response, observation, contribution) ou prend la colonne médiane la plus longue.

# Upload depuis le terminal
curl -X POST "http://127.0.0.1:8001/api/consultations/centre-ville/sources/csv" \
  -F "[email protected]"

# Réponse
{
  "consultation": "centre-ville",
  "text_column": "reponse",
  "inserted": 142,
  "deduplicated": 8,
  "skipped": 0,
  "channel": "libre"
}

Chaque ligne ingérée passe ensuite dans le pipeline standard · modération mistral-small puis classification thématique.

Webhook entrant

Authentification par HMAC SHA-256 obligatoire sur chaque requête entrante.

Balisio génère un endpoint et un secret HMAC par projet. Vous y poussez chaque nouvelle réponse depuis votre système.

1. Provisionner le secret

curl -X POST "http://127.0.0.1:8001/api/consultations/centre-ville/sources/webhook/secret"

# Réponse · conservez le secret côté client
{
  "endpoint": "/api/consultations/centre-ville/sources/webhook",
  "secret": "whsec_B8TbyNj6p9yFXpeStitwXrT2gRReQz_iSZwt2Hcbm2Y",
  "signature_header": "X-Balisio-Signature",
  "algorithm": "sha256"
}

2. Pousser une contribution

Le body peut être un objet JSON unique ou un tableau. Champs requis · text. Optionnels · channel, submitted_at (ISO 8601), pseudonym.

BODY='{"text":"La traversée piétonne au croisement est dangereuse.","channel":"libre"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')

curl -X POST "http://127.0.0.1:8001/api/consultations/centre-ville/sources/webhook" \
  -H "X-Balisio-Signature: sha256=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

# Réponse
{
  "received": 1,
  "inserted": 1,
  "deduplicated": 0,
  "skipped": 0
}

Pièces jointes

Quatre endpoints pour gérer les documents publics du projet ·

# Upload (multipart, 25 Mo max, allowlist d'extensions)
curl -X POST "$TRAME/api/consultations/centre-ville/attachments" \
  -F "[email protected]"

# Lister
curl "$TRAME/api/consultations/centre-ville/attachments"

# Télécharger (proxy avec Content-Disposition)
curl -O -J "$TRAME/api/consultations/centre-ville/attachments/{id}"

# Supprimer
curl -X DELETE "$TRAME/api/consultations/centre-ville/attachments/{id}"

Atelier IA · endpoints

Journal d'audit

Chaque action sensible (changement de statut d'un signalement, réponse publiée, document publié, projet dupliqué, archive exportée, lettre générée) crée un évènement horodaté. Le journal est consultable par projet et alimente les souscriptions webhooks sortants.

curl "$TRAME/api/consultations/centre-ville/audit?limit=50"

# Réponse
{
  "events": [
    {
      "id": 142, "type": "pin.response_published",
      "actor": "Mairie · DGS",
      "summary": "Réponse publique publiée (87 car.)",
      "payload": {"pin_hash": "5365…", "author": "Mairie · DGS"},
      "at": "2026-05-03 20:24:54"
    }
  ]
}

Types d'évènements émis aujourd'hui · pin.status_changed, pin.assigned, pin.response_published, attachment.uploaded, letter.generated, project.duplicated, project.exported.

Génération DOCX (courriers)

Trois templates officiels · convocation à réunion publique, lettre d'information aux riverains, accusé de réception. Le serveur reçoit le contenu déjà éditable côté agent et renvoie un .docx mis en forme (en-tête mairie en Bleu France, corps Inter 11pt, listes à puces, marges A4 22mm).

curl -X POST "$TRAME/api/consultations/centre-ville/letter" \
  -H "Content-Type: application/json" \
  -o trame-centre-ville-convocation.docx \
  -d '{
    "template": "convocation",
    "title": "Objet · convocation à la réunion publique",
    "commune": "Ville de Montaigu-Vendée",
    "signataire": "Le Maire",
    "paragraphs": [
      "Madame, Monsieur,",
      {"kind":"list","text":"Date · 18 mai 19h00\nLieu · Salle du conseil\nDurée · 1h30"},
      "Comptant sur votre présence,"
    ]
  }'

Chaque génération crée un évènement letter.generated dans le journal d'audit.

Exports · CSV & archive ZIP

Export CSV des contributions

Les colonnes · hash, submitted_at, channel, text, pseudonym, theme, secondary_themes, sentiment, stance, specificity, summary. Les classifications sont jointes lorsqu'elles existent.

curl -O -J "$TRAME/api/consultations/centre-ville/contributions.csv"

Archive ZIP complète du projet

Bundle contenant consultation.json, contributions.json (avec classifications), audit.json, reports/*.json, attachments/*. Un README.txt à la racine décrit la structure. Idéal pour les remises de fin de mission ou les transferts vers un autre outil.

curl -O -J "$TRAME/api/consultations/centre-ville/export.zip"

Duplication d'un projet

Clone le format, le template, la base légale, le périmètre et le bloc config JSON dans un nouveau brouillon. Aucune contribution n'est copiée. Le slug est auto-suffixé en cas de collision.

curl -X POST "$TRAME/api/consultations/centre-ville/duplicate" \
  -H "Content-Type: application/json" -d '{}'

# Réponse
{
  "slug": "centre-ville-copie",
  "from": "centre-ville"
}

Webhooks sortants (souscriptions)

Symétrique du webhook entrant · vous abonnez votre système à des évènements Balisio, on vous les pousse en HMAC-SHA256 dès qu'ils se produisent.

1. Souscrire

curl -X POST "$TRAME/api/sdk/webhooks" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-systeme.fr/trame-events",
    "events": ["pin.created","pin.response_published","letter.generated"]
  }'

# Réponse · le secret HMAC n'est plus jamais renvoyé après cette réponse
{
  "id": "wh_XcmVwd2G-Ei-2w",
  "secret": "whsec_…",
  "warning": "Cette clé HMAC ne sera plus jamais affichée."
}

2. Vérifier la signature côté client

# Headers reçus à chaque livraison
X-Balisio-Signature: sha256=<hex>
X-Balisio-Event: pin.response_published

# Body · JSON
{
  "id": "evt_20260503T202454Z_pin.response_published",
  "type": "pin.response_published",
  "project_slug": "85146",
  "actor": "Mairie · DGS",
  "summary": "Réponse publique publiée (87 car.)",
  "data": {"pin_hash": "5365…"},
  "at": "2026-05-03T20:24:54Z"
}

Recherche cross-projet

Une seule requête, trois sections en réponse · contributions matching le texte, projets matching le nom/slug/base-légale, évènements matching le summary/actor.

curl "$TRAME/api/search?q=fontaine"

Powered by SQLite LIKE aujourd'hui · index full-text en T3 2026 lorsque les volumes le justifieront.

Compte & clé API

Réglages tenant single-tenant pour l'instant (multi-tenant T2 2026 avec l'auth magic-link). Toute clé non listée dans SETTINGS_DEFAULTS est ignorée silencieusement (anti-injection de schéma).

# Lire les réglages
curl "$TRAME/api/account/settings"

# Mettre à jour deux clés
curl -X PATCH "$TRAME/api/account/settings" \
  -H "Content-Type: application/json" \
  -d '{"france_connect": true, "synth_interval_hours": "4"}'

# Régénérer la clé API · révoque l'active, retourne la nouvelle UNE FOIS
curl -X POST "$TRAME/api/account/api-key/rotate"

Authentification magic-link (mode local)

Implémentation locale opérationnelle, sans dépendance externe. Le transport email (Brevo, Scaleway TEM) sera branché en T2 2026. En attendant, l'endpoint /api/auth/dev/last-link expose le lien à cliquer · l'espace agent l'affiche dans une bannière jaune sur la page de connexion.

# 1. Demander un lien
curl -X POST "$TRAME/api/auth/magic-link" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

# 2. Récupérer le lien (DEV ONLY · sera désactivé en production)
curl "$TRAME/api/auth/dev/last-link"

# 3. Suivre le lien · pose le cookie trame_sess (HttpOnly, 14j)
curl -L "$TRAME/api/auth/callback?token=…"

SDK navigateur

Pour intégrer le formulaire de signalement directement dans votre site existant, déployez le SDK Balisio ·

<script src="https://balisio.app/sdk/v1.js" async></script>
<div data-trame-widget="signaler"
     data-commune="montaigu-vendee"
     data-theme="voirie"></div>

Provisionnez vos clés API depuis l'onglet Intégrer de l'espace client.

Iframe embed

L'option la plus simple · une iframe dans votre CMS communal.

<iframe src="https://balisio.com/projet/?slug=plan-velo-grenoble-2027"
        width="100%" height="720" style="border:0"
        loading="lazy" title="Consultation Balisio"></iframe>

RGPD & CNIL

• Hashage IP · SHA-256 + sel rotatif. Aucune adresse IP en clair n'est stockée.
• Conservation · 12 mois après la clôture de la consultation, conformément à LCEN art. 6.
• Bandeau de consentement · granulaire (essentiel toujours coché, analytique opt-in). Implémentation à web/css/trame-consent.js.
• Droits · art. 15 (accès), 16 (rectification), 17 (effacement), 18 (limitation), 20 (portabilité), 21 (opposition). Voir page Confidentialité.
• Hébergement · Scaleway Paris (eu-fr-par1) sélectionné. Production T2 2026.

Accessibilité RGAA 4.1

Page de déclaration publiée à trame · accessibilité. Audit formel à programmer T3 2026 avant la première mise en production payante. Critères visés ·

• Contraste AA minimum (4.5:1 texte normal, 3:1 texte large).
• Navigation clavier complète, ordre de tabulation logique.
• Lecteur d'écran · ARIA labels sur tous les contrôles, alt text sur tous les médias.
• Mobile-first, tactile-friendly, touche min. 44 × 44 px.

Bases légales par format

Dernière mise à jour · 3 mai 2026 · Version v1.1 · couvre les endpoints audit, DOCX, ZIP, duplicate, sortants, recherche, compte, auth.