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 fatture, attivi prima il modulo di fatturazione nella configurazione di DoliPlus. Lo stesso vale per i prodotti, i soggetti terzi, 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 soggetto terzo. 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 soggetto terzo.

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:

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:

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, nell’archivio documentale 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.

Ogni notifica viene inviata all’indirizzo indicato nelle impostazioni del modulo API. Contiene l’identificativo dell’oggetto e il suo stato: create (creazione), update (modifica) o delete (eliminazione). Alla ricezione, il vostro software interroga l’API REST per leggere il dettaglio dell’oggetto.

Ecco gli eventi trasmessi oggi.

event – send_order (ordini)

Una notifica parte alla convalida di un ordine (create), a ogni modifica (update) e alla sua eliminazione (delete). Anche la modifica di un campo personalizzato dell’ordine conta come modifica.

event – send_invoice (fatture)

Una notifica parte alla convalida di una fattura (create), poi a ogni modifica, pagamento, ritorno a non pagata o abbandono (update), e alla sua eliminazione (delete). Le bozze non vengono trasmesse: il vostro software riceve solo fatture reali. Anche la modifica di un campo personalizzato della fattura conta come modifica.

event – send_products (prodotti e prezzi)

Una notifica parte alla creazione, alla modifica e all’eliminazione di un prodotto. Parte anche quando cambia il suo prezzo di vendita e quando un prezzo fornitore viene aggiunto, modificato o eliminato. In questi due casi, il campo «change» indica cosa è cambiato.

Così il vostro software aggiorna i prezzi del solo prodotto interessato, nel momento in cui cambiano. Non serve quindi rileggere tutto il catalogo ogni notte.

event – send_tiers, send_contacts, send_categories

Allo stesso modo, una notifica parte alla creazione, alla modifica e all’eliminazione di un soggetto terzo, di un contatto o di una categoria. Per soggetti terzi e contatti, la notifica contiene direttamente i loro dati.

event – send_documents

Infine, all’aggiunta o all’eliminazione di un documento nella gestione documentale di DoliPlus collegata a un ordine in corso, una notifica parte verso l’indirizzo indicato.

Alla ricezione di questo evento, il vostro software utilizza l’API per recuperare i documenti aggiunti all’ordine.

Cosa non genera una notifica

Un’importazione massiva (file CSV di prodotti o di prezzi d’acquisto) scrive direttamente nel database, senza passare da questi eventi. Dopo un’importazione, prevedete quindi una sincronizzazione puntuale da parte vostra.

Prezzi e fatture seguiti in tempo reale

Collegate DoliPlus a un software di pianificazione, di produzione o di negozio online? Da settembre 2026, quel software viene a sapere subito cosa cambia nei vostri listini e nella vostra fatturazione:

• un prezzo di vendita o un prezzo fornitore modificato parte subito, prodotto per prodotto;
• ogni fattura convalidata, pagata o modificata viene segnalata, come già avveniva per gli ordini;
• i campi personalizzati dei vostri ordini e delle vostre fatture vengono seguiti a ogni modifica.

Il vantaggio è doppio. Da un lato, l’altro software lavora sempre con prezzi aggiornati. Dall’altro, evita le riletture complete del catalogo, spesso programmate di notte, che caricano inutilmente il vostro server.

Per approfondire

• Collegare i propri software tra loro: senza doppia immissione né codice — collegare i vostri software tra loro, senza doppia immissione né sviluppo.