Riferimento dell’API (beta)

L’API di To Bill è quella che usa l’app stessa: clienti, fatture, offerte, articoli, spese, banca, contabilità, IVA, stipendi e tempo. Una chiave API personale la apre ai suoi script e ai suoi strumenti, con i suoi diritti. Il riferimento interattivo dell’API descrive ogni route che una chiave può chiamare, i suoi parametri e le sue risposte, fornisce esempi in curl, JavaScript, Python e PHP e le permette di provare una richiesta con la sua chiave.

Il riferimento è in inglese

Come la maggior parte dei riferimenti tecnici, è redatto in inglese, la lingua degli sviluppatori. Questa pagina ne riassume l’essenziale.

Una versione beta

L’API è in versione beta (0.x). Le sue route e le loro risposte possono cambiare senza preavviso: non c’è né garanzia di compatibilità, né supporto per il suo uso diretto. Per collegare un assistente IA, usi il server MCP, che è l’interfaccia stabile: veda Collegare un assistente IA.

Autenticarsi

Ogni richiesta porta una chiave API personale nell’intestazione HTTP Authorization:

curl https://app.tobill.ch/api/clients -H "Authorization: Bearer tb_pk_…"

La chiave si crea in Impostazioni › Connessioni IA e API: veda L’API e le chiavi API. Agisce a suo nome, nell’azienda in cui l’ha creata, con i suoi diritti in quell’azienda. Una chiave Sola lettura invia solo richieste di lettura (GET); una chiave Lettura e modifica può anche creare, modificare ed eliminare.

Gli errori

Una richiesta rifiutata riceve una risposta JSON di questa forma: { "statusMessage": "error", "message": "…", "error_code": "…", "fallback": "…" }. message è un codice stabile, da verificare nel suo programma; fallback è una frase leggibile, ad esempio con il campo in questione.

Codice HTTP	Significato
400	Dati non validi.
401	Chiave assente, non valida, scaduta o revocata.
403	Rifiutato: chiave in sola lettura, diritto mancante, abbonamento senza accesso all’API, o parte di To Bill chiusa alle chiavi (not_available_with_api_token).
404	Non trovato in questa azienda.
429	Troppe richieste: attenda il numero di secondi indicato dall’intestazione Retry-After.

I limiti

• 300 richieste al minuto per chiave; una modifica conta doppio.
• Una chiave non apre né l’accesso al suo account, né l’abbonamento, né i pagamenti, né la gestione del team e delle chiavi, né un’altra azienda, né il cockpit di un fiduciario, né le azioni di massa. Queste route non figurano nel riferimento.

La specifica OpenAPI

Il riferimento è generato a partire dal documento OpenAPI 3.1 dell’API. Può importarlo in uno strumento come Postman o generarne un client:

Che cosa	Indirizzo
Riferimento interattivo	https://docs.tobill.ch/api
Specifica OpenAPI 3.1	https://app.tobill.ch/api/openapi.json

Provare una richiesta

Nel riferimento, il pulsante Test Request invia la richiesta dal suo browser direttamente a https://app.tobill.ch, senza intermediari. La sua chiave va solo a To Bill e non viene salvata: scompare quando chiude la pagina. Una richiesta di modifica modifica davvero i suoi dati: per scoprire l’API, la provi con una chiave Sola lettura.