Nell'era della trasformazione digitale mobile-first, integrare le applicazioni aziendali con piattaforme mobili non è più una tendenza, ma una necessità strategica. Dolibarr ERP & CRM, noto per la sua architettura modulare open source, offre una robusta API REST che consente agli sviluppatori di collegare applicazioni esterne, comprese le app mobili, direttamente al sistema centrale. Questa flessibilità apre la strada a flussi di lavoro ottimizzati, sincronizzazione dei dati in tempo reale e una migliore esperienza utente.

Che tu sia una piccola impresa che desidera estendere i propri strumenti interni, una software house che sviluppa un client mobile per Dolibarr o un consulente IT che progetta una soluzione ibrida, questo articolo è la tua guida completa. Copriremo tutto: fondamentali dell'API, autenticazione, endpoint, casi d'uso, gestione degli errori e buone pratiche per un'integrazione mobile sicura e scalabile.

Comprendere l’API REST di Dolibarr

L'API REST di Dolibarr espone un'ampia gamma di endpoint corrispondenti ai moduli principali del sistema, come fatture, clienti, prodotti, ordini e progetti. Basata sui metodi HTTP standard (GET, POST, PUT, DELETE), segue i principi RESTful, risultando facilmente accessibile da qualsiasi piattaforma che supporta HTTP.

Introdotta nella versione 5.0 e notevolmente migliorata tra le versioni 10 e 16, nel 2025 l'API REST è compatibile con le versioni di Dolibarr 14 e successive, con gli ultimi aggiornamenti di sicurezza e miglioramenti nella struttura dei dati.

Perché usare l’API REST per un'app mobile?

Integrare un'app mobile con l'API REST di Dolibarr offre numerosi vantaggi:

• Sincronizzazione in tempo reale di dati come prodotti, stock e fatture

• Accesso personalizzato ai moduli CRM, contabilità o HR

• Accesso sul campo per venditori, tecnici o corrieri

• Notifiche push per nuovi lead o pagamenti in ritardo

• Funzionalità offline con sincronizzazione differita

Prerequisiti e configurazione dell’ambiente

Per iniziare ti serviranno:

• Un'installazione funzionante di Dolibarr (versione 14 o superiore consigliata)

• Accesso amministrativo a Dolibarr

• Attivazione dell’API nelle impostazioni

• Una chiave API o token OAuth

• Un’app mobile o framework di sviluppo (Flutter, React Native, Android Studio, ecc.)

Attivare il modulo API in Dolibarr:

1. Vai su Configurazione > Moduli/App

2. Attiva il modulo API REST

3. Vai su Utenti > Elenco > Modifica

4. Genera e copia la chiave API per l'utente

Opzionale: installa il plugin APIGateway o configura le regole CORS se l'app è basata sul web.

Autenticazione: chiave API vs OAuth2

Dolibarr supporta due metodi di autenticazione:

Chiave API (token)

• Facile da implementare

• Ideale per app interne o a utente singolo

• Inviata come header: DOLAPIKEY: tua_chiave

OAuth2

• Più sicuro e scalabile

• Raccomandato per app pubbliche con più utenti

• Richiede client ID, secret e URI di reindirizzamento

Usa OAuth2 se l’app sarà distribuita su store o destinata a clienti esterni.

Struttura dell'API REST e endpoint disponibili

L’API Dolibarr è basata su un endpoint principale:

https://iltuodominio.com/api/index.php

Ogni risorsa (clienti, prodotti, fatture) ha un percorso dedicato:

Esempi:

• GET /thirdparties – Elenco clienti o fornitori

• POST /thirdparties – Crea un nuovo cliente

• GET /products – Lista prodotti

• POST /invoices – Crea una fattura

• GET /users/me – Info utente corrente

Tutte le richieste devono essere autenticate e restituiscono risposte JSON.

Casi d’uso comuni per app mobili

1. App CRM mobile

• Visualizza dati e contatti dei clienti

• Aggiungi/modifica lead

• Storico attività

• Pianifica incontri o follow-up

2. App per ordini/vendite

• Naviga prodotti con immagini e prezzi

• Crea ordini o preventivi

• Verifica disponibilità

• Trasforma preventivi in fatture

3. App per tecnici sul campo

• Visualizza progetti o ticket assegnati

• Aggiorna lo stato delle attività

• Registra ore lavorate

• Allega foto o file

4. App per inventario

• Scannerizza codici a barre

• Aggiorna le quantità

• Ricevi merci

• Registra movimenti di magazzino

Gestione delle risposte ed errori

Le risposte seguono i codici HTTP standard:

• 200 OK – Successo

• 201 Created – Creazione riuscita

• 400 Bad Request – Dati errati

• 401 Unauthorized – Credenziali errate

• 403 Forbidden – Accesso negato

• 500 Internal Server Error – Errore API

Struttura JSON tipica:

{
  "success": true,
  "error": null,
  "data": {...}
}

Controlla success e gestisci gli errori nell'interfaccia mobile.

Paginazione e filtri

Per liste (es. prodotti, clienti), l’API supporta:

• limit=25&sortfield=lastname&sortorder=asc

• sqlfilters=(status:in:(1,2))

Utile per migliorare la velocità e ridurre il consumo dati.

Upload di file e allegati

L’API REST supporta l’invio di file (contratti, PDF, immagini).

Esempio:

POST /documents/upload
Headers:
  DOLAPIKEY: tua_chiave
Body (multipart/form-data):
  refid, ref, modulepart, file

Usa questa funzione per allegare file a fatture o interventi.

Sicurezza: raccomandazioni essenziali

• Usa sempre HTTPS

• Limita gli IP se possibile

• Preferisci OAuth2 per app pubbliche

• Implementa rate limiting

• Non salvare mai la chiave API nel codice sorgente

Sviluppo mobile: framework consigliati

Alcune opzioni:

• Flutter: veloce e multi-piattaforma

• React Native: basato su JS con ampio ecosistema

• Android/iOS nativi: per massime prestazioni

Librerie utili: axios (JS), http (Dart), Retrofit (Java).

Best practice per il deployment

• Gestisci versioni della tua interfaccia API

• Memorizza in cache i dati statici localmente

• Monitora errori con logging e analytics

• Sincronizzazione in background

• Testa con vari dispositivi e modalità offline

Problemi comuni e soluzioni

Errore 401: verifica che la chiave API sia corretta e nel header

Errore CORS: configura i permessi su Apache/Nginx o usa un proxy

Risposta HTML invece di JSON: controlla endpoint e header Accept: application/json

Esempio reale: app Flutter per gestione clienti

Un’app Flutter semplice può:

• Autenticarsi via API key

• Recuperare i clienti con GET /thirdparties

• Mostrare info in una lista

• Visualizzare ordini GET /orders?fk_soc=ID

• Aggiornare dati con PUT /thirdparties/ID

Conclusione

Connettere un’app mobile a Dolibarr tramite API REST consente una gestione moderna, efficace e flessibile. Che tu sviluppi per uso interno o commerciale, l’API REST è la chiave per estendere Dolibarr al mondo mobile, mantenendo controllo, sicurezza e scalabilità.