Strainovic IT Creare un token di accesso all’API di bexio
Chi cerca una «chiave API di bexio» non trova nessun pulsante in bexio. Oggi all’API di bexio si accede in due modi: con un token di accesso personale per i tuoi script, oppure con un’app nel Developer Portal che si collega tramite OAuth 2. Questa guida mostra entrambi i modi, la prima chiamata con il token e gli errori che più spesso bloccano all’inizio.
Esiste una chiave API di bexio?
No, non più. In passato la documentazione descriveva degli «API Tokens» fissi per le connessioni da server a server. Nell’ottobre 2024 bexio ha sostituito quella sezione con i token di accesso personali, in inglese «Personal Access Tokens», in breve PAT. Le vecchie guide che promettono una chiave permanente dalle impostazioni sono quindi superate.
Oggi ogni richiesta a https://api.bexio.com ha bisogno di un token di accesso
nell’intestazione Authorization: Bearer …. Da dove arriva il token dipende da chi usa la
connessione:
- Solo tu, per esempio per uno script, un’esportazione o un test: token di accesso personale (modo 1).
- Un’applicazione per altri, per esempio un plugin su un sito o un servizio per più aziende: app nel Developer Portal con OAuth 2 (modo 2).
Il riferimento di tutti gli endpoint si trova su docs.bexio.com. Per provare senza una contabilità vera, bexio offre un conto di prova da aprire su bexio.com.
Modo 1: creare un Personal Access Token
- Apri developer.bexio.com/pat e accedi con il tuo conto bexio.
- Crea un nuovo token e salvalo subito in un posto sicuro, per esempio in un gestore di password o in un file che solo tu puoi leggere.
- Invia il token dallo script come bearer token.
Secondo la documentazione un PAT funziona così:
- Accesso completo: un PAT ha tutti i diritti predefiniti e quindi accesso a tutti i dati dell’azienda. Chi lo conosce può leggere le fatture e modificare i contatti.
- Valido 60 giorni: poi scade e lo script ne ha bisogno di uno nuovo.
- Revoca tramite eliminazione: un token eliminato non si può più usare. Possono passare fino a un’ora prima che la revoca valga ovunque.
- Solo per uso personale: se vuoi limitare i diritti, per esempio alla sola lettura dei contatti, usa un’app.
Testare il token
Il test più semplice è un elenco dei contatti:
curl https://api.bexio.com/2.0/contact \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'
Se torna un elenco JSON, l’accesso funziona. L’API segnala gli errori con un codice di stato
HTTP e un breve testo JSON con error_code e message. Una chiamata a /3.0/users/me mostra
inoltre con quale utente lavora il token. È importante, perché l’API non ha mai più diritti di
questo utente in bexio.
Il token non va mai in un repository Git pubblico, in JavaScript nel browser o in un’e-mail. Se è stato comunque esposto: eliminalo nel Developer Portal e creane uno nuovo.
Modo 2: app nel Developer Portal con OAuth 2
Per tutto ciò che collegano altre persone o aziende, un PAT è la strada sbagliata. Serve allora un’app propria:
- Accedi al Developer Portal e accetta le condizioni d’uso. bexio rimanda in particolare al punto 4.4 sull’uso commerciale.
- Crea un’app e inserisci gli URL di reindirizzamento consentiti, cioè gli indirizzi a cui bexio rimanda dopo l’accesso.
- Leggi client ID e client secret sotto «App Details». Il secret resta sul server.
- Fai accedere l’utente tramite l’«Authorization Code Flow» su
auth.bexio.com. Lì vede quali diritti chiede l’app e li conferma.
Questi diritti si chiamano scope, per esempio contact_show per leggere i contatti o
kb_invoice_edit per modificare le fatture. Un diritto di scrittura include quello di
lettura. Con lo scope offline_access l’app riceve anche un refresh token, con cui ottiene
nuovi token di accesso senza che l’utente debba accedere di nuovo. La guida
Collegare l’API di bexio a WordPress mostra come appare
in WordPress.
Quale modo scegliere?
| Domanda | Personal Access Token | App con OAuth 2 |
|---|---|---|
| Chi usa la connessione? | tu stesso | altri utenti o aziende |
| Diritti | tutti i dati dell’azienda | solo gli scope richiesti |
| Validità | 60 giorni | finché il refresh token viene rinnovato regolarmente |
| Impegno | pochi minuti | accesso, memorizzazione del token, rinnovo |
| Uso tipico | esportazione, test, script proprio | plugin, integrazione, servizio |
Errori frequenti
- Token scaduto: uno script che girava da due mesi si ferma all’improvviso. Di solito il PAT è scaduto dopo 60 giorni.
- Diritti dell’utente mancanti: l’API lavora con i diritti dell’utente che ha creato il token o collegato l’app. Se in bexio non ha accesso ai contatti, nemmeno lo scope giusto aiuta.
- Nuovi scope al rinnovo: rinnovando un token i diritti restano gli stessi. Se l’app ha bisogno di più, l’utente deve accedere di nuovo.
- URL di reindirizzamento diverso: se l’indirizzo non è inserito esattamente così nell’app, l’accesso si interrompe con un messaggio di errore.
- Troppe richieste: l’API limita le richieste al minuto per azienda. Raggiunto il limite,
restituisce lo stato 429; le intestazioni
RateLimit-RemainingeRateLimit-Resetdicono quanto aspettare. - Nessun file OpenAPI: secondo la sua documentazione, bexio non fornisce una descrizione OpenAPI. Un client quindi non si genera automaticamente, ma si scrive in base al riferimento.
- Guasto anziché errore: se l’API non risponde affatto, conviene guardare la pagina di stato bexio-status.com prima di cercare nel proprio codice.
Soluzioni pronte
Se non vuoi gestire un token da solo, per i casi più frequenti esiste un collegamento pronto:
- Connettore moduli bexio: plugin WordPress, le richieste dal modulo del sito diventano contatti con nota in bexio. Il collegamento avviene con un clic su «Connetti a bexio», senza un’app propria e senza un token da rinnovare ogni 60 giorni.
- Collegare l’API di bexio a WordPress: la strada con la tua app, passo per passo, se costruisci da solo.