API & MCP — Automatizzare Slonge Billing

Slonge Billing offre un'interfaccia a riga di comando (CLI) ufficiale e un server MCP (Model Context Protocol) per Claude Desktop, Cursor e Claude Code. In questo modo può gestire il suo tenant in modo programmatico o tramite agenti IA — creare clienti, emettere fatture, ottenere rapporti, il tutto senza cliccare nell'interfaccia web.

A chi è destinato?

• Utenti della CLI: sviluppatori/sviluppatrici, contabili o utenti esperti che desiderano automatizzare attività di routine o integrarle nei propri script.
• Utenti di agenti IA: chi utilizza Claude Desktop, Cursor o Claude Code (o un altro agente compatibile con MCP) e vuole usare le funzioni di Slonge direttamente dalla chat — «Creami il cliente Beispiel AG con l'e-mail …» oppure «Quali fatture sono scadute questa settimana?».
• Requisito: ruolo Amministratore nel tenant — solo gli amministratori possono creare o revocare token API.

Avvio rapido in 5 minuti

Passo 1: creare un token API

1. Acceda a Slonge Billing.
2. Apra le Impostazioni.
3. Passi alla scheda API & MCP.
4. Clicchi su Crea token.
5. Assegni un nome significativo (ad es. «Claude Desktop», «Pipeline CI»).
6. Facoltativo: scelga una scadenza (30 / 90 / 365 giorni oppure «Mai»).
7. Clicchi su Crea — il token completo viene mostrato una sola volta. Lo copi subito. Dopo la chiusura della finestra di dialogo non è più recuperabile.

Sicurezza: i token vengono memorizzati come hash SHA-256. Slonge stesso non può più visualizzare il valore in chiaro dopo la creazione. Se un token viene perso, lo revochi e ne crei uno nuovo.

Passo 2A: usare la CLI

# Una tantum: impostare la configurazione
slonge config set api-url https://app.slonge-billing.ch
slonge config set api-token slk_live_IL_SUO_TOKEN_QUI
slonge config test       # conferma l'autenticazione Bearer

# Comandi quotidiani
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 "Prestazione di consulenza maggio"
slonge invoice mark-paid <id-fattura>

Flag globali (disponibili per tutti i comandi):

• --json — restituisce una risposta JSON invece di una tabella (ideale per gli script)
• --verbose — registra le chiamate HTTP su stderr
• --dry-run — convalida l'input e mostra la chiamata prevista senza eseguirla

La CLI salva la configurazione in ~/.slonge/config.json (Windows: %USERPROFILE%\.slonge\config.json).

Passo 2B: integrare il server MCP in Claude Desktop

1. Completi la configurazione in %APPDATA%\Claude\claude_desktop_config.json (Windows) o ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

2. Chiuda completamente Claude Desktop (non solo la finestra — anche l'icona nella barra delle applicazioni) e lo riavvii.

3. Nella chat compare un'icona 🔌 con la voce slonge-billing e circa 20 strumenti disponibili.

4. Nella conversazione chieda: «Elencami le fatture aperte in Slonge» — Claude richiama lo strumento adatto e mostra il risultato direttamente nella chat.

Gli stessi passi funzionano con Cursor e Claude Code (tramite la rispettiva configurazione MCP).

Funzioni disponibili

Sia la CLI sia il server MCP accedono alla stessa API — la funzionalità è identica.

Nuovi strumenti (Wave 6)

Fattura elettronica (Peppol BIS Billing 3.0)

Comando CLI abbreviato:

slonge invoice ubl <id> -o rechnung.xml   # scrive l'XML su disco
slonge invoice ubl <id>                   # invia l'XML in streaming su stdout

Per ottenere l'elenco completo dei nomi degli strumenti MCP (nel formato client_list, invoice_create, ecc.), utilizzi la chiamata tools/list del suo client MCP.

Autenticazione & limiti

• Token Bearer — ogni chiamata richiede l'intestazione Authorization: Bearer slk_<env>_<token>.
• Vincolo al tenant — il token conosce il proprio tenant; non è possibile cambiare tenant su un token. Chi gestisce più tenant crea un token distinto per ciascun tenant.
• Limite di frequenza — 60 richieste al minuto per token. In caso di superamento, l'API risponde con 429 Too Many Requests e l'intestazione Retry-After.
• Registro di audit — ogni accesso viene registrato (data e ora, metodo, percorso, codice di stato, tempo di risposta).

Quota IA

Gli strumenti che utilizzano OpenAI — attualmente solo expense upload / expense_upload — vengono conteggiati rispetto al limite IA mensile del suo piano (aiCallsPerMonth).

Al raggiungimento del limite, l'API risponde con 429 QUOTA_EXCEEDED. Le chiamate effettuate su un piano senza funzioni IA rispondono con 403 FORBIDDEN. Entrambi i codici hanno un significato deterministico — gli agenti possono distinguere tra «attendere e riprovare» (limite di frequenza) e «aggiornare il piano» (quota).

Codici di errore

L'API risponde sempre con la stessa struttura di involucro:

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

Sicurezza & buone pratiche

• Non committare mai i token — un .gitignore per i file .env e ~/.slonge/config.json è obbligatorio.
• Un token per applicazione — ogni pipeline CI, ogni laptop, ogni agente riceve un proprio token. In questo modo è possibile revocare in modo mirato in caso di perdita di un dispositivo.
• Assegnare nomi significativi — il nome del token compare nel registro di audit e nella panoramica; «Claude Desktop — laptop di Ben» è più eloquente di «Token 1».
• Revocare in caso di sospetto — la revoca è immediatamente efficace; il token non può essere riattivato.
• Utilizzare una data di scadenza — per integrazioni temporanee (ad es. una migrazione una tantum) è preferibile 30 giorni anziché «Mai».

Streamable HTTP Transport

Oltre allo slonge-mcp locale (stdio), Slonge Billing offre un endpoint MCP ospitato:

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

Colleghi i client compatibili (claude.ai, ChatGPT, Cursor con supporto MCP remoto) direttamente a questo URL — nessuna installazione necessaria. Gli stessi token API funzionano tramite stdio e HTTP.

Passi successivi

• Creare un token: Impostazioni → API & MCP
• Ci contatti all'indirizzo [email protected] in caso di domande sulla configurazione o se desidera nuovi strumenti MCP.

Nota per sviluppatori/sviluppatrici: l'SDK ufficiale si chiama @slonge/agent-sdk e contiene schemi Zod e un client HTTP tipizzato. Viene mantenuto insieme alla CLI e al server MCP nel monorepo di Slonge Billing.