on 5 September 2026 L’API di comunicazione bidirezionale di DoliPlus
L’API di comunicazione bidirezionale di DoliPlus stabilisce un dialogo macchina-macchina. In pratica, collega il Suo ERP agli altri sistemi informativi.
Per farlo, si basa su due componenti. Prima un’API REST. Poi un Webhook.
Questa funzionalità è in fase di sviluppo. Il suo utilizzo richiede competenze avanzate e una buona conoscenza di DoliPlus.
Utilizzare l’API REST
Innanzitutto, un’interfaccia di tipo Swagger elenca la maggior parte delle comunicazioni possibili tramite l’API (Application Program Interface).
Inoltre, questa funzionalità viene attivata su richiesta speciale. Pertanto, può essere verificata e migliorata prima del rilascio, in base alle Sue esigenze e previo preventivo.
Nella pratica, una volta attivato il modulo, DoliPlus diventa anche un server di webservices REST.
Può quindi inviare la Sua richiesta REST. Per farlo, indirizzi l’URL relativa /api/index.php/xxx, dove xxx indica il nome dell’API da chiamare.
Inoltre, l’elenco delle API della Sua installazione rimane disponibile tramite l’esploratore di API.
Così, può visualizzare l’elenco completo dei servizi Web forniti da DoliPlus. Per iniziare, chiami l’esploratore al seguente indirizzo:
http://yourdolibarrurl/api/index.php/explorer
Ad esempio, può anche provare l’esploratore sull’istanza dimostrativa:
https://demo.dolibarr.org/api/index.php/explorer
Poi, nell’angolo superiore destro, incolli il <token> (token API) dell’utente desiderato. Quindi clicchi sul pulsante « Esplora ».
Nota: il token di ogni utente viene definito nella pagina di registrazione dell’utente.
Dopo aver cliccato su « Esplora », dovrebbe vedere tutte le azioni disponibili con questo token. Se ne vede poche, probabilmente i moduli corrispondenti sono ancora disattivati.
Ad esempio, per vedere le invoice, attivi prima il modulo di fatturazione nella configurazione di DoliPlus. Lo stesso vale per i prodotti, i customer or supplier, e così via.
Su questa pagina di esplorazione, può quindi effettuare diversi test. Infatti, legge i dati di DoliPlus, ma li scrive, modifica e cancella anche.
Attenzione però: i dati vengono effettivamente modificati nel Suo database.
Successivamente, può testare direttamente qualsiasi API dall’esploratore. È anzi la soluzione consigliata, poiché tutte le API e i parametri sono documentati.
Di conseguenza, dopo ogni test, ottiene la risposta. Inoltre, recupera un esempio su come chiamare l’API.
Per utilizzare l’API REST, deve infine chiamare un URL come il seguente:
https://<mon_serveur>/api/index.php/<action>
Utilizzi uno dei 4 metodi seguenti: GET, POST, PUT, DELETE. Sostituisca poi <action> con l’azione desiderata. Es:
https://<mon_serveur>/api/index.php/invoices
Esempi di codici
Esistono diversi modi per procedere. Ecco ad esempio un frammento di codice. Tuttavia, è possibile utilizzare anche altre librerie.
funzione API REST callAPI ( $method , $apikey , $url , $data = false ) { $curl = curl_init (); $httpheader = [ 'DOLAPIKEY : ' . $apikey ] ; switch ( $method ) { case "POST" : curl_setopt ( $curl , CURLOPT_POST , 1 ); $httpheader [] = "Content-Type:application/json" ; if ( $data ) curl_setopt ( $curl , CURLOPT_POSTFIELDS , $data ); break ; case "PUT" : curl_setopt ( $curl , CURLOPT_CUSTOMREQUEST , 'PUT' ); $httpheader [] = "Content-Type:application/json" ; if ( $data ) curl_setopt ( $curl , CURLOPT_POSTFIELDS , $data ); break ; default : if ( $data ) $url = sprintf ( "%s?%s" , $url , http_build_query ( $data )); } // Autenticazione opzionale: // curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); // curl_setopt($curl, CURLOPT_USERPWD, "username:password"); curl_setopt ( $curl , CURLOPT_URL , $url ); curl_setopt ( $curl , CURLOPT_RETURNTRANSFER , 1 ); curl_setopt ( $curl , CURLOPT_HTTPHEADER , $httpheader ); $result = curl_exec ( $curl ); curl_close ( $curl ); return $result ; }
Questo è solo un esempio di lavoro. Infatti, non c’è alcun controllo degli errori e la sicurezza non è stata presa in considerazione. Tuttavia, è possibile utilizzare questo codice e modificarlo in base alle proprie esigenze.
Inoltre, la funzione accetta 4 parametri:
- $method: stringa, “GET”, “POST”, “PUT”, “DELETE”
- $apikey: stringa, “il vostro <token> generato in precedenza”
- $url: stringa, URL da chiamare. Es: “http://<mio_server>/api/index.php/invoices”
- $data: stringa, dati in formato json. Inoltre, questo parametro non è obbligatorio.
Javascript Ajax
< script >
$ . ajax ({
type : 'GET' ,
async : true ,
contentType : "application/json; charset=utf-8" ,
data : { 'lang' : 'en_US' },
dataType : "json" ,
cache : false ,
jsonp : false ,
headers : {
'DOLAPIKEY' : 'abcdef123456'
},
url : 'https://myserver/api/index.,
success : function ( rep ) {
console . log ( "Chiamata API riuscita" );
console . log ( rep );
},
error : function ( rep ) {
console . log ( "Errore nella chiamata API" );
console . log ( rep );
}
});
< /script>
Ottenere i campi della tabella
Prendiamo ad esempio la tabella prodotti.
Innanzitutto, per ottenere i suoi campi, il modo più semplice è elencare uno o più prodotti tramite una richiesta GET.
In seguito, potete anche accedere alla console di configurazione. Infatti, un link permette di esplorare le tabelle, a condizione di avere i diritti di amministratore.
Tuttavia, alcuni campi vengono rinominati durante le transazioni. Ad esempio, rowid può diventare id, o socid per un customer or supplier. Di conseguenza, questo metodo non è affidabile per eseguire iniezioni.
Estrazione dalla tabella prodotto
Esempio – Elencare un/i contatto/i
Esempio – Creare un contatto
Prima di creare un contatto, può essere utile verificare se esiste già. Inoltre, ciò permette di ottenere la struttura dei campi.
Concretamente, la tabella interessata è llx_socpeople per i campi. Da notare: si utilizza socid al posto di fk_soc per l’ID del customer or supplier.
Ecco quindi la richiesta POST:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'DOLAPIKEY: XXXXX571e9accee5df' -d '
{
"socid": 1 ,
"entity": "1" ,
"civilite": "MR" ,
"name": "TEST" ,
"firstname": "TEST2" ,
"address": "12 rue de fleurs" ,
"cp": "75010" ,
"ville": "PARIS" ,
"poste": "Directeur" ,
"phone_pro": "0413054367" ,
"phone_perso": "0425363212" ,
"phone_mobile": "0606060504" ,
"email": "test@gmail.com" ,
"fk_user_creat": "1" ,
"note": "EE" ,
"note_public": "ZZ" ,
"import_key": "API" ,
"statut": "1"
}
' 'https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts'
Questi sono i campi utili da inserire nell’interfaccia per testare. Successivamente, adattateli in base ai vostri dati.
In questo esempio, l’ID creato è il 12084.
Nota:
Tipo di contatti: type
Esempio – Creare/modificare i campi personalizzati di un contatto
Per concludere, i campi riprendono la sintassi utilizzata durante l’estrazione. Pertanto, portano il prefisso options_: “options_xxxxxx”
{
"options_client": "1",
"options_asso": "aaa,zzz",
"options_compl": "",
"options_test": ""
}
Non resta che inserire i valori.
Esempio – Modificare un contatto
Riprendiamo l’esempio sopra con l’ID 20084. Questa volta, utilizzate la richiesta PUT sull’URL: https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084
Esempio – Eliminare un contatto
Riprendiamo nuovamente l’esempio sopra con l’ID 20084. Questa volta, utilizzate la richiesta DELETE.
curl -X DELETE --header 'Accept: application/json' --header 'DOLAPIKEY: xxxxx0571e9accee5df' 'https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084'
Esempio – Modificare lo stato di una proposta
Ecco ad esempio i parametri da trasmettere:
“status” : 2 (accettata) o 3 (rifiutata) ,
“notrigger”: 1 – non attivare altri eventi ,
“note_private” : “modificato tramite API”
}
Esempio – Richiamare un elenco di prodotti
Innanzitutto, i parametri accettati sono parzialmente documentati nell’esploratore REST.
Successivamente, sono disponibili filtri SQL. Questi vengono trasmessi al database dopo la verifica. Ad esempio, funzionano sull’endpoint del prodotto:
(t.fk_product_type: = :’0′) e (t.tosell: = :’1′) e (t.label: ilike :’%string’)
Infine, per le date, è accettato il formato ISO: %Y-%m-%d, ad esempio 2020-07-14. Al contrario, il formato aammjj non è accettato.
Esempio – Richiamare un dizionario di funzioni dei contatti dei clienti/fornitori
Innanzitutto, i dizionari disponibili sono classificati nella sezione SETUP. Qui, quindi, si utilizza GET /setup/dictionary/jobs.
Ecco un esempio di output ordinato per codice e job:
[ { “code”: “BE”, “job”: “Disegnatore / Misuratore / Tecnico ufficio studi” }, { “code”: “COMPTA”, “job”: “Contabilità / Pagamento fatture” }, { “code”: “CONCPT”, “job”: “Progettista / Venditore / Responsabile affari” }, { “code”: “CRAYON”, “job”: “Caporeparto Cucina” },……..]
Esempio – Richiamare un listino prezzi cliente
Questa chiamata corrisponde alla richiesta di statistica 507.
Esempio – Richiamare clienti/fornitori appartenenti a una categoria
Esempio – Inviare un documento
Ad esempio, nella document library di un ordine con rif. PRO-CO2007-0254.
Esempio – Scaricare un documento
Ad esempio, per un ordine cliente con il rif. PRO-CO2007-0254.pdf.
Esempio – Elencare i documenti
Ad esempio, per un determinato ordine cliente con ID 456.
Esempio – Elencare le immagini dei prodotti
Inoltre, nella risposta è presente un link pubblico “link”. Grazie a esso, è possibile accedere alle foto dei prodotti.
Esempio – Elencare i responsabili cliente per livello
Successivamente, è possibile aggiungere anche un filtro su un ID cliente.
Configurazione di dati avanzati tramite eventi Webhook
Per semplificare, i webhook attivano un’azione dopo un evento. In questo modo, vengono generalmente utilizzati per far comunicare i sistemi.
Concretamente, è il modo più semplice per ricevere un’avviso. Infatti, viene attivato non appena accade qualcosa in un altro sistema.
In altre parole, un webhook è un richiamo HTTPS all’URL specifico di un utente. Inoltre, serve per le notifiche in tempo reale. Così, il vostro sistema si aggiorna non appena si verifica l’evento.
Al contrario, un’API classica richiede un’interrogazione continua. Il webhook, invece, vi avvisa quando le informazioni arrivano. Pertanto, è un metodo molto efficace per ricevere notifiche senza verifica permanente.
Per illustrare la funzionalità, abbiamo ad esempio implementato questi eventi durante uno sviluppo.
event – send_documents
Innanzitutto, al deposito o alla cancellazione di un documento nella document library DoliPlus associata all’ordine, viene inviata una notifica all’URL specifica.
Contiene quindi le seguenti informazioni:
[“id” =>Id dell’ordine,
“element” => ‘ordine,
“state” => ‘ADD_FILE’ / ‘DELETE_FILE’ ,
“file” => il percorso del file
]
Successivamente, alla ricezione di questo evento, il sistema del cliente utilizza l’API. In questo modo, recupera i documenti depositati nell’ordine per aggiornare il proprio sistema informativo.
events – send_order
Per approfondire
- Collegare i propri software tra loro: senza doppia immissione né codice — collegare i vostri software tra loro, senza doppia immissione né sviluppo.
