Guida all'Integrazione API

API Bexio: La Guida 2025 per Freelancer Svizzeri

Collega il software gestionale più usato in Svizzera con qualsiasi strumento. Configurazione OAuth 2.0, esempi di codice e la cruciale migrazione autenticazione 2025.

Illustrazione Integrazione API

Basta con l'Inserimento Manuale.
Automatizza Tutto.

Passi ore a inserire dati manualmente tra i tuoi strumenti. Il software di fatturazione non comunica con il CRM. L'e-commerce richiede di copiare ordini nella contabilità. Le API Bexio risolvono questo problema—collegando oltre 40'000 aziende svizzere con praticamente qualsiasi altro strumento.

⏰
5+ Ore a SettimanaPerse in inserimento dati manuale
🔗
Strumenti ScollegatiApp che non comunicano tra loro
📋
Caos Copia-IncollaOrdini inseriti manualmente in contabilità

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

FunzioneCapacità API
ContattiCreare, aggiornare, elencare clienti e fornitori
FattureGenerare, inviare, monitorare stato pagamenti
OrdiniCreare da sistemi esterni, aggiornare stato
ProdottiSincronizzare inventario, aggiornare giacenze
ContabilitàRecuperare conti, registrare transazioni
ProgettiCreare, assegnare, tracciare tempo
⚠️ Aggiornamento Critico

Migrazione Autenticazione 2025

Se hai integrazioni API Bexio esistenti, leggi prima questo.

Bexio disattiverà idp.bexio.com il 31 marzo 2025. Tutte le applicazioni devono migrare al nuovo identity provider:

Vecchio: https://idp.bexio.com
Nuovo: https://auth.bexio.com/realms/bexio

Per la maggior parte delle applicazioni, la migrazione richiede solo l'aggiornamento degli URL di autorizzazione e token. Tuttavia, se non migri entro la scadenza, la tua integrazione smetterà di funzionare.

Checklist migrazione:

  1. Aggiorna l'URL di autorizzazione nella configurazione dell'app
  2. Aggiorna l'URL del token endpoint
  3. Testa il flusso OAuth completo prima di marzo 2025
  4. Monitora la pagina di stato Bexio su bexio-status.com per annunci

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
Setup Sviluppatori

Iniziare con le API Bexio

Tutto ciò che devi sapere per la tua prima integrazione

Prerequisiti

  1. Account Bexio: Qualsiasi piano a pagamento (Starter CHF 45/mese, Pro CHF 75/mese, Pro+ CHF 125/mese). L'accesso API è incluso.
  2. Accesso al Portale Sviluppatori: Visita il Portale Sviluppatori Bexio e accedi con le tue credenziali Bexio.

Creare Credenziali API

  1. Naviga su "My Apps" nel portale sviluppatori
  2. Clicca "Create New App"
  3. Imposta un Redirect URL (richiesto per il flusso OAuth)
  4. Salva immediatamente Client ID e Client Secret—non vedrai più il secret

🔒 Nota sicurezza: Non salvare mai le credenziali nel version control. Usa variabili d'ambiente o un secrets manager.

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
Esempi di Codice

Implementazione in Più Linguaggi

Snippet di codice pronti all'uso per Python, JavaScript e PHP

Python

Python è popolare tra i freelancer svizzeri per script di automazione. Anche se non esiste una libreria ufficiale, la bexio-api-python-client mantenuta dalla community offre un punto di partenza.

import requests

BASE_URL = "https://api.bexio.com/2.0"
ACCESS_TOKEN = "your_access_token"

headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Accept": "application/json"
}

# Recupera tutti i contatti
response = requests.get(f"{BASE_URL}/contact", headers=headers)
contacts = response.json()

for contact in contacts:
    print(f"{contact['id']}: {contact['name_1']}")

# Crea nuova fattura
invoice_data = {
    "contact_id": 1,
    "title": "Lavoro Progetto - Gennaio 2025",
    "positions": [
        {
            "type": "KbPositionCustom",
            "text": "Servizi di Consulenza",
            "unit_price": "150.00",
            "amount": "10"
        }
    ]
}

response = requests.post(
    f"{BASE_URL}/kb_invoice",
    headers=headers,
    json=invoice_data
)
print(response.json())

JavaScript (Node.js)

const axios = require('axios');

const BASE_URL = 'https://api.bexio.com/2.0';
const ACCESS_TOKEN = process.env.BEXIO_TOKEN;

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${ACCESS_TOKEN}`,
    'Accept': 'application/json'
  }
});

// Recupera contatti
async function getContacts() {
  const response = await api.get('/contact');
  return response.data;
}

// Crea contatto
async function createContact(contactData) {
  const response = await api.post('/contact', {
    contact_type_id: 1, // 1 = Azienda, 2 = Persona
    name_1: contactData.company,
    name_2: contactData.name,
    mail: contactData.email,
    country_id: 1 // Svizzera
  });
  return response.data;
}

getContacts().then(contacts => console.log(contacts));

PHP

La libreria onlime/bexio-api-client su GitHub fornisce integrazione PHP:

<?php
require 'vendor/autoload.php';

use Bexio\Client;

$client = new Client([
    'clientId' => 'your_client_id',
    'clientSecret' => 'your_client_secret',
]);

$client->setAccessToken('your_access_token');

// Ottieni tutti i contatti
$contacts = $client->getContacts();

// Crea fattura
$invoice = $client->createInvoice([
    'contact_id' => 1,
    'title' => 'Servizi Sviluppo Web',
    'positions' => [
        [
            'type' => 'KbPositionCustom',
            'text' => 'Sviluppo Frontend',
            'unit_price' => '120.00',
            'amount' => '20'
        ]
    ]
]);

Nota: Sia le librerie Python che PHP della community coprono solo un sottoinsieme dei metodi API. Per funzionalità complete, potresti dover fare chiamate HTTP dirette.

Esempi di Integrazione Reali

E-Commerce: Shopify + Bexio

L'integrazione Shopware-Bexio dimostra cosa è possibile:

  • Generazione automatica fatture basata su metodo di pagamento
  • Creazione contatti dagli account clienti
  • Sincronizzazione stato ordini
  • Aggiornamenti inventario tra piattaforme

Per Shopify, usa Zapier o costruisci un'integrazione personalizzata che:

  1. Ascolta nuovi ordini Shopify (webhook o polling)
  2. Crea/aggiorna contatto Bexio dai dati cliente
  3. Genera fattura con righe articoli
  4. Opzionalmente invia la fattura automaticamente

Time Tracking: Toggl + Bexio

Collega il tracciamento tempo alla fatturazione:

  1. Crea progetti corrispondenti in entrambi i sistemi
  2. Quando il tempo viene registrato in Toggl, sincronizza al progetto Bexio
  3. Genera fattura dalle ore accumulate
  4. Includi dettaglio ore nella fattura

CRM: HubSpot + Bexio

Mantieni vendite e contabilità allineate:

  • Nuovo deal HubSpot chiuso → Crea fattura Bexio
  • Contatto HubSpot aggiornato → Sincronizza a contatto Bexio
  • Fattura Bexio pagata → Aggiorna stato deal HubSpot

Limitazioni API
e Soluzioni Alternative

Essere trasparenti su cosa l'API non può fare ti risparmia ore di frustrazione. Le API Bexio hanno limitazioni—ma conoscerle in anticipo ti aiuta a pianificare meglio.

🔔
Nessun Webhook NativoUsa polling o Zapier come alternative
🚦
Rate Limit Non DocumentatiImplementa backoff e caching
🧪
Nessun Ambiente SandboxTesta con dati reali con cautela

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
  • Cacha 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 del codice personalizzato.

Sicurezza

Best Practice di Sicurezza

Proteggi la tua integrazione e i dati dei tuoi clienti

Prezzi

Piani Bexio e Accesso API

Piani attuali 2025—tutti includono accesso API

FunzionalitàStarterProPro+
PrezzoCHF 45/meseCHF 75/meseCHF 125/mese
Utenti1 utenteFino a 3Fino a 25
Accesso API✓ Incluso✓ Incluso✓ Incluso
App bexio Go✗ No✓ Inclusa✓ Inclusa
Prova Gratuita30 giorni30 giorni30 giorni (funzioni Pro+)
Alternativa più Semplice

Quando le API Bexio Sono Eccessive

Non tutti i freelancer svizzeri hanno bisogno di integrazioni API. Se invii meno di 10 fatture al mese, non usi più strumenti aziendali, o trovi OAuth 2.0 intimidatorio—considera alternative più semplici. Magic Heidi offre fatturazione semplificata per freelancer svizzeri a CHF 30/mese. Nessuna complessità API richiesta.

Lista Fatture Magic Heidi
FAQ

Domande Frequenti

Le API Bexio sono gratuite?

Sì, l'accesso API è incluso in tutti i piani Bexio a pagamento (da CHF 45/mese).

Quali linguaggi di programmazione funzionano con le API?

Qualsiasi linguaggio che possa fare richieste HTTP—Python, JavaScript, PHP, C#, Ruby, Go, ecc.

Posso usare le API senza programmare?

Sì. Zapier e Make.com offrono automazione no-code con Bexio.

Bexio supporta i webhook?

Non nativamente. Usa polling o Zapier come alternative.

Quali sono i rate limit delle API?

Non documentati pubblicamente. Implementa backoff e caching come precauzione.

Esiste un ambiente test/sandbox?

No. Testa con dati reali con cautela.

Quando devo migrare l'autenticazione?

Prima del 31 marzo 2025. Il vecchio endpoint idp.bexio.com smetterà di funzionare.

Risorse

Cerchi una Fatturazione Svizzera più Semplice?

Magic Heidi gestisce fatture QR, spese e IVA—disponibile su ogni piattaforma. Nessuna complessità API richiesta.

Inizia la Prova GratuitaConfronta con Bexio
App Store Google Play Microsoft Store App Web