L’API e le chiavi API
Un assistente come Claude o ChatGPT si collega con la pagina di autorizzazione di To Bill: veda Collegare un assistente IA. Uno strumento che non ha questa pagina, uno script, un client MCP a riga di comando o un’automazione, usa una chiave API personale. Questa pagina spiega le chiavi e indica gli indirizzi tecnici.
Gli indirizzi
| Che cosa | Indirizzo |
|---|---|
| Server MCP (assistenti IA) | https://app.tobill.ch/mcp |
| API di To Bill | https://app.tobill.ch/api/… |
| Discovery OAuth | https://app.tobill.ch/.well-known/oauth-authorization-server |
| Riferimento dell’API (beta) | https://docs.tobill.ch/api |
Il server MCP dà all’assistente strumenti pronti all’uso per la contabilità e la fatturazione, più due strumenti che aprono tutto il resto di To Bill: uno cerca la route giusta dell’API, l’altro la chiama, con gli stessi controlli dell’app.
Il riferimento dell’API descrive ogni route che una chiave apre, con i parametri, le risposte e degli esempi; la sua versione interattiva permette di provare una richiesta con la sua chiave.
Creare una chiave
- Apra Impostazioni › Connessioni IA e API.
- Sotto Chiavi API personali, clicchi su Crea una chiave.
- Indichi in Nome a che cosa serve, scelga l’Accesso (Sola lettura o Lettura e modifica) e la Validità (30, 90 o 365 giorni), poi clicchi su Crea la chiave.
- Copi la chiave: viene mostrata una sola volta. Poi clicchi su Ho copiato la chiave.
La chiave inizia con tb_pk_. Apre l’azienda in cui si trovava quando l’ha creata, con i suoi diritti in quell’azienda. L’elenco mostra poi il suo inizio, il suo accesso, la sua azienda, la sua data di scadenza e il suo ultimo utilizzo, mai la chiave intera.
Una chiave è una password
Chiunque abbia la chiave agisce in To Bill a suo nome. Non la metta in un’e-mail, in un documento condiviso o in un repository di codice. Una chiave persa si revoca subito (veda più sotto) e si sostituisce con una nuova.
Inviare la chiave
Ogni richiesta porta la chiave nell’intestazione HTTP Authorization, come token Bearer:
curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"Claude Code con una chiave
claude mcp add --transport http tobill https://app.tobill.ch/mcp --header "Authorization: Bearer tb_pk_…"Che cosa apre una chiave e che cosa non apre
- Con Sola lettura, la chiave legge soltanto: ogni modifica è rifiutata.
- Con Lettura e modifica, fa ciò che lei può fare nell’azienda, con gli stessi controlli dell’app, e mai più dei diritti del suo ruolo.
- Non apre né l’accesso al suo account, né l’abbonamento, né i pagamenti, né la gestione delle connessioni e delle chiavi, né un’altra azienda, né il cockpit di un fiduciario.
- Ogni modifica fatta con la chiave è registrata nell’attività dell’azienda sotto il nome che lei le ha dato.
- To Bill limita il numero di richieste al minuto e per chiave; oltre il limite, rifiuta le richieste per un po’ e lo strumento deve attendere prima di riprovare.
Revocare una chiave
In Impostazioni › Connessioni IA e API, clicchi su Revoca accanto alla chiave, poi confermi. Smette di funzionare, subito. Una chiave scaduta resta nell’elenco, contrassegnata come Scaduta, finché lei non la revoca.