API de comunicación bidireccional

La API de comunicación bidireccional de DoliPlus

La API de comunicación bidireccional de DoliPlus establece un diálogo máquina a máquina. En concreto, conecta su ERP con sus otros sistemas de información.

Para ello, se basa en dos componentes. Primero, una API REST. Segundo, un Webhook.

Esta funcionalidad está en desarrollo. Su uso requiere competencias avanzadas y un buen conocimiento de DoliPlus.

Utilizar la API REST

En primer lugar, una interfaz tipo Swagger enumera la mayoría de las comunicaciones posibles mediante la API (Interfaz de Programación de Aplicaciones).

Además, esta funcionalidad se abre bajo petición especial. Así, puede ser objeto de verificaciones y mejoras antes de su puesta en producción, según sus necesidades y previo presupuesto.

En la práctica, una vez activado el módulo, DoliPlus se convierte también en un servidor de webservices REST.

Por lo tanto, puede enviar su propia solicitud REST. Para ello, diríjase a la URL relativa /api/index.php/xxx, donde xxx designa el nombre de la API a llamar.

Además, la lista de API de su instalación sigue disponible mediante el explorador de API.

De este modo, puede ver la lista completa de servicios web proporcionados por DoliPlus. Para empezar, llame al explorador en la siguiente dirección:

http://yourdolibarrurl/api/index.php/explorer

Por ejemplo, también puede probar el explorador en la instancia de demostración:

https://demo.dolibarr.org/api/index.php/explorer

A continuación, en la esquina superior derecha, pegue el <token> (clave API) del usuario deseado. Luego haga clic en el botón «Explorar».

Nota: el token de cada usuario se define en la página de registro del usuario.

Tras hacer clic en «Explorar», debería ver todas las acciones disponibles con ese token. Si ve pocas, probablemente sea porque los módulos correspondientes siguen desactivados.

Por ejemplo, para ver las facturas, active primero el módulo de facturación en la configuración de DoliPlus. Lo mismo para los productos, los clientes/proveedores, etc.

En esta página de exploración, puede realizar bastantes pruebas. De hecho, lee los datos de DoliPlus, pero también los escribe, modifica y elimina.

No obstante, tenga cuidado: los datos se modifican realmente en su base.

A continuación, puede probar directamente cualquier API desde el explorador. Es, de hecho, la solución recomendada, ya que todas las API y parámetros están documentados allí.

Por consiguiente, tras cada prueba, obtendrá la respuesta. Además, recuperará un ejemplo sobre cómo llamar a la API.

Para utilizar la API REST, finalmente debe llamar a una URL como esta:

https://<mi_servidor>/api/index.php/<acción>

Utilice uno de los 4 métodos siguientes: GET, POST, PUT, DELETE. Luego sustituya <acción> por la acción deseada. Ej:

https://<mi_servidor>/api/index.php/invoices

Ejemplo de códigos

Existen diferentes formas de proceder. A continuación, le mostramos un fragmento de código. No obstante, también puede utilizar otras bibliotecas.

función 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 )); 
    }

    // Autenticación opcional: 
    // 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 ; 
}

Este es solo un ejemplo de trabajo. En efecto, no hay control de errores y no se ha tenido en cuenta la seguridad. Sin embargo, puede utilizar este código y modificarlo según sus necesidades.

Además, la función toma 4 parámetros:

$method: cadena, “GET”, “POST”, “PUT”, “DELETE”
$apikey: string, “su <token> generado anteriormente”
$url: cadena, URL a llamar. Ej: “http://<mi_servidor>/api/index.php/invoices”
$data: string, datos en formato json. Además, este parámetro no es obligatorio.

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 ( "Éxito en la llamada API" ); 
    console . log ( rep ); 
  }, 
  error :  function ( rep )  { 
    console . log ( "Error en la llamada API" ); 
    console . log ( rep ); 
  } 
}); 
< /script>

Obtener los campos de la tabla

Tomemos como ejemplo la tabla de productos.

Primero, para obtener sus campos, lo más sencillo es listar uno o varios productos mediante una consulta GET.

Posteriormente, también puede acceder a la consola de configuración. De hecho, un enlace permite explorar las tablas, siempre que tenga permisos de administrador.

Sin embargo, algunos campos se renombran durante las transacciones. Así, rowid puede convertirse en id, o socid para un tercero. Por lo tanto, este método no es fiable para realizar inyecciones.

Extracto de la tabla de productos

Ejemplo – Listar un/os contacto(s)

Ejemplo – Crear un contacto

Antes de crear un contacto, puede ser útil verificar si ya existe. Además, esto permite obtener la estructura de los campos.

Concretamente, la tabla correspondiente es llx_socpeople para los campos. Tenga en cuenta: se utiliza socid en lugar de fk_soc para el ID del tercero.

Aquí tiene la consulta 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": "Director" ,
"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'

Estos son los campos útiles para inyectar en la interfaz y probar. Luego, adapte según sus datos.

En este ejemplo, el ID creado es el 12084.

Nota:

Tipo de contactos: type

Ejemplo – Crear/modificar los campos personalizados de un contacto

Para terminar, los campos utilizan la sintaxis empleada durante la extracción. Así, llevan el prefijo options_: “options_xxxxxx”

{
"options_client": "1",
"options_asso": "aaa,zzz",
"options_compl": "",
"options_test": ""
}

Solo queda insertar los valores.

Ejemplo – Modificar un contacto

Retomemos el ejemplo anterior con el ID 20084. Esta vez, utilice la consulta PUT en la URL: https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084

Ejemplo – Eliminar un contacto

Retomemos nuevamente el ejemplo anterior con el ID 20084. Esta vez, utilice la consulta DELETE.

curl -X DELETE --header 'Accept: application/json' --header 'DOLAPIKEY: xxxxx0571e9accee5df' 'https://xxxx.doliplus.com/dev/htdocs/api/index.php/contacts/12084'

Ejemplo – Modificar el estado de una propuesta

Aquí tiene, por ejemplo, los parámetros a transmitir:

{
“status” : 2 (aceptada) o 3 (rechazada) ,
“notrigger”: 1 – no activar otros eventos ,
“note_private” : “modificado por API”
}

Ejemplo – Llamar a una lista de productos

Primero, los parámetros aceptados están en parte documentados en el explorador REST.

A continuación, dispone de filtros SQL. Estos se transmiten a la base de datos después de su verificación. Por ejemplo, funcionan en el punto de conexión del producto:

(t.fk_product_type: = :’0′) y (t.tosell: = :’1′) y (t.label: ilike :’%string’)

Finalmente, en cuanto a las fechas, se acepta el formato ISO: %Y-%m-%d, por ejemplo 2020-07-14. En cambio, el formato aammjj no se acepta.

Ejemplo – Llamar a un diccionario de funciones de contactos de clientes o proveedores

Primero, los diccionarios disponibles están clasificados en la sección SETUP. Aquí, se utiliza GET /setup/dictionary/jobs.

Aquí tiene, por ejemplo, una salida ordenada por código y trabajo:

[ { “code”: “BE”, “job”: “Diseñador / Medidor / Técnico de oficina de estudios” }, { “code”: “COMPTA”, “job”: “Contabilidad / Pago de facturas” }, { “code”: “CONCPT”, “job”: “Diseñador / Vendedor / Responsable de negocio” }, { “code”: “CRAYON”, “job”: “Jefe de sección Cocina” },……..]

Ejemplo – Llamar a una lista de precios de clientes

Esta llamada corresponde a la consulta estadística 507.

Ejemplo – Llamar a clientes o proveedores que pertenecen a una categoría

Ejemplo – Enviar un documento

Por ejemplo, en la biblioteca de documentos de un pedido con referencia PRO-CO2007-0254.

Ejemplo – Descargar un documento

Por ejemplo, para un pedido de cliente con la referencia PRO-CO2007-0254.pdf.

Ejemplo – Listar los documentos

Por ejemplo, para un pedido de cliente dado con el ID 456.

Ejemplo – Listar las imágenes de productos

Además, un enlace público « link » figura en la respuesta. Gracias a él, puede acceder a las fotos de los productos.

Ejemplo – Listar los gestores de clientes por rango

Además, también puede añadir un filtro sobre un ID de cliente.

Configuración de datos enviados a través de eventos Webhook

Para simplificar, los webhooks activan una acción después de un evento. Así, generalmente se utilizan para hacer comunicar sistemas.

Concretamente, es la forma más sencilla de recibir una alerta. De hecho, se activa tan pronto como ocurre algo en otro sistema.

En otras palabras, un webhook es una llamada HTTPS a la URL específica de un usuario. Además, sirve para notificaciones en tiempo real. Así, su sistema se actualiza tan pronto como ocurre el evento.

En cambio, una API clásica requiere una consulta continua. El webhook, en cambio, le avisa cuando llega la información. Por lo tanto, es un medio muy eficaz para recibir notificaciones sin verificación permanente.

Para ilustrar la funcionalidad, por ejemplo, hemos implementado estos eventos durante un desarrollo.

event – send_documents

Primero, al depositar o eliminar un documento en la biblioteca de documentos DoliPlus adjunta al job, se envía una notificación a la URL específica.

Contiene entonces la siguiente información:

[
“id” => Id del job,
“element” => ‘job’,
“state” => ‘ADD_FILE’ / ‘DELETE_FILE’,
“file” => la ruta del archivo
]

A continuación, al recibir este evento, el sistema del cliente utiliza la API. Así, busca los documentos depositados en el job para actualizar su sistema de información.

events – send_order

Según los eventos ‘ORDER_VALIDATE’, ‘ORDER_MODIFY’, ‘ORDER_DELETE’, se envía una notificación a la URL específica. Contiene entonces la siguiente información:

[

“id” => Id del job,

“state” => create/update/delete

]

A continuación, al recibir este evento, el sistema del cliente utiliza la API. Así, busca la información del job para actualizar su sistema de información.

Para profundizar

Conectar sus software entre sí: sin doble entrada ni código — conectar sus software entre sí, sin doble entrada ni desarrollo.

Dolibarr DoliPlus

API de comunicación bidireccional de DoliPlus