API bexio: La Guida Completa 2026 per Freelancer Svizzeri

Cosa Sono le API bexio?

Un'API (Application Programming Interface) permette a diversi sistemi software di scambiarsi dati automaticamente. Le API bexio sono un'interfaccia RESTful che espone le funzionalità principali di bexio—contatti, fatture, contabilità, inventario—ad applicazioni esterne.

In pratica: invece di creare manualmente una fattura in bexio dopo aver completato un progetto, il tuo strumento di gestione progetti può generarla automaticamente. Invece di copiare i dati dei clienti dal webshop, gli ordini confluiscono direttamente in bexio.

Le API usano HTTPS e formato JSON, rendendole compatibili con qualsiasi linguaggio di programmazione. bexio offre attualmente la versione API 3.0.0.

Cosa Puoi Automatizzare

Automazioni Zapier Popolari per Freelancer

1. Shopify → bexio: Nuovo ordine crea fattura automaticamente
2. Toggl → bexio: Ore registrate sincronizzate al progetto
3. HubSpot → bexio: Nuovo contatto CRM crea contatto bexio
4. Gmail → bexio: Allegato email crea voce di spesa

Autenticazione nel Dettaglio

bexio usa OAuth 2.0, lo standard industriale per l'autorizzazione API. Comprendere il sistema di doppia autorizzazione è cruciale.

Due Livelli di Autorizzazione

Livello 1: Scope dell'Applicazione Quando gli utenti collegano la tua app, concedono permessi specifici (scope). Richiedi solo ciò di cui hai bisogno—gli utenti vedono questi permessi nella schermata di consenso.

Categorie di scope disponibili:

• contact_show, contact_edit — Gestione contatti
• kb_invoice_show, kb_invoice_edit — Accesso fatture
• accounting_show — Lettura dati contabili
• article_show, article_edit — Gestione prodotti

Livello 2: Diritti Utente Le richieste API vengono eseguite con i permessi dell'utente che ha autorizzato la connessione. Se quell'utente non può eliminare fatture in bexio, nemmeno la tua API potrà farlo.

Flusso OAuth 2.0

1. La tua app reindirizza l'utente a:
   https://auth.bexio.com/realms/bexio/protocol/openid-connect/auth
   ?client_id=YOUR_CLIENT_ID
   &redirect_uri=YOUR_REDIRECT_URL
   &response_type=code
   &scope=contact_show kb_invoice_edit

2. L'utente accede e approva i permessi

3. bexio reindirizza al tuo URL con codice di autorizzazione

4. Scambia il codice per token su:
   https://auth.bexio.com/realms/bexio/protocol/openid-connect/token

5. Usa l'access token per le richieste API

Gestione token:

• Gli access token hanno vita breve (tipicamente 1 ora)
• I refresh token ottengono nuovi access token senza interazione utente
• Conserva i refresh token in modo sicuro e implementa il refresh automatico

Soluzioni per l'Assenza di Webhook

• Polling: Controlla le modifiche periodicamente (ogni 5-15 minuti)
• Zapier: Usa polling ma gestisce l'infrastruttura
• Servizi webhook di terze parti: Alcune piattaforme di integrazione offrono funzionalità pseudo-webhook

Gestire i Rate Limit

Basandosi sull'esperienza della community:

• Implementa exponential backoff su errori 429
• Metti in cache le risposte dove possibile
• Raggruppa le richieste quando l'API lo supporta
• Evita frequenze di polling non necessarie

Librerie Client Limitate

Non esistono SDK ufficiali. Le librerie della community sono incomplete. Per applicazioni in produzione, aspettati di scrivere codice personalizzato.

Magic Heidi Invoice API

La Magic Heidi Swiss Invoice QR Code API è un'API aperta a singolo endpoint per generare fatture svizzere professionali con bollettini di pagamento QR. Nessun OAuth, nessun refresh token, nessuno scope—solo una API key e una richiesta POST.

Come Funziona

1. Invia una richiesta POST con i dati della fattura (mittente, cliente, voci)
2. Ricevi un URL di download del PDF valido per 24 ore
3. Tutto qui—nessun flusso OAuth, nessuna registrazione al portale sviluppatori

Esempio Python

import requests

response = requests.post(
    "https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d",
    headers={"key": "your_api_key"},
    json={
        "user_details": {
            "name": "Muster GmbH",
            "address": "Bahnhofstrasse 1",
            "zip": "8001",
            "city": "Zurich",
            "iban": "CH93 0076 2011 6238 5295 7"
        },
        "customer_details": {
            "name": "Acme AG",
            "address": "Bundesplatz 3",
            "zip": "3011",
            "city": "Bern"
        },
        "invoice_items": [
            {
                "description": "Web Development",
                "quantity": 10,
                "unit_price": 150
            },
            {
                "description": "Design Review",
                "quantity": 3,
                "unit_price": 120
            }
        ],
        "language": "en",
        "currency": "CHF",
        "vat_enabled": true,
        "vat_percentage": 8.1,
        "vat_number": "CHE-123.456.789 MWST"
    }
)

data = response.json()
print(f"Download your invoice: {data['url']}")

Esempio JavaScript (Node.js)

const axios = require('axios');

const response = await axios.post(
  'https://europe-west6-magic-heidi.cloudfunctions.net/create_invoice_abstract_v1d',
  {
    user_details: {
      name: 'Muster GmbH',
      address: 'Bahnhofstrasse 1',
      zip: '8001',
      city: 'Zurich',
      iban: 'CH93 0076 2011 6238 5295 7'
    },
    customer_details: {
      name: 'Acme AG',
      address: 'Bundesplatz 3',
      zip: '3011',
      city: 'Bern'
    },
    invoice_items: [
      { description: 'Web Development', quantity: 10, unit_price: 150 },
      { description: 'Design Review', quantity: 3, unit_price: 120 }
    ],
    language: 'en',
    currency: 'CHF'
  },
  { headers: { key: 'your_api_key' } }
);

console.log(`Download your invoice: ${response.data.url}`);

Caratteristiche Principali

• Fatture svizzere con QR code conformi agli standard di pagamento svizzeri
• Multi-lingua: inglese, tedesco, francese, italiano
• CHF ed EUR supporto valute
• Gestione IVA con aliquote configurabili e numero IVA
• Loghi personalizzati tramite URL
• Modalità solo QR per generare solo il bollettino di pagamento
• Test gratuiti senza API key
• Documentazione aperta su GitHub

Risorse

• Magic Heidi Invoice API — GitHub
• Generare Fatture Svizzere con QR Code in Modo Programmatico — Articolo Blog
• Portale Sviluppatori bexio
• Documentazione API bexio
• Pagina Stato bexio
• Marketplace bexio — oltre 120 integrazioni pre-costruite