Come utilizzare l'API di Dolibarr per automatizzare i processi

Sincronizza i tuoi clienti, crea automaticamente le fatture, collega il tuo sito web al tuo ERP... L'API REST di Dolibarr apre le porte all'automazione. Ecco una guida completa per iniziare e liberare tempo dalle attività ripetitive.

Automazione · API REST · Dolibarr • Livello intermedio

1. Cos'è l'API REST di Dolibarr?

2. Perché automatizzare i processi con le API?

3. Passaggio 1: Attivare il modulo API REST

4. Passaggio 2: Genera e proteggi la tua chiave API

5. Fase 3: Scopri l'API Explorer

6. Comprendere gli endpoint e la loro struttura

7. Fase 4: Le vostre prime richieste in pratica

8. Scenari concreti di automazione

9. Gestione multi-azienda, risposte ed errori

10. Buone pratiche per l'automazione sostenibile

11. Domande frequenti

12. Conclusione: Lasciate che Dolibarr lavori per voi

Quante ore dedicate ogni settimana a copiare informazioni da un programma all'altro? A creare manualmente le schede dei clienti, a generare le fatture una per una, a esportare e poi reimportare i dati tra il vostro sito web e il vostro strumento gestionale? Queste attività ripetitive, oltre a essere dispendiose in termini di tempo, sono fonte di errori e frustrazione.

La soluzione ha un nome: automazione . E per gli utenti di Dolibarr, si basa su uno strumento potente e spesso sottovalutato: l'API REST . Integrata nel cuore del software, questa interfaccia di programmazione consente ad altre applicazioni di comunicare direttamente con il vostro Dolibarr, leggendo e scrivendo dati senza alcun intervento manuale.

In questa guida completa, sveleremo i segreti dell'API di Dolibarr. Scoprirai cos'è un'API REST, come attivarla e proteggerla, come effettuare le prime richieste e, soprattutto, come utilizzarla efficacemente per automatizzare i processi aziendali. Ti basteranno pochi concetti tecnici di base: li spiegheremo passo dopo passo. Alla fine, sarai in grado di trasformare ore di lavoro manuale in poche righe di codice che verranno eseguite automaticamente.

Che cos'è l'API REST di Dolibarr?

Partiamo dalle basi. Un'API ( Application Programming Interface) è un insieme di regole che permette a due programmi software di comunicare tra loro. Anziché cliccare su un'interfaccia, un programma invia richieste strutturate e riceve risposte, il tutto in modo automatico.

L'API di Dolibarr è basata su REST , uno standard web che si avvale di richieste HTTP, le stesse utilizzate dal browser. Lo scambio di dati avviene in formato JSON , un formato di testo leggero e leggibile, compatibile con praticamente tutti i linguaggi di programmazione. In pratica, questo significa che è possibile controllare Dolibarr da uno script PHP, Python o JavaScript, o persino da un semplice strumento da riga di comando.

Integrata nativamente in Dolibarr da diverse versioni, questa API fornisce accesso alla maggior parte delle funzionalità del software: terze parti, prodotti, ordini, fatture, utenti e molto altro. Rappresenta la pietra angolare di qualsiasi integrazione e automazione intorno al vostro ERP.

Le quattro operazioni fondamentali

L'API si basa su quattro azioni fondamentali, che corrispondono ai metodi HTTP. Queste vengono spesso definite operazioni CRUD (Create, Read, Update, Delete):

•     GET — lettura dei dati (consultazione dell'elenco clienti, recupero di una fattura).

•     POST — crea un nuovo elemento dati (aggiungi un prodotto, crea una terza parte).

•     PUT — aggiorna i dati esistenti (modifica una fattura).

•     CANCELLA — elimina un dato.

Perché automatizzare i processi con le API?

Prima di addentrarci nei dettagli tecnici, consideriamo i vantaggi concreti. L'automazione tramite API non è un lusso per gli sviluppatori: è una leva di produttività con risultati tangibili.

Risparmia tempo prezioso

Ogni attività ripetitiva automatizzata libera tempo prezioso per la tua azienda. Sincronizzare centinaia di clienti, generare decine di fatture, aggiornare un catalogo prodotti: ciò che prima richiedeva ore ora si completa in pochi secondi, senza bisogno di supervisione.

Eliminare gli errori di input

L'inserimento manuale è la principale fonte di errori: una cifra invertita, una riga dimenticata, un duplicato. Affidando il trasferimento delle informazioni a un programma, si garantisce la coerenza e l'affidabilità dei dati tra i diversi strumenti utilizzati.

Connetti il tuo ecosistema

L'API consente a Dolibarr di comunicare con il resto del tuo software: il tuo sito di e-commerce , il tuo strumento di contabilità, il tuo CRM, un'applicazione mobile personalizzata o piattaforme di automazione. Il tuo ERP cessa di essere un'isola isolata e diventa il centro nevralgico di un sistema interconnesso.

Lavorando in tempo reale

Un ordine effettuato sul tuo sito web crea istantaneamente il cliente e l'ordine in Dolibarr. Il pagamento ricevuto aggiorna la fattura. Questa sincronizzazione in tempo reale offre una visione sempre aggiornata della tua attività e semplifica tutte le tue operazioni.

Passaggio 1: Attivare il modulo API REST

Innanzitutto, è necessario attivare l'API in Dolibarr. Vai su Home → Configurazione → Moduli/Applicazioni , quindi trova e attiva il modulo Servizi Web API REST . Questa operazione richiede i privilegi di amministratore.

Una volta attivato il modulo, verifica che l'API risponda. È disponibile all'indirizzo /api/index.php della tua installazione. Se Dolibarr è in esecuzione su Apache, l'API è generalmente disponibile senza configurazioni aggiuntive. Con Nginx, potrebbe essere necessario modificare la configurazione del server per consentire l'accesso alle richieste API.

Passaggio 2: Genera e proteggi la tua chiave API

l'autenticazione tramite chiave API (un token). Ogni utente può avere una o più chiavi. Per generarne una, accedi, apri il profilo dell'utente in Utenti e gruppi , quindi vai alla scheda Chiave API e generala. Copia questa chiave e conservala in un luogo sicuro.

Questa chiave deve quindi accompagnare ciascuna delle tue richieste. Viene trasmessa in un'intestazione HTTP specifica:

Fondamentalmente, l'autenticazione è legata ai diritti dell'utente. La chiave eredita le autorizzazioni dell'utente che l'ha generata. Pertanto, una richiesta può eseguire solo le azioni che tale utente è autorizzato a compiere in Dolibarr. Si tratta di un meccanismo di sicurezza fondamentale che deve essere utilizzato con intelligenza.

Buone pratiche di sicurezza

Una chiave API è altrettanto sensibile di una password. È necessario seguire alcune regole per evitare di trasformare il punto di accesso in una vulnerabilità di sicurezza:

•     Crea un utente API dedicato con i soli diritti strettamente necessari per l'automazione desiderata. Non utilizzare mai un account amministratore.

•     Utilizza una chiave per applicazione . In caso di compromissione, puoi revocare la chiave in questione senza influire sulle altre integrazioni.

•     Non esporre mai la chiave nel codice lato client (JavaScript del browser, applicazione pubblica) dove sarebbe visibile.

•     Implementare il protocollo HTTPS per crittografare la trasmissione della chiave e dei dati.

•     Sostituisci periodicamente le chiavi per limitare i rischi in caso di perdite.

Passaggio 3: Scopri l'API Explorer

Dolibarr include un fantastico strumento per esplorare e testare le API senza scrivere una sola riga di codice: l'API Explorer , basato sull'interfaccia Swagger. È possibile accedervi all'indirizzo /api/index.php/explorer/ nella propria installazione.

Questo strumento di esplorazione elenca tutti gli endpoint disponibili nella tua installazione, insieme alla relativa documentazione generata automaticamente dal codice. Ancora meglio, offre moduli interattivi "Prova" che ti consentono di eseguire una richiesta reale direttamente dal tuo browser e visualizzare la risposta. È il luogo ideale per comprendere la struttura dei dati e testare le tue chiamate prima di implementarle nel codice.

Comprendere gli endpoint e la loro struttura

Un endpoint (o punto di accesso) è un URL che corrisponde a un tipo di dati. In Dolibarr, seguono una struttura coerente, organizzata per modulo. L'URL di base è sempre /api/index.php/ , seguito dal nome della risorsa. Ecco i più comuni:

Ciascun endpoint accetta diversi metodi HTTP a seconda dell'azione desiderata. Per indirizzare un elemento specifico, il suo identificatore viene aggiunto all'URL: una richiesta per la fattura numero 42 indirizzerà quindi il percorso alla risorsa della fattura seguito da questo identificatore.

Fase 4: Le tue prime richieste in pratica

Passiamo ora all'applicazione pratica con lo strumento più universale: cURL, disponibile tramite riga di comando sulla maggior parte dei sistemi. Gli esempi seguenti possono essere adattati a qualsiasi linguaggio di programmazione.

Lettura dei dati (GET)

Per recuperare l'elenco dei tuoi partner, è sufficiente una semplice richiesta GET con la tua chiave:

Dolibarr restituisce quindi un array JSON contenente le terze parti, con tutti i relativi campi. È possibile affinare la query con parametri di ordinamento, limitazione o filtro per recuperare solo ciò che interessa.

Crea un dato (POST)

Per creare un nuovo prodotto, viene inviata una richiesta POST insieme a un corpo JSON che descrive l'oggetto:

Aggiorna (PUT) ed elimina (DELETE)

Il processo di aggiornamento segue la stessa logica utilizzando il metodo PUT, puntando all'ID dell'elemento e inviando solo i campi da modificare. La cancellazione, invece, utilizza il metodo DELETE sull'URL dell'elemento in questione. In tutti i casi, la richiesta deve essere accompagnata dalla chiave API e il successo dell'operazione è determinato dai permessi dell'utente.

Scenari concreti di automazione

Ora che abbiamo trattato le nozioni di base, vediamo come tutto ciò si traduce in vantaggi concreti. Ecco alcune delle automazioni più utili.

Sincronizza il tuo negozio online

Per ogni ordine effettuato sul tuo sito di e-commerce, uno script richiama l'API per creare automaticamente un cliente, se non esiste già, e salva l'ordine in Dolibarr. Il tuo sistema ERP visualizza le vendite in tempo reale, senza bisogno di inserimento manuale dei dati. Viceversa, puoi importare il catalogo prodotti da Dolibarr al tuo negozio online per mantenere informazioni di prodotto coerenti.

Genera e invia fatture automaticamente

Per gli abbonamenti o i servizi ricorrenti, uno script programmato può creare le relative fatture ogni mese tramite l'API e poi attivarne la convalida. Il tempo dedicato alla fatturazione ricorrente si riduce letteralmente a zero.

Popolamento di una dashboard esterna

Desideri monitorare i tuoi indicatori chiave di prestazione (KPI) tramite uno strumento di visualizzazione o un foglio di calcolo condiviso? Uno script interroga regolarmente l'API per estrarre ricavi, fatture non pagate o nuovi ordini e popola la tua dashboard. I tuoi dati sulle prestazioni saranno sempre aggiornati.

Collegamento di Dolibarr alle piattaforme di automazione

Le piattaforme di automazione no-code ti permettono di connettere Dolibarr a centinaia di altri servizi tramite la sua API. Questo ti consente di attivare una notifica quando una fattura viene pagata, creare un'attività nel tuo strumento di gestione progetti per ogni nuovo ordine o avvisare il tuo team via e-mail. Le possibilità sono praticamente illimitate.

Gestione multi-azienda, risposte ed errori

Se utilizzi Dolibarr in modalità multi-azienda, l'API gestisce questo scenario tramite un'intestazione dedicata, DOLAPIENTITY , che ti consente di specificare l'entità pertinente alla richiesta. Questo ti permette di gestire più aziende da un unico framework di automazione.

Lato risposta, l'API restituisce sempre JSON, accompagnato da un codice di stato HTTP che indica il risultato: un codice di successo per un'operazione riuscita o un codice di errore in caso di problemi (chiave non valida, autorizzazioni insufficienti, dati non trovati, richiesta non corretta). Il codice deve sempre verificare questo stato prima di utilizzare la risposta.

Una gestione efficace degli errori è essenziale per un'automazione affidabile. Pianifica sempre come affrontare i guasti: registra l'errore, riprova se necessario e invia un avviso se il problema persiste. Un'automazione che fallisce silenziosamente è più pericolosa dell'assenza totale di automazione.

Le migliori pratiche per un'automazione sostenibile

Per garantire che le vostre automazioni rimangano affidabili e gestibili nel tempo, tenete a mente questi principi:

1.    testa sempre tutto in Explorer. Convalida ogni richiesta nell'API di Explorer.

2.    Lavora in un ambiente di test. Non sviluppare mai i tuoi script direttamente sul tuo ambiente di produzione Dolibarr.

3.    Limitare i diritti dell'utente dell'API. Il principio del minimo privilegio riduce l'impatto di una potenziale violazione.

4.    Registra le tue chiamate. Tenere traccia delle richieste facilita notevolmente la risoluzione dei problemi.

5.    Gestisci i volumi in modo responsabile. Per le attività di elaborazione di grandi dimensioni, suddividi le query in pagine ed evita di sovraccaricare il server.

6.    Documenta le tue integrazioni. Annota cosa fa ogni script e quale chiave utilizza: te stesso in futuro ti ringrazierà.

Domande frequenti

È necessario saper programmare per utilizzare l'API di Dolibarr?

Per esplorazione e test, no: l'API Explorer consente di effettuare richieste dal browser senza codice. Per una vera automazione, sono necessarie conoscenze di programmazione o l'utilizzo di una piattaforma di automazione no-code. Le nozioni di base sono sufficienti per iniziare: l'API REST è uno standard semplice e ben documentato.

L'API è disponibile in tutte le versioni di Dolibarr?

L'API REST è integrata nel core di Dolibarr da diverse versioni ed è ora un modulo standard. È sufficiente attivarla nella configurazione. Assicurati di mantenere aggiornata l'installazione per beneficiare delle ultime correzioni e del supporto per tutti gli endpoint.

Cosa devo fare se una richiesta restituisce un errore di autorizzazione?

Un errore di autorizzazione significa che l'utente associato alla chiave API non ha il diritto di eseguire l'azione richiesta. Verifica le autorizzazioni di questo utente in Dolibarr e concedigli i diritti necessari, ma non concedergli più di quanto strettamente richiesto.

Posso collegare Dolibarr al mio sito web senza doverlo sviluppare io stesso?

Sì. Esistono connettori per molte piattaforme di e-commerce e gli strumenti di automazione senza codice consentono di connettere Dolibarr ad altri servizi tramite la sua API, senza scrivere una sola riga di codice. Tuttavia, per esigenze molto specifiche, lo sviluppo personalizzato rimane l'approccio più flessibile.

In conclusione: lascia che Dolibarr lavori per te

L'API REST di Dolibarr è una vera risorsa per chiunque desideri automatizzare i propri processi e risparmiare tempo. In pochi semplici passaggi – attivare il modulo, generare una chiave, esplorare gli endpoint e scrivere le prime query – è possibile gettare le basi per automazioni che eliminano l'inserimento manuale dei dati, garantiscono l'affidabilità dei dati e integrano il sistema ERP con il resto dell'ecosistema.

Il punto di forza di questo approccio risiede nella sua gradualità. Non è necessario rivoluzionare tutto in una volta: inizia con una singola automazione, convalidala nell'API Explorer e poi implementala con sicurezza. Ogni attività automatizzata ti permette di recuperare tempo prezioso da dedicare a ciò che conta davvero per la tua azienda.

Il consiglio migliore? Apri oggi stesso l'API Explorer di Dolibarr, invia la tua prima richiesta GET ai tuoi fornitori terzi e osserva la risposta. Questo piccolo passo ti darà un'idea del potenziale a tua disposizione e ti spingerà ad andare oltre. Il tuo ERP è pronto a lavorare per te, a patto che tu gli fornisca le istruzioni necessarie.