AcumatiCares
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 trabajar con todos nuestros formularios de Acumatica ERP utilizando directamente los campos y acciones disponibles en estos formularios. Por ejemplo, en el siguiente formulario, cada elemento (un cuadro de texto, un cuadro combinado o una columna de tabla) está asociado a una clase particular de API de servicios web y está disponible a través de una propiedad correspondiente de esta clase. La propiedad tiene un nombre similar al del cuadro correspondiente del formulario.
Después de haber iniciado sesión en Acumatica mediante la API, puede acceder a los datos de los formularios disponibles a través de un sencillo servicio web. Proporcionamos una clase de pantalla de los métodos de la API para trabajar con todos los formularios de Acumatica ERP disponibles a través del servicio. Puedes saber 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 se utiliza para exportar datos de los artículos de stock del formulario de inventario IN202500 es IN202500Export().
Ejemplo de Código en Pantalla: Recuperación de una lista de artículos de stock
Veamos un ejemplo de código en el que recuperamos una lista de artículos 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();
}
}
}
Note que la línea en el código anterior, IN202500Content stockItemsSchema = context.IN202500GetSchema(); hace referencia a la pantalla Inventario (IN2025000) y su contenido y por lo tanto está ligada a una pantalla específica que es la pantalla o formulario que mostramos anteriormente en la figura 2.
Las API basadas en pantallas son exclusivas de Acumatica: ofrecen un enorme valor en términos de un conjunto de ricas capacidades y gran flexibilidad. Sin embargo, están vinculadas 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 o añadir un pequeño borde puede obligarle a recompilar su código para asegurarse de 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. Esto significa que puede automatizar casi cualquier actividad o tarea. Echemos ahora un vistazo a nuestras API basadas en contratos.
API de servicios web basados 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 ha escrito 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 ID de ItemClass en su proyecto de personalización, su código seguirá siendo totalmente funcional y no requerirá recompilación ni otras modificaciones. 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 de 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 del inventario. Observe las diferencias entre el código. 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();
}
}
}
Para 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 nuevas API basadas en contratos proporciona una mayor estabilidad: no es susceptible a los problemas creados al realizar cambios en su aplicación o a lo que podamos cambiar por nuestra parte que pueda afectar a la funcionalidad de sus aplicaciones sin necesidad de recompilarlas. Por supuesto, no hace falta decirlo: es importante probar siempre sus aplicaciones cuando se publique una nueva versión del producto, no sólo durante su ciclo de desarrollo.
Resumen
Las API basadas en pantalla son exclusivas de Acumatica - piense en ellas como una especie de interfaz de secuencias de comandos para obtener datos dentro y fuera de nuestra plataforma de sistemas. Y lo que es más importante, recuerde que están vinculadas a una 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 en el código puede hacer que la aplicación no funcione como se diseñó, recompile su código para asegurarse de ello. Con estas API, se obtiene una enorme flexibilidad y una rica funcionalidad. Todo lo que se puede hacer a nivel de pantalla se puede hacer con la API, así, 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- estrictamente definidos. Se puede crear una entidad, actualizarla, leerla por criterios, por identificadores clave, etc. Hemos expuesto y definido nuestro modelo de datos, que el desarrollador puede aprovechar sin preocuparse por los cambios de pantalla que pueden 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 mes de febrero. Pronto lanzaremos nuestras API basadas en contratos con REST, que ofrecen una serie de ventajas añadidas que entusiasman a los desarrolladores. Ofreceremos más detalles en futuras entradas de este blog. En breve publicaremos un vídeo sobre nuestras API, que incluirá un primer vistazo a la compatibilidad con REST.
Reiteramos un mensaje importante a nuestros lectores: cualquier nueva integración, cualquier nuevo proyecto de desarrollo que se inicie debe construirse utilizando las API basadas en contratos. Aunque estamos invirtiendo nuestros esfuerzos en las API basadas en contratos, las API basadas en pantallas seguirán manteniéndose en un futuro previsible. Esperamos que el código de nuestros socios actuales migre con el tiempo para aprovechar las ventajas de nuestras API basadas en contratos.
Para más detalles, descargue nuestra Guía del desarrollador . Si tiene alguna pregunta, visite nuestro foro para desarrolladores en StackOverflow y publique sus preguntas.
