Collegare l’API di bexio a WordPress

Una richiesta dal modulo del sito deve arrivare in bexio come contatto, un ordine come fattura, un cliente del negozio come indirizzo. Per questo WordPress deve parlare con l’API di bexio. Questa guida mostra il percorso dall’app nel Developer Portal al primo contatto creato, le insidie lungo la strada e quando un plugin pronto conviene più di codice proprio.

Che cos’è l’API di bexio

L’API di bexio è un’interfaccia REST in JSON. Tutti gli endpoint si trovano sotto https://api.bexio.com, i percorsi iniziano secondo l’ambito con /2.0/, /3.0/ o più recenti, per esempio /2.0/contact per i contatti e /3.0/users/me per l’utente connesso. Il riferimento è su docs.bexio.com. Secondo la sua documentazione, bexio non offre una descrizione OpenAPI; un client si scrive quindi a mano.

Ogni accesso richiede un access token nell’intestazione Authorization: Bearer …. Come WordPress ottiene questo token è il vero lavoro.

Passo 1: creare un’app nel Developer Portal

1. Accedere al Developer Portal con l’account bexio.
2. Leggere e accettare le condizioni d’uso, in particolare la cifra 4.4 sull’uso commerciale (vedi le insidie).
3. Creare una nuova app e inserire l’URL di reindirizzamento a cui bexio rimanda dopo l’accesso, per esempio la pagina delle impostazioni del plugin nell’amministrazione WordPress. Sono possibili fino a dieci indirizzi, per esempio per test e produzione.
4. Leggere Client ID e Client Secret sotto «App Details».

Il Client Secret resta sul server, mai in JavaScript nel browser.

Passo 2: accedere con OAuth 2

bexio gestisce l’accesso con OpenID Connect su auth.bexio.com, con l’«Authorization Code Flow». WordPress manda l’utente alla pagina di accesso di bexio:

https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
  ?client_id=<Client ID>
  &redirect_uri=<URL di reindirizzamento registrato>
  &response_type=code
  &scope=openid offline_access contact_edit note_edit
  &state=<valore casuale>

L’utente accede e conferma i diritti. bexio rimanda con un codice, che WordPress scambia, insieme a Client ID e Secret, presso l’endpoint del token /realms/bexio/protocol/openid-connect/token con un access token e un refresh token.

Sugli scope: un diritto di scrittura include quello di lettura, quindi contact_edit basta anche per cercare. offline_access serve per il refresh token. E l’API lavora sempre con i diritti dell’utente che ha creato il collegamento: se in bexio non può vedere i contatti, non può neanche l’app.

Passo 3: salvare e rinnovare i token

L’access token scade presto. Prima, WordPress ne ottiene uno nuovo con il refresh token e grant_type=refresh_token, tutti i valori nel corpo della richiesta, non nell’URL. Da tenere presente:

• Salvare sempre il nuovo refresh token restituito al rinnovo.
• Se un collegamento resta un anno senza rinnovo, bexio chiude la sessione; poi qualcuno deve accedere di nuovo.
• Salvare i token in opzioni WordPress senza autoload, perché non vengano caricati a ogni pagina.

Per i propri script esistono anche i token di accesso personali (PAT). Hanno accesso completo a tutti i dati dell’azienda e valgono 60 giorni. Comodi per uso personale, non sono adatti a un plugin installato sul sito di un cliente.

Passo 4: creare contatto e nota

Uno svolgimento tipico per una richiesta dal modulo richiede quattro chiamate:

1. GET /3.0/users/me restituisce l’ID dell’utente. È obbligatorio alla creazione, come user_id e owner_id.
2. POST /2.0/contact/search cerca tramite l’indirizzo e-mail se il contatto esiste già.
3. Altrimenti: POST /2.0/contact lo crea, contact_type_id 1 per le aziende, 2 per le persone.
4. POST /2.0/note aggiunge il testo del modulo come nota al contatto.

La chiamata per creare un’azienda è così:

{
  "contact_type_id": 1,
  "name_1": "Esempio SA",
  "street_name": "Via Nassa",
  "house_number": "1",
  "postcode": "6900",
  "city": "Lugano",
  "mail": "info@esempio.ch",
  "user_id": 1,
  "owner_id": 1
}

Insidie tipiche

• URL di reindirizzamento: deve figurare esattamente così nel Developer Portal, altrimenti l’accesso si interrompe con un messaggio d’errore.
• Nuovi scope: i diritti di un collegamento non cambiano al rinnovo. Se l’app ha bisogno di più, l’utente deve accedere di nuovo.
• Campi indirizzo: il campo address è obsoleto alla creazione. Via e numero vanno in street_name e house_number.
• A capo nelle note: bexio mostra il testo di una nota senza a capo. Per i paragrafi usare <br> e codificare i valori in HTML.
• Limite di richieste: con troppe richieste al minuto l’API risponde con lo stato 429. Le intestazioni RateLimit-Remaining e RateLimit-Reset dicono quanto attendere.
• Moduli lenti: chiamare bexio all’invio fa aspettare il visitatore e perde la richiesta se bexio non risponde. Meglio trasmettere in background e riprovare in caso di errore.
• Uso commerciale: secondo la cifra 4.4 delle condizioni, deve informare bexio chi gestisce sull’API un proprio modello di business a cui sono collegati almeno cinque account bexio.

Tre approcci a confronto

Make e Zapier offrono bexio come app propria. Il plugin del modulo invia la richiesta via webhook e un’azione bexio crea il contatto.

Soluzioni pronte

Per i due casi più frequenti ci sono i miei collegamenti:

• Connettore moduli bexio: plugin WordPress, le richieste dal modulo del sito diventano contatti con nota in bexio, i duplicati vengono riconosciuti dall’e-mail. Ogni gestore collega il proprio bexio con una propria app, i dati vanno direttamente dal sito a bexio.
• bexio ↔ HubSpot: un deal vinto in HubSpot diventa offerta o fattura in bexio, lo stato del pagamento torna nel deal.

Tutte le guide