API di bexio da Make e Zapier: cosa i moduli pronti non sanno fare

Make e Zapier offrono bexio come app pronta all’uso: si compilano alcuni campi e la fattura è in contabilità. Nei forum delle due community, però, dal 2023 ci sono domande su bexio rimaste senza soluzione, perché al modulo manca un campo o un endpoint. Ho esaminato questi thread e li ho confrontati con la documentazione ufficiale dell’API di bexio. Questa guida mostra, caso per caso, dove il forum si è fermato e quale campo dell’API di bexio risolve il caso. Descrive i moduli così come li descrivono le persone che hanno posto la domanda; non si basa su un’esperienza personale con Make o Zapier.

Da dove vengono gli otto casi

I casi provengono dai forum pubblici community.make.com e community.zapier.com, domande dal 2023 al 2025. Ogni caso è linkato qui sotto. «Senza soluzione» significa: nel thread non c’è una risposta confermata da chi ha chiesto, oppure la risposta rimanda al supporto. Più persone segnalano lo stesso schema, a volte a mesi di distanza. La soluzione tramite API è ogni volta documentata; i percorsi stanno così nel riferimento.

Caso 1: più posizioni in una fattura

Il problema più frequente. In Make qualcuno vuole scrivere più posizioni in una fattura bexio; il modulo rifiuta l’elenco e «Update Invoice» non offre nessuna posizione. In Zapier la stessa cosa fallisce con un ordine Shopify con più prodotti, con un ordine WooCommerce tramite un giro con ciclo e memoria intermedia, e con un pagamento Payrexx, dove il messaggio dice che l’elenco degli importi non ha la stessa lunghezza dell’elenco degli articoli; alla fine resta una bozza senza posizioni con totale 0.

Nell’API non è un caso speciale. POST /2.0/kb_invoice accetta un array positions, e la documentazione dice espressamente che i tipi di posizione si possono combinare: KbPositionCustom per righe libere, KbPositionArticle per articoli dall’anagrafica, più posizioni di testo, subtotale, sconto e interruzione di pagina. Una fattura con due righe ha questo aspetto:

{
  "contact_id": 14,
  "user_id": 1,
  "mwst_type": 0,
  "mwst_is_net": true,
  "positions": [
    { "type": "KbPositionArticle", "article_id": 3, "amount": "2", "unit_price": "45.00", "tax_id": 4 },
    { "type": "KbPositionCustom", "text": "Spedizione", "amount": "1", "unit_price": "9.00", "tax_id": 4 }
  ]
}

bexio consiglia al massimo 150 posizioni alla creazione; le righe successive si aggiungono poi con POST /2.0/kb_invoice/{document_id}/kb_position_article o …/kb_position_custom. Spedizione e sconto sono così righe normali, senza percorsi speciali.

Caso 2: numero documento delle offerte

Un utente di Zapier non riesce a creare un’offerta: bexio richiede document_nr, l’azione non ha un campo per questo; una seconda persona con lo stesso problema si fa viva nello stesso thread. Un’altra non trova un’offerta tramite il numero, anche se lo stesso numero dà risultati in un altro strumento.

La documentazione di POST /2.0/kb_offer spiega la regola: document_nr non va impostato se in bexio è attiva la numerazione automatica, ed è obbligatorio se è disattivata. Un modulo senza questo campo funziona quindi solo con la numerazione automatica. Chi tiene numeri propri li passa tramite l’API. La ricerca avviene con POST /2.0/kb_offer/search e document_nr come campo di ricerca:

[{ "field": "document_nr", "value": "AN-00001", "criteria": "=" }]

Senza criteria bexio cerca con «like», cioè per corrispondenza parziale; per un numero, = è la via sicura. Gli stessi campi di ricerca esistono per le fatture sotto POST /2.0/kb_invoice/search.

Caso 3: aliquota IVA per posizione

Una fattura arriva in bexio con il 7,7 % invece dell’8,1 %, e l’aliquota non si può scegliere nel modulo. Zapier conferma nel thread una segnalazione di bug; la soluzione provvisoria è impostare l’aliquota sul prodotto in bexio.

Nell’API ogni posizione ha il suo campo tax_id. I valori validi arrivano da GET /3.0/taxes?types=sales_tax&scope=active; è proprio la chiamata che la documentazione consiglia, perché su offerte, ordini e fatture sono ammesse solo le imposte sulle vendite attive. La risposta indica per ogni aliquota id, code, value e gli anni di validità. Un servizio legge questo elenco una volta e sceglie la tax_id in base alla percentuale, invece di fissare un numero che diventa sbagliato al prossimo cambio di aliquota.

Caso 4: riferimento per la riconciliazione dei pagamenti

Qualcuno crea fatture da un foglio Google e vuole scrivere il numero di riferimento a 27 cifre nel campo riferimento, così che bexio assegni automaticamente i pagamenti dalla banca. Zapier registra una richiesta di funzionalità; nessuna data viene indicata.

La fattura nell’API ha due campi di riferimento. reference è un testo libero sul documento. api_reference, secondo la documentazione, si legge e si modifica solo tramite API e serve a conservare rimandi ad altri sistemi, per esempio il numero d’ordine del negozio o l’ID di pagamento del fornitore; è anche un campo di ricerca di POST /2.0/kb_invoice/search. La risposta di una fattura contiene inoltre qr_invoice_id. Un campo con cui impostare da sé il riferimento della sezione di pagamento QR non è descritto nella documentazione.

Chi riceve comunque il pagamento segnalato da un fornitore di pagamenti non ha bisogno della riconciliazione bancaria per questo: POST /2.0/kb_invoice/{invoice_id}/payment registra il pagamento direttamente sulla fattura con date, value e bank_account_id. Il pagamento risulta allora sulla fattura in bexio, e nessuno sollecita clienti che hanno pagato da tempo.

Caso 5: utente nella registrazione delle ore

Le registrazioni di ore da un foglio Google devono appartenere al collaboratore giusto in bexio. Nel modulo Zapier l’ID utente non si può impostare; il campo viene riempito con un contatto e chi chiede non trova una via d’uscita.

POST /2.0/timesheet richiede user_id come campo obbligatorio, insieme a client_service_id per la prestazione, allowable_bill per «fatturabile» e un oggetto tracking, come durata (type: duration con date e duration) oppure come intervallo (type: range). Gli utenti arrivano da GET /3.0/users, le prestazioni da GET /2.0/client_service. Contatto e progetto sono facoltativi (contact_id, pr_project_id). Una registrazione di un’ora e quaranta:

{
  "user_id": 1,
  "client_service_id": 1,
  "allowable_bill": true,
  "contact_id": 2,
  "tracking": { "type": "duration", "date": "2026-11-04", "duration": "01:40" }
}

Caso 6: PDF di un’offerta

Un utente di Make vuole archiviare le offerte come PDF in DocuWare. Per le fatture c’è un modulo, per le offerte no; il tentativo con una chiamata HTTP produce un PDF che non si apre. L’unica risposta rimanda alle basi di HTTP.

GET /2.0/kb_offer/{quote_id}/pdf restituisce il documento, con o senza carta intestata (logopaper). Il punto in cui la persona si è bloccata: la risposta non è un PDF, ma JSON con i campi name, size, mime e content, e content contiene il file codificato in Base64. Solo dopo la decodifica si ottiene un file PDF valido. Lo stesso vale per le fatture (/2.0/kb_invoice/{invoice_id}/pdf) e gli ordini (/2.0/kb_order/{order_id}/pdf).

Caso 7: riconoscere le fatture modificate

Il trigger di Make «Watch Invoices», secondo una persona del forum, non restituisce record quando una fattura viene solo modificata. Una persona che risponde sospetta un bug nel modulo, una seconda propone di usare invece una ricerca.

L’API offre per questo il campo di ricerca updated_at con criteri di confronto. Un servizio si annota il timestamp dell’ultima esecuzione e chiede:

[{ "field": "updated_at", "value": "2026-11-04 06:00:00", "criteria": ">" }]

a POST /2.0/kb_invoice/search?order_by=updated_at_desc. Il formato della data corrisponde a quello che bexio restituisce in updated_at. Così le fatture nuove e quelle modificate compaiono allo stesso modo, per esempio un cambio di stato a «pagata».

Caso 8: fattura da un ordine

Un ordine Shopify diventa in Make un ordine bexio; la fattura dovrebbe nascere da una chiamata HTTP, perché non c’è un modulo. La chiamata fallisce con stato 415, mentre la stessa chiamata funziona in Postman. Il supporto di Make conferma nel thread un problema noto («known issue») e lo passa allo sviluppo, senza una data.

L’endpoint è POST /2.0/kb_order/{order_id}/invoice. Il corpo è facoltativo: se manca, bexio riprende tutte le posizioni dell’ordine; altrimenti positions indica le righe desiderate con id, type e amount. Lo stato 415 significa che il server non accetta il tipo di contenuto della richiesta; la documentazione richiede Accept: application/json e JSON come corpo. Un servizio dedicato imposta da sé le intestazioni e non dipende da come un intermediario le inoltra.

Gli otto casi in sintesi

Si aggiunge un rischio che nessun campo copre: un utente di Zapier segnala che bexio ha bloccato il client ID dell’app Zapier e con esso la sua connessione si è fermata. Chi si collega tramite un’app di terzi dipende dalla sua autorizzazione; un’app propria nel Developer Portal dipende solo dalla tua. Come crearla è spiegato nella guida Creare un token di accesso all’API di bexio, l’accesso con OAuth 2 nella guida Collegare l’API di bexio a WordPress.

Quando conviene il collegamento diretto

Per un contatto da un modulo, i moduli pronti di solito bastano. Appena entrano in gioco fatture con più righe, numeri propri, aliquote IVA, registrazioni di ore per collaboratore o PDF, il giro attraverso la piattaforma intermedia costa più tempo di quanto ne faccia risparmiare: ogni campo mancante diventa un thread di forum senza fine.

Un’interfaccia che parla direttamente con l’API di bexio la costruisco a prezzo fisso: mi indichi il sistema di partenza e il flusso, io definisco l’ambito sui tuoi documenti reali, il collegamento gira sulla tua infrastruttura senza abbonamento presso terzi, con nuovo tentativo in caso di errore e un registro che mostra cosa è stato trasmesso. Per HubSpot il collegamento esiste già: bexio ↔ HubSpot trasforma un deal vinto in offerta o fattura con le posizioni e riporta lo stato del pagamento. Per tutto il resto: Contatto, con il sistema di partenza e ciò che oggi si fa a mano.

Tutte le guide