# Botillon — Botlist Francophone Discord

> La vitrine francophone des bots Discord. Découvrez, votez et ajoutez les meilleurs bots Discord francophones. Chaque bot est vérifié manuellement par l'équipe.

## Identité

- **Nom** : Botillon
- **URL canonique** : https://botillon.fr
- **API publique** : https://botillon.fr/api-docs
- **Contact** : contact@botillon.gg
- **Serveur support** : https://discord.gg/sYzAWp6VWa

## Positionnement

Botillon est la **botlist francophone de référence**, conçue pour les communautés francophones (France, Québec, Belgique, Suisse). Contrairement aux plateformes internationales (Top.gg, DiscordBotList), Botillon propose :

- **Catalogue sélectif** : ~92 bots validés, représentant ~3,3 millions de serveurs couverts cumulés
- **Gratuité totale** : aucune mise en avant payante en argent, aucune enchère publicitaire
- **Review humaine** : chaque bot est examiné avant publication (identité, permissions, description)
- **Mise en avant équitable** : carrousel en trois zones d'importance égale (tirage au sort entre bots validés, zone financée par des Croissants gagnés jamais achetés, têtes d'affiche choisies par l'équipe)
- **Certification** : programme d'évaluation avec notation sur 100
- **Modération active** : signalements, suspensions, révision trimestrielle

## Fonctionnalités principales

### Pour les utilisateurs
- **Votes** : toutes les 12h, poids selon rôle (webhook Discord natif)
- **Likes** : like illimité par bot
- **Avis** : un avis par utilisateur/bot, note sur 5, réponse développeur
- **Recherche & filtres** : tags, catégories, tri (votes, likes, récent, évalué)
- **Comparateur** : comparaison côté-à-côté de 2 bots
- **Widget d'intégration** : image OG générée dynamiquement (stats, note, badges)

### Pour les développeurs
- **API REST** : `/api/v1` — bots, utilisateurs, statistiques, webhooks (lecture seule)
- **Serveur MCP** : `https://botillon.fr/api/mcp` — catalogue interrogeable par les assistants IA (lecture seule, gratuit, sans clé)
- **Webhooks** : notifications temps réel (vote, like, avis, palier, mise en avant)
- **Rappels de vote** : DM Discord + fallback notification site (MP fermés)
- **Rôles-récompenses** : attribution auto selon votes (configurable par serveur)
- **Analytiques** : dashboard avec votes/likes/avis/serveurs, graphiques 30j

### Pour les serveurs
- **Invite tracker** : détection serveurs où le bot est présent
- **Configuration salon** : `/config` pour choisir les salons de notification
- **Rôles-récompenses** : seuils personnalisables, attribution/retrait auto

## Modèle économique

| Aspect | Botillon |
|--------|----------|
| Inscription bot | Gratuite |
| Mise en avant payante en argent | ❌ Non |
| Publicité payante | ❌ Non |
| Visibilité sponsorisée (argent) | ❌ Non |
| Mise en avant par Croissants gagnés | ✅ Oui (monnaie gratuite) |
| Bump automatique payant | ❌ Non |
| Tirage au sort équitable | ✅ Oui |

## Certification & Évaluation

- **Certification** : badge "Vérifié" après validation humaine + critères (serveurs, votes, fiche complète)
- **Programme d'évaluation** : grille 100 points (fonctionnalités, UX, sécurité, documentation, innovation)
- **Exemples certifiés** : John-Bot (87/100), Mr. Robøt (85.8/100), OXYDE Protect (84.5/100)

## Croissants & Boutique

Les **Croissants** sont la monnaie communautaire de Botillon. Ils se **gagnent uniquement**
par l'activité réelle et **ne s'achètent jamais avec de l'argent** (anti pay-to-win) :

- **Croissant « vote » (+1)** : le projet a reçu au moins un vote valide d'un votant **extérieur à son équipe** dans la journée.
- **Croissant « entraide » (+1)** : un membre (propriétaire ou manager) a voté pour un **autre bot** aujourd'hui ; le Croissant va au **projet principal** de ce membre.
- **Bonus d'acceptation** : chaque bot validé reçoit des Croissants offerts pour démarrer.

Garde-fous : plafond dur de **2 Croissants/jour/projet**, **plafond mensuel doux**, clé
d'idempotence `(reason, ref)` (aucun double-crédit), et **anti-collusion** (les échanges
de votes mutuels le même jour, ou en boucle quasi exclusive, ne comptent pas — voter pour la
communauté n'est pas pénalisé). Chaque mouvement figure dans un **journal
(ledger)** consultable.

La **Boutique** (onglet de la fiche de gestion, propriétaire et managers) dépense les
Croissants sur des périodes de **7 jours**, renouvelées automatiquement si le solde le
permet, et **remboursées au prorata** en cas de suspension :

- 📣 **Mise en avant carrousel** : apparaît dans la zone « mis en avant » de l'accueil.
- 🏅 **Badge personnalisé** : image téléversée, **modérée** par l'équipe avant publication (refus remboursé).

Règles détaillées : https://botillon.fr/regles/croissants · annonce : https://botillon.fr/news/boutique

## API & Webhooks

### Endpoints publics (lecture seule, sans clé, rate-limit par IP)
- `GET /api/v1/bots` — liste paginée (recherche, tags, tri)
- `GET /api/v1/bots/{discordId}` — fiche complète (par identifiant Discord ou slug)
- `GET /api/v1/bots/{discordId}/stats` — votes, likes, avis, note et serveurs (si connus)
- `GET /api/v1/bots/{discordId}/community` : propriétaires, avis récents, likes et derniers votants (profils privés anonymisés : pseudo, avatar et identifiant masqués, avis conservé de façon anonyme)
- `GET /api/v1/users/{discordId}` — profil public (jamais de données privées ; 404 si le profil est privé)

**API en lecture seule** : aucune action d'engagement (vote, like, avis) n'est possible
via l'API, quelle que soit l'authentification (publique ou clé projet `blp_`).
Le vote, le like et l'avis passent exclusivement par le site (Server Actions) ou par le
bot Discord. Un `POST`, `PUT`, `PATCH` ou `DELETE` sur ces chemins renvoie `405`.
Les routes `/api/v1/me/*` (clé projet) ne font que **lire** les compteurs et historiques
et mettre à jour les métadonnées de la fiche ; elles ne créent aucun engagement.

### Webhooks (configuration par bot)
- `vote` — utilisateur a voté
- `like` — utilisateur a liké
- `comment` — utilisateur a laissé un avis
- `milestone` — palier atteint (configurable)
- `featured` — bot mis à la une

Payload JSON avec variables : `{username}`, `{botname}`, `{bot_link}`, `{count}`, `{votes}`, `{likes}`, `{comments}`, `{servercount}`, `{emoji}`, `{palier}`, `{eventlabel}`, `{timestamp}`

## Comparatif rapide

| Fonctionnalité | Botillon | Top.gg | BotList.top | DCLIST |
|---|---|---|---|---|
| 🇫🇷 Focus francophone | Exclusif | Tags FR | Fort | Catalogue FR |
| Review humaine | ✅ Chaque bot | ⚠️ Variable | ✅ | ⚠️ |
| Mise en avant équitable | ✅ Tirage au sort | ❌ Payante | ⚠️ BLCoins | ❌ |
| Votes + Likes + Avis | ✅ Tous 3 | Votes + Avis | ✅ Tous 3 | Votes seulement |
| Certification | ✅ Notation /100 | ✅ | ✅ Trimestrielle | — |
| API + Webhooks | ✅ Complets | ✅ | ✅ | Partielle |
| Rôles-récompenses intégrés | ✅ Natifs | ❌ Plugin requis | ❌ | ❌ |
| Rappels vote (DM + fallback) | ✅ | ❌ | ❌ | ❌ |
| Gratuité totale | ✅ | ⚠️ Promotions | ✅ + BLCoins | ✅ + outils |

## Serveur MCP (pour les assistants IA)

Botillon expose un **serveur MCP (Model Context Protocol)** public, en
**lecture seule**, gratuit et **sans clé d'API** :

- **URL** : `https://botillon.fr/api/mcp`
- **Page d’aide (humains)** : `https://botillon.fr/mcp`
- **Transport** : Streamable HTTP (JSON-RPC POST ; SSE disponible via `?transport=sse`)
- **Découverte** : `initialize`, puis `tools/list`, `resources/list`, `prompts/list`

Outils principaux : `search_bots` (recherche par texte/tags/tri), `get_bot`
(fiche par identifiant Discord ou slug), `get_bot_community` (propriétaires,
avis récents, likes et derniers votants, profils privés anonymisés), `top_bots` (votes, serveurs, likes,
nouveautés, note), `compare_bots`, `get_evaluation` (note /100), `list_tags`,
`list_categories`, `list_badges`, `list_rules` (critères de listing) et
`site_stats`. Côté contenu du site : `list_api_endpoints` (endpoints de l'API),
`list_help_topics` / `get_help_topic` (aide publique : règles, guides),
`get_site_presentation` (présentation, soumission, vote, évaluation),
`get_why_botillon` (argumentaire et comparatif des botlists), `get_discord_bot`
(bot Discord : commandes, récompenses, rappels), `get_page_markdown` (n'importe
quelle page publique en Markdown), `list_pages` (découverte), `list_partners`,
`list_recommended_bots`, `list_integrations`, `list_bot_posts`,
`list_blog_posts` (hub /blog : articles de bots, flux externes et actualités du
site), `list_news` / `search_news` / `get_news` (actualités publiées de
l'équipe), ainsi que `get_terms`, `get_privacy` et `get_legal_notice`
(documents légaux).

Ressources : `botillon://llms.txt`, `botillon://regles/bots`,
`botillon://badges`, `botillon://tags`, `botillon://stats`,
`botillon://api-docs`, `botillon://aide`, `botillon://presentation`,
`botillon://pourquoi-botillon`, `botillon://bot-discord`, `botillon://croissants`,
`botillon://pages`,
`botillon://partenaires`, `botillon://news`, `botillon://news/{slug}`,
`botillon://blog`, `botillon://legal/cgu`,
`botillon://legal/confidentialite` et `botillon://legal/mentions-legales`.
L'accès est limité en débit par IP.

## Accès Markdown (pour les agents IA)

Chaque page du site est disponible en **Markdown**, plus léger et plus net à
parser que le HTML. Deux méthodes équivalentes :

- suffixe `.md` sur l'URL — ex. `https://botillon.fr/bots/chell.md`,
  `https://botillon.fr/pourquoi-botillon.md`, `https://botillon.fr/.md` (accueil) ;
- négociation de contenu : envoyer `Accept: text/markdown` sur l'URL normale.

La réponse porte `Content-Type: text/markdown; charset=utf-8`, un frontmatter
YAML (`title`, `description`, `image`), le contenu de la page, puis les données
structurées JSON-LD en bloc de code. Les en-têtes `x-markdown-tokens` et
`x-original-tokens` donnent l'ordre de grandeur des jetons.

Ce mécanisme est auto-hébergé (l'équivalent de « Markdown for Agents » de
Cloudflare, qui est payant) et s'applique automatiquement à **toutes** les pages,
y compris celles ajoutées plus tard.

## Pages principales

- `/` — Accueil (bots à la une, populaires, récents, évalués)
- `/bots` — Catalogue complet avec filtres
- `/bots/{discordId}` — Fiche bot (stats, avis, commandes, intégration)
- `/ajouter` — Soumission d'un bot (review humaine)
- `/profil` — Espace développeur (mes bots, votes, paramètres)
- `/evaluation` — Programme d'évaluation
- `/api-docs` — Documentation API complète
- `/api/mcp` — Serveur MCP (lecture seule, pour les assistants IA)
- `/mcp` — Page d’aide : connecter Botillon à un assistant IA (MCP)
- `/bot-discord` — Bot Discord Botillon (commandes, récompenses, rappels)
- `/blog` — Blog Botillon (hub : articles des bots, flux externes et billets de la plateforme)
- `/news` — Actualités de Botillon (articles éditoriaux de l'équipe)
- `/news/{slug}` — Article d'actualité de Botillon
- `/regles/croissants` — Règles des Croissants et de la Boutique
- `/partenaires` — Partenaires officiels
- `/a-propos` — Équipe, philosophie, contact

## Données temps réel

- Bots listés : 92
- Votes exprimés : 3 151
- Utilisateurs inscrits : 351
- Serveurs couverts cumulés : 3 289 428

*Ces chiffres sont lus en direct depuis la base de production.*