Cómo desarrollar un add-on para SAP Business One: UI API, DI API o Service Layer, y cómo distribuirlo

SAP Business One cubre bien los procesos estándar, pero toda empresa tiene algunos pasos que las pantallas estándar no resuelven: escanear artículos en una entrega, una aprobación especial, un cálculo de comisiones, una conexión de facturación electrónica o un registro de llamadas junto a la ficha del cliente. Un add-on es la forma de agregar esos pasos sin salir de SAP Business One.

Esta guía explica cómo se desarrollan hoy los add-ons, qué API usar para qué y cómo entregar uno en el que los usuarios confíen.

Qué es un add-on

Un add-on es un programa independiente que SAP Business One inicia cuando un usuario entra al sistema. Se conecta al cliente en ejecución y puede:

• agregar menús y pantallas nativas que se ven y se comportan como los formularios estándar de SAP,
• reaccionar a eventos en las pantallas estándar, por ejemplo cuando un usuario crea un pedido de cliente,
• leer y escribir datos de negocio a través de los propios objetos de negocio de SAP, con las mismas validaciones que el cliente.

Los usuarios no instalan nada por su cuenta. El add-on se registra una vez y SAP Business One lo distribuye a cada estación de trabajo.

Las tres API y cuándo usar cada una

Un add-on de cliente típico usa la UI API para la pantalla y la DI API para los datos, y obtiene la conexión DI desde la UI API, de modo que comparte la sesión y la licencia del usuario. La lógica que debe ejecutarse sin un usuario conectado (una sincronización nocturna, un portal, una cola de facturación electrónica) va en el servidor y se comunica con el Service Layer.

Leer datos con consultas SQL está bien y a menudo es la forma más rápida de llenar una pantalla. Escribir debe pasar por la DI API o el Service Layer para que el stock, los asientos contables, las aprobaciones y el registro de cambios se mantengan correctos.

Pantallas nativas, no ventanas aparte

Los usuarios esperan que la pantalla de un add-on se vea como SAP: los mismos campos, la misma lista de selección (Choose From List), el mismo comportamiento del teclado. La UI API construye formularios con grids, campos de edición, combos y botones que el propio cliente dibuja. Una ventana de Windows aparte abierta por el add-on se siente ajena, no respeta la configuración de SAP del usuario y muchas veces los usuarios la rechazan.

Dos detalles hacen que las pantallas nativas se sientan bien:

• Choose From List en campos como cliente, artículo o pedido, filtrada a lo que tiene sentido (solo pedidos abiertos, solo documentos de este cliente).
• Congelar el formulario mientras se construye o se actualiza, para que aparezca de una sola vez en lugar de dibujarse ítem por ítem.

Guarde sus propios datos en UDF y UDT

La mayoría de los add-ons necesitan algunos campos o tablas adicionales. SAP Business One lo permite sin modificar sus propias tablas:

• Los campos definidos por el usuario (UDF) agregan columnas a objetos existentes, por ejemplo un estado de factura electrónica en la factura de clientes o una tasa de comisión en el empleado del departamento de ventas.
• Las tablas definidas por el usuario (UDT) guardan los datos propios del add-on, como una tabla de bloqueos, un log o una tabla de configuración.

Créelos desde el add-on al iniciar (y omita los que ya existen), para que una empresa nueva los reciba automáticamente. Use nombres cortos: SAP limita las descripciones de UDT a 30 caracteres, y una más larga puede impedir que se cree la tabla.

Eventos: donde viven la mayoría de los errores de un add-on

Un add-on reacciona a eventos: un clic en un menú, un botón presionado, un cambio de valor, un documento que se crea. Tres reglas evitan la mayoría de los problemas:

1. Maneje cada evento que registra y filtre con mucho cuidado. Un filtro de eventos que deja fuera los clics de menú hace que todos los menús del add-on dejen de funcionar sin ningún aviso.
2. Cancele en el evento “before”, actúe en el evento “after”. Para bloquear o validar una acción, cancélela antes de que SAP la procese; para agregar trabajo posterior, espere a que SAP haya terminado.
3. Recuerde que los datos creados mediante la DI API no generan eventos de pantalla. Si otro add-on reacciona cuando un usuario crea una factura en pantalla, no verá las facturas que su add-on contabiliza por código.

Contabilizar documentos de forma segura

Cuando un add-on crea documentos, por ejemplo una factura a partir de una entrega escaneada, hágalo como lo haría SAP:

• Base el documento nuevo en el origen (pedido → entrega → factura) para que los precios, los impuestos y las cantidades abiertas se trasladen automáticamente.
• Use una transacción cuando una acción crea varios documentos, para que se contabilicen todos o ninguno.
• Lea todo lo que necesita antes de que empiece la transacción. Una búsqueda fallida dentro de una transacción de la DI API puede hacer que falle el commit final.
• Revise cada código de retorno y muestre al usuario el mensaje de error propio de SAP, no un genérico “algo salió mal”. Qué significan los códigos comunes (-5002, -1029, -2035, -5006) se explica en códigos de error de la DI API de SAP B1.

Empaquetado y distribución con el Extension Manager

Los add-ons se entregan como extensiones:

1. Compile el add-on con la misma arquitectura que el cliente (64 bits para los clientes actuales de SAP Business One 10.0).
2. Empaquételo con ExtensionPackage.exe del SDK. El paquete es un zip con el programa, sus archivos y un archivo de registro (.ard). El nombre del zip se convierte en el nombre de la extensión.
3. En el Extension Manager (System Landscape Directory), importe el zip, asígnelo a la empresa y elija si se inicia automáticamente para los usuarios.
4. Para una versión nueva, importe un zip con el mismo nombre y una versión mayor. El Extension Manager lo trata como una actualización y conserva la versión anterior para poder revertir.

Use un número de versión que siempre aumente, como 2026.1021.1530 (año, mes y día, hora). Nunca cambie el nombre de la extensión después de la primera importación, o los usuarios tendrán una segunda copia de cada menú.

Pruebas antes de que lo vean los usuarios

• Pruebe en una copia de la empresa, nunca solo en producción.
• Pruebe con un usuario normal, no solo con la cuenta manager; las autorizaciones cambian lo que los usuarios pueden hacer.
• Si soporta ambas bases de datos, pruebe en SQL Server y SAP HANA: HANA compara texto distinguiendo mayúsculas y minúsculas y usa otro dialecto SQL, lo que rompe consultas que funcionan en SQL Server.
• Escriba un archivo de log en cada estación de trabajo. Cuando un usuario dice “el botón no hace nada”, el log da la respuesta en minutos.
• Después de cada actualización de SAP Business One, vuelva a probar el add-on en la copia antes de actualizar producción.

Errores comunes

Cómo desarrollamos add-ons en Kodenova

Desarrollamos add-ons de SAP Business One sobre SQL Server y SAP HANA: pantallas nativas mediante la UI API, contabilización mediante la DI API, paquetes para el Extension Manager y un log en cada estación de trabajo. Algunos ejemplos son un add-on de telefonía para un fabricante alemán, un puente de facturación electrónica ZATCA y un portal de comisiones de ventas. Cada proyecto tiene precio fijo por fase y 3 meses de soporte gratis después de la salida en vivo.

Si el trabajo debe quedar fuera del cliente, por ejemplo un portal de clientes o una app móvil, vea desarrollo SAP Business One y la guía del Service Layer.

Fuentes

• SAP Help Portal: documentación de SAP Business One (SDK, DI API, UI API)
• SAP Help Portal: Working with SAP Business One Service Layer (PDF)
• SAP Learning: Leveraging the SAP Business One Service Layer

Servicios relacionados

• Desarrollo para SAP Business One