Sí, tenemos una API para eso

En el post de hoy, voy a presentarte las APIs de Acumatica Cloud ERP que permiten la integración con sistemas y aplicaciones externas. A través de los servicios web, las aplicaciones externas pueden obtener registros de datos de Acumatica, procesar estos registros, guardar, crear registros nuevos o actualizados. En la actualidad, ponemos a disposición del desarrollador y del integrador de sistemas el acceso tanto a las API basadas en pantalla como a las basadas en contrato, que se basan en interfaces SOAP. En un futuro próximo, desplegaremos nuestras API basadas en contratos habilitadas para REST, en las que los desarrolladores podrán utilizar interfaces REST. En una futura entrada del blog profundizaré más en nuestra implementación de REST. La figura 1 representa gráficamente estas interfaces API entre nuestra base de productos de planificación de recursos empresariales (ERP) y las aplicaciones de terceros.

API de servicios web en pantalla

Nuestras API basadas en pantalla están diseñadas para funcionar con todos nuestros formularios de Acumatica ERP utilizando directamente los campos y acciones disponibles en estos formularios. Por ejemplo, en el formulario siguiente, cada elemento – un cuadro de texto, un cuadro combinado o una columna de tabla – está asociado con una clase API de servicios web particular y está disponible a través de una propiedad correspondiente de esta clase. La propiedad tiene un nombre similar al del cuadro correspondiente en el formulario.

Después de iniciar sesión en Acumatica utilizando la API, puede acceder a los datos de los formularios disponibles a través de un servicio web simple. Proporcionamos una clase de pantalla de los métodos API para trabajar con todos los formularios de Acumatica ERP disponibles a través del servicio. Puede averiguar a qué formulario accede un método por el prefijo en el nombre del método, que es el ID del formulario. Por ejemplo, el método Export() que utiliza para exportar datos de los artículos en stock del formulario de inventario IN202500 es IN202500Export().

Ejemplo de código basado en pantalla: Recuperación de una lista de artículos en stock

Veamos un ejemplo de código donde recuperamos una lista de artículos en stock del inventario utilizando la API basada en pantalla.

//Retrieving the list of stock items from inventory 
public static void ExportStockItems() 
{ 
 using
 {
  //Connect to the web service and log in to Acumatica ERP 
  Screen context = WebServiceConnector.InitializeWebService() 
 } 
 { 
  try 
  { 
   IN202500Content stockItemsSchema = context.IN202500GetSchema(); 
   var commands = new Command[] 
   { 
    stockItemsSchema.StockItemSummary.ServiceCommands.EveryInventoryID, 
    stockItemsSchema.StockItemSummary.InventoryID, 
    stockItemsSchema.StockItemSummary.Description, 
    stockItemsSchema.GeneralSettingsItemDefaults.ItemClass, 
    stockItemsSchema.GeneralSettingsUnitOfMeasureBaseUnit.BaseUnit, 
    new Field 
    { 
     ObjectName = 
     stockItemsSchema.StockItemSummary.InventoryID.ObjectName, 
      FieldName = “LastModifiedDateTime” 
    } 
   }; 
  } 
  finally 
  { 
   context.Logout(); 
  } 
 } 
}

Tenga en cuenta que la línea en el código anterior, IN202500Content stockItemsSchema = context.IN202500GetSchema(); hace referencia a la pantalla de inventario (IN2025000) y a su contenido y, por lo tanto, está vinculada a una pantalla específica, que es la pantalla o formulario que mostramos anteriormente en la figura 2.

Las API basadas en pantalla son exclusivas de Acumatica – ofrecen un valor tremendo en términos de un conjunto de capacidades ricas y gran flexibilidad. Sin embargo, están ligadas a la pantalla y cualquier cambio en la pantalla tiende a cambiar la propia API. Por ejemplo, mover un control de un grupo a otro – añadir un pequeño borde puede obligarle a recompilar su código para asegurar que todo funciona correctamente. Todo lo que se puede hacer a nivel de pantalla en Acumatica se puede hacer con la API basada en pantalla. Lo que significa que puede automatizar casi cualquier actividad o tarea. Ahora, echemos un vistazo a nuestras API basadas en contratos.

API de servicios web basada en contratos

Estas API se introdujeron en Acumatica 5.3 en febrero de este año y son relativamente nuevas. Las API basadas en contratos operan con objetos de lógica empresarial no vinculados a la pantalla, propiamente dicha, y con sus propiedades y métodos. Las API basadas en contratos se basan en un modelo de objetos que proporciona la API de servicios web. No cambian en función de la personalización del sistema, la localización o cualquier otro cambio realizado en Acumatica Enterprise Resource Planning (ERP), como los formularios.

Por ejemplo, supongamos que escribió algún código utilizando el campo ItemClass, que accede al mismo elemento ItemClass ID que encontramos en el formulario de inventario IN2025000 en nuestro ejemplo de API basada en pantalla. Si cambia el nombre del elemento ItemClass ID en su proyecto de personalización, su código sigue siendo completamente funcional y no requiere recompilación, ni ninguna otra modificación. Puede acceder al elemento ItemClass ID en el formulario a través del mismo campo ItemClassID.

Ejemplo de código simple basado en contratos: Recuperación de una lista de artículos en stock

Al igual que en el ejemplo basado en pantalla de la sección anterior, aquí mostramos lo fácil que es recuperar artículos en stock del inventario. Observe las diferencias entre los códigos. Aquí, nuestro código no hace referencia a una pantalla para recuperar los artículos y es muy simple y directo.

//Retrieving the list of stock items from inventory 
public static void ExportStockItems() 
{ 
 using (DefaultSoapClient soapClient = new DefaultSoapClient()) 
  { 
   //Log in to Acumatica ERP 
   WebServiceConnector.InitializeWebService(soapClient); 

   try 
   { 
    //Get the list of stock items 
    Entity[] stockItems = 
    soapClient.GetList(stockItemsToBeFound, False); 
   } 
   finally 
   { 
    //Log out from Acumatica ERP 
    soapClient.Logout(); 
   } 
  } 
 }

Cualquier nuevo proyecto de desarrollo de nuestros socios actuales o su primer proyecto de desarrollo como nuevo socio, debe construirse utilizando las API basadas en contratos. Sin embargo, algunas características del sistema aún no están expuestas. Por lo tanto, en ocasiones seguirá utilizando algunas de las API basadas en pantalla. El uso de las API basadas en contratos más recientes proporciona una estabilidad adicional, no siendo susceptibles a problemas creados por cambios en su aplicación o por lo que podamos cambiar nosotros que pueda afectar la funcionalidad de sus aplicaciones sin necesidad de recompilación. Por supuesto, no hace falta decir que es importante probar siempre sus aplicaciones cuando se lanza una nueva versión del producto, no solo durante su ciclo de desarrollo.

Resumen

Las API basadas en pantalla son exclusivas de Acumatica – piense en ellas como una especie de interfaz de scripting para introducir y extraer datos de nuestra plataforma de sistema. Lo más importante, recuerde que están ligadas a la pantalla. Cada pantalla de Acumatica tiene campos, grupos y contenedores… y así sucesivamente. Cada cambio en la pantalla tiende a cambiar la API. Por ejemplo, mover un control de un grupo a otro – hacer pequeños cambios en el formulario o el código puede hacer que la aplicación no funcione según lo diseñado – recompile su código para asegurar esto. Con estas API, obtiene una flexibilidad tremenda y una rica funcionalidad. Todo lo que se puede hacer a nivel de pantalla también se puede hacer con la API, lo que le da la capacidad de automatizar casi cualquier cosa en el sistema.

Con el lanzamiento de las API basadas en contratos, exponemos nuestros modelos de datos – por ejemplo, CRUD, detalles y métodos simples – que están estrictamente definidos. Puede crear una entidad, actualizar, leer por criterios, por identificadores clave, etc. Hemos expuesto y definido nuestro modelo de datos, del que el desarrollador puede aprovecharse sin preocuparse por los cambios de pantalla que puedan entrar en conflicto y romper la aplicación. Encapsulamos los cambios y ocultamos la complejidad al desarrollador. Esencialmente, hemos proporcionado un "contrato" con los desarrolladores que promete que cualquier cambio subyacente que hagamos no romperá su código.

Escuchando los comentarios de nuestros clientes y socios, lanzamos nuestras API basadas en contratos el pasado febrero. Pronto, lanzaremos nuestras API basadas en contratos habilitadas para REST, que tienen una serie de beneficios adicionales que entusiasman a los desarrolladores. Proporcionaremos más detalles en futuras publicaciones de este blog. Muy pronto lanzaremos un video de discusión sobre nuestras API, incluyendo un adelanto del soporte REST.

Reiterando un mensaje importante a nuestros lectores: cualquier nueva integración, cualquier nuevo proyecto de desarrollo iniciado debe construirse utilizando las API basadas en contratos. Aunque estamos invirtiendo nuestros esfuerzos en las API basadas en contratos, las API basadas en pantalla seguirán manteniéndose en el futuro previsible. Esperamos que el código de nuestros socios actuales migre con el tiempo para aprovechar los beneficios de nuestras API basadas en contratos.

Para más detalles, descargue nuestra Guía del desarrollador . Si tiene preguntas, visite nuestro foro de desarrolladores en StackOverflow y publique cualquier pregunta que pueda tener.

Gestión Empresarial General

Conozca más