API & MCP — Automatiser Slonge Billing

Slonge Billing propose une interface en ligne de commande (CLI) officielle ainsi qu'un serveur MCP (Model Context Protocol) pour Claude Desktop, Cursor et Claude Code. Vous pouvez ainsi piloter votre tenant de manière programmatique ou via des agents IA — créer des clients, établir des factures, obtenir des rapports, le tout sans cliquer dans l'interface web.

À qui cela s'adresse-t-il ?

• Utilisateurs de la CLI : développeurs/développeuses, comptables ou utilisateurs avancés qui souhaitent automatiser des tâches de routine ou les intégrer dans leurs propres scripts.
• Utilisateurs d'agents IA : toute personne qui utilise Claude Desktop, Cursor ou Claude Code (ou un autre agent compatible MCP) et qui veut utiliser les fonctions de Slonge directement depuis le chat — « Crée-moi le client Beispiel AG avec l'e-mail … » ou « Quelles factures sont en retard cette semaine ? ».
• Condition préalable : rôle Administrateur dans le tenant — seuls les administrateurs peuvent créer ou révoquer des jetons d'API.

Démarrage rapide en 5 minutes

Étape 1 : créer un jeton d'API

1. Connectez-vous à Slonge Billing.
2. Ouvrez les Paramètres.
3. Passez à l'onglet API & MCP.
4. Cliquez sur Créer un jeton.
5. Attribuez un nom parlant (p. ex. « Claude Desktop », « Pipeline CI »).
6. En option : choisissez une expiration (30 / 90 / 365 jours ou « Jamais »).
7. Cliquez sur Créer — le jeton complet s'affiche une seule fois. Copiez-le immédiatement. Une fois la boîte de dialogue fermée, il ne peut plus être récupéré.

Sécurité : les jetons sont enregistrés sous forme de hachage SHA-256. Slonge lui-même ne peut plus consulter la valeur en clair après la création. Si un jeton est perdu, révoquez-le et créez-en un nouveau.

Étape 2A : utiliser la CLI

# Une seule fois : définir la configuration
slonge config set api-url https://app.slonge-billing.ch
slonge config set api-token slk_live_VOTRE_JETON_ICI
slonge config test       # confirme l'authentification Bearer

# Commandes quotidiennes
slonge client list
slonge client create --name "Beispiel AG" --email [email protected]
slonge invoice list --status pending --limit 10
slonge invoice create --project-id <id> --amount 1500 --description "Prestation de conseil mai"
slonge invoice mark-paid <id-facture>

Indicateurs globaux (disponibles pour toutes les commandes) :

• --json — renvoie une réponse JSON au lieu d'un tableau (idéal pour les scripts)
• --verbose — consigne les appels HTTP dans stderr
• --dry-run — valide l'entrée et affiche l'appel prévu sans l'exécuter

La CLI enregistre la configuration dans ~/.slonge/config.json (Windows : %USERPROFILE%\.slonge\config.json).

Étape 2B : intégrer le serveur MCP dans Claude Desktop

1. Complétez la configuration dans %APPDATA%\Claude\claude_desktop_config.json (Windows) ou ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) :

   {
     "mcpServers": {
       "slonge-billing": {
         "command": "node",
         "args": ["<chemin-absolu>/packages/mcp-server/dist/index.js"],
         "env": {
           "SLONGE_CONFIG_PATH": "<chemin-absolu>/.slonge/config.json"
         }
       }
     }
   }
   

2. Quittez complètement Claude Desktop (ne fermez pas seulement la fenêtre — quittez aussi l'icône de la barre d'état) et redémarrez-le.

3. Dans le chat apparaît une icône 🔌 avec l'entrée slonge-billing et une vingtaine d'outils disponibles.

4. Dans la conversation, demandez : « Liste-moi les factures ouvertes dans Slonge » — Claude appelle l'outil approprié et affiche le résultat directement dans le chat.

Les mêmes étapes fonctionnent avec Cursor et Claude Code (via leur configuration MCP respective).

Fonctions disponibles

La CLI et le serveur MCP accèdent tous deux à la même API — les fonctionnalités sont identiques.

Nouveaux outils (Wave 6)

Facture électronique (Peppol BIS Billing 3.0)

Commande CLI abrégée :

slonge invoice ubl <id> -o rechnung.xml   # écrit le XML sur le disque
slonge invoice ubl <id>                   # diffuse le XML vers stdout

Pour obtenir la liste complète des noms d'outils MCP (au format client_list, invoice_create, etc.), utilisez l'appel tools/list de votre client MCP.

Authentification & limites

• Jeton Bearer — chaque appel nécessite l'en-tête Authorization: Bearer slk_<env>_<token>.
• Liaison au tenant — le jeton connaît son tenant ; il n'est pas possible de changer de tenant sur un jeton. Qui gère plusieurs tenants crée un jeton distinct par tenant.
• Limite de débit — 60 requêtes par minute et par jeton. En cas de dépassement, l'API répond avec 429 Too Many Requests et l'en-tête Retry-After.
• Journal d'audit — chaque accès est consigné (horodatage, méthode, chemin, code de statut, temps de réponse).

Quota IA

Les outils qui utilisent OpenAI — actuellement uniquement expense upload / expense_upload — sont imputés sur la limite IA mensuelle de votre plan (aiCallsPerMonth).

Lorsque la limite est atteinte, l'API répond avec 429 QUOTA_EXCEEDED. Les appels effectués sur un plan sans fonctions IA répondent avec 403 FORBIDDEN. Les deux codes ont une signification déterministe — les agents peuvent distinguer entre « attendre et réessayer » (limite de débit) et « passer à un plan supérieur » (quota).

Codes d'erreur

L'API répond toujours avec la même structure d'enveloppe :

{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "...", "details": { } } }

Sécurité & bonnes pratiques

• Ne jamais committer de jetons — un .gitignore pour les fichiers .env et ~/.slonge/config.json est obligatoire.
• Un jeton par application — chaque pipeline CI, chaque ordinateur portable, chaque agent reçoit son propre jeton. Cela permet de révoquer de manière ciblée en cas de perte d'un appareil.
• Attribuer des noms parlants — le nom du jeton apparaît dans le journal d'audit et dans la vue d'ensemble ; « Claude Desktop — ordinateur portable de Ben » est plus éloquent que « Jeton 1 ».
• Révoquer en cas de doute — la révocation prend effet immédiatement ; le jeton ne peut pas être réactivé.
• Utiliser une date d'expiration — pour des intégrations temporaires (p. ex. une migration unique), préférez 30 jours à « Jamais ».

Streamable HTTP Transport

Outre le slonge-mcp local (stdio), Slonge Billing propose un point de terminaison MCP hébergé :

POST https://app.slonge-billing.ch/api/mcp
Authorization: Bearer slk_...
Accept: application/json, text/event-stream

Connectez les clients compatibles (claude.ai, ChatGPT, Cursor avec prise en charge du MCP distant) directement à cette URL — aucune installation nécessaire. Les mêmes jetons d'API fonctionnent via stdio et HTTP.

Étapes suivantes

• Créer un jeton : Paramètres → API & MCP
• Contactez-nous à l'adresse [email protected] si vous avez des questions sur la configuration ou si vous souhaitez de nouveaux outils MCP.

Remarque pour les développeurs/développeuses : le SDK officiel s'appelle @slonge/agent-sdk et contient des schémas Zod ainsi qu'un client HTTP typé. Il est maintenu avec la CLI et le serveur MCP dans le monorepo de Slonge Billing.