Bienvenido a BC Scout Path, hoy vamos a explorar las API pages📃 en Business Central.
Las APIs se convertirán en una de tus herramientas ⚒️ mas versátiles en escenarios de integración usando nuestro amigo Json🧖♂️. Te permiten no únicamente exponer datos en multiples empresas empresas de Business Central, sino también realizar operaciones CRUD, 🚦limitando lo que se puede hacer en cada endpoint que expones (el control es clave y vamos a ver algunos ejemplos prácticos).
Antes de entrar en en el código recordaremos con una comparativa cuando usaremos API Pages y cuando nos interesa mas usar API Queries.
| Característica / Aspecto | Páginas API (API Pages) | Consultas API (API Queries) |
|---|---|---|
| Propósito | Operaciones CRUD sobre entidades (Crear, Leer, Actualizar, Eliminar) | Conjuntos de datos de solo lectura, reporting y analítica |
| Objeto subyacente | Página | Consulta (Query) |
| Fuente de datos | Una tabla (puede exponer FlowFields y variables) | Múltiples tablas con joins y filtros |
| ¿Soporta operaciones de escritura? | ✅ Sí | ❌ No – solo lectura |
| Caso de uso recomendado | Exponer una tabla de Business Central como una entidad API | Exponer una vista combinada de datos |
| ¿Soporta agregaciones (Suma, Conteo, Media)? | ❌ No | ✅ Sí |
| Filtros complejos / Agrupaciones | ❌ Limitado | ✅ Totalmente soportado |
| Rendimiento | Bueno para operaciones sobre una sola entidad | Excelente para conjuntos de datos orientados a reporting |
| Uso en integraciones | Integraciones de sistemas, apps móviles, operaciones CRUD | Dashboards, conectores BI, sincronizaciones de solo lectura |
| Comportamiento OData | Semántica de conjunto de entidades (Entity-set) | Semántica de conjunto de resultados (Result-set) |
| ¿Puede representar un documento con líneas? | ⚠️ Solo usando páginas API separadas para las líneas | ❌ No es ideal para documento + líneas |
| Mejor opción para | Aplicaciones externas que crean o modifican registros en BC | Extracción de datos y APIs de analítica |
🧭 ¿Cuándo deberías usar cada uno?
✅ Usa API Pages cuando…
Necesitas manipular registros de negocio mediante API, por ejemplo:
- Crear un Cliente desde otro sistema
- Actualizar datos de Productos / Artículos
- Crear Pedidos de venta o sincronizar inventario
- Realizar operaciones CRUD en integraciones
Integraciones típicas: eCommerce, CRM, aplicaciones móviles, Power Apps y el nuevo MCP estandard de BC con capacidad de escritura.
✅ Usa API Queries cuando…
Necesitas una vista de solo lectura de datos combinados o analíticos, por ejemplo:
- Obtener el total de ventas por cliente
- Exportar un listado de envíos con datos de facturas
- Sincronizar analítica con Power BI, Azure Data Factory o Synapse
- Obtener conjuntos de datos optimizados para reporting
- Devolver datasets con joins entre múltiples tablas
Integraciones típicas: herramientas BI, plataformas de reporting, sincronizaciones de datos de solo lectura.
🧠 Resumen para recordar
- API Pages = CRUD sobre una tabla → Usadas para integraciones operativas.
- API Queries = Analítica de solo lectura → Usadas para reporting y vistas combinadas.
Como siempre, recuerda que tienes todo el código que voy mencionando en el siguiente repositorio:
1- Contexto funcional:
Seguimos extendiendo la extensión de cuentas estadísticas, esta vez los requisitos de nuestra funcionalidad son los siguientes:
- Necesitamos exponer el modulo de cuentas estadísticas para permitir crear nuevas cuentas estadísticas desde una Power App así como registrar valores de las mismas a lo largo del tiempo via API.
- Necesitaremos llevarnos la información del historico de registros de cuentas estadisticas a un Dashboard de Power BI para mostrar sus valores a lo largo del tiempo.
- Debemos de ajustar los nuevos objetos creados para poder realizar las operaciones de creación y registro usando un MCP y Copilot Studio.
2- Contexto técnico:
Estamos extendiendo la extensión de Microsoft “Statistical Accounts”, para ello hemos declarado en el archivo app.json nuestra dependencia.
Si quieres saber como puedes verlo en el articulo anterior:
3- Desarrollo:
Vamos a hacer lo siguiente:
- Crear una API Page para la creación, modificación y eliminación de cuentas estadísticas.
- Crear una API Page para la creación de registros de diario de cuentas estadísticas usando una tabla temporal para su procesado via Codeunit y posterior registro en base a una configuración muy maja.
- Crear una Codeunit para controlar la creación de registros de diario de cuentas estadisticas y definir parte de su lógica de negocio en tablas de configuración.
- Crear una API Query para mostrar los valores de cuentas estadísticas registrados en un Dashboard de Power BI.
- Actualizaremos el wizard de instalación con las nuevas configuraciones.
- Definiremos la propiedad AboutText en las API Pages para dar contexto de su uso funcional a un MCP y que pueda realizar operaciones contra nuestra API cuando se lo pidamos usando lenguaje natural.
Parecen muchas cosas 📚 pero no os preocupéis que este desarrollo es mas sencillo que preparar unos huevos fritos🍳.
Aprovecharemos a comparar la estructura de una API Page con la de un API Query así como veremos como limitar las acciones de creación y modificación de registros a través de propiedades de los objetos.
Antes de ir a tope con código quiero empezar con un briconsejo, instala la extensión "AZ AL Dev Tools/AL Code Outline" en tu Visual Studio Code si lo la tienes ya porque te permitirá acelerar mucho cosas que vamos a ver en este desarrollo y muchos mas.
Pulsando con el botón secundario del ratón puedes generar objetos de AL de una manera muy simple.
Como podeis ver hemos declarado en el AboutText un contexto funcional para que la IA pueda tener mayor contexto de para que debe ser usada esa API:
'Manages Statistical Accounts master data including names and related dimension codes.Supports full CRUD operations for retrieving, creating, updating, and deleting Statistical Account records. Ideal for integration scenarios requiring access to Statistical Account data and non financial KPIs.';
Si quereis aprender mas 🧐 acerca de como definir este contexto os dejo aquí un post de mi compañero Gerardo donde te explica en detalle el como definirlo:
Continuaremos con una API Page más compleja que nos permitirá controlar la inserción y registro de valores de cuentas estadisticas a traves de su diario de registro.
Como se puede ver claramente esta API Page usa una tabla temporal, hemos activado la propiedad Delayed Insert y hemos incluido en el trigger OnInsertRecord() la función que hará ejecutar la Codeunit que usamos para controlar la conversión de este registro temporal en uno persistido en Business Central con las modificaciones que sean necesarias para ello.
Esta codeunit permite a través del OnRun() realizar una inserción controlada de un registro en el diario de cuentas estadísticas y registrarlo para que sea incluido en su tabla de históricos apoyandose en configuraciones adicionales para definir el diario que usaremos para su carga así como numeros de series para la asignación automatica de numero de documento (estos nuevos campos los hemos creado en tabla e incluido en la página de configuración y wizard que mostramos en articulos anteriores).
Ahora vamos a abordar la exposición del histórico de cuentas estadísticas de dos maneras diferentes, usando una API Page y por otro lado usando una API Query... y ahora es cuando te haces esa razonable pregunta: "para que queremos dos objetos para lo mismo?"...y la respuesta es simple: no los necesitamos para lo mismo.
Recuerda:
- Usaremos la API Page con la propiedad AboutText para que nuestro MCP entienda para que debe usar esa API (por ahora el MCP estándar de BC no usa API Queries). Como se trata de una tabla de histórico de registro la protegeremos usando las propiedades InsertAllowed, ModifyAllowed y DeleteAllowed.
- Usaremos la API Query para exponer la información a Power BI, ya que su rendimiento para cargas de datos es superior a las API Pages, aunque sabemos que esta algo mas limitado.
Y hasta aquí nuestro desarrollo, recuerda que cuando publiques la APP en BC no es preciso exponer los API como se hacia en el pasado con los web services.
4- Funcionalidad:
Ahora una vez publiquemos la extensión en Business Central podemos extraer información de las APIs usando Power BI, Power Automate, e incluso definir nuestras APIs en la configuración de un MCP en Business Central.
En Power BI:
En Power BI seleccionamos el conector de BC.
Una vez autenticados podemos acceder al entorno y empresa y dentro de APIs Avanzadas seleccionar las que hemos creado
En Power Apps:
Partiremos creando una solución en la que incluiremos nuestra Power App
Crearemos una Canvas App
Seleccionaremos el conector de BC
Podremos seleccionar entorno y empresa de la que queremos extraer datos
Buscando por el nombre del publicador podemos filtrar todas las APIs y acceder a las que hemos personalizado.
Definiremos en BC nuestro MCP e incluiremos todas las APIs que tiene nuestro publicador, como puedes ver aquellas API en las que informamos del InsertAllowed, ModifyAllowed y DeleteAllowed a false no permite marcar los checks en el MCP de BC que estamos configurando.
Crearemos un agente en nuestra solución y pasaremos a Copilot Studio para configurarlo
Una vez definido el nombre de agente e icono seleccionaremos Tools>>MCP>>Business Central
En la configuración de la herramienta definiremos los parámetros de entorno, empresa y MCP Server Configuration (Código de nuestro MCP en BC) y guardaremos la configuración.
Nota importante: siempre que sea posible es mejor definir parámetros de entorno y empresa en las soluciones usando un objeto llamado "Variables de entorno", pero de eso hablaremos otro día 😉.
5- Conclusión:
Si te quedas con una sola idea, que sea esta: no todas las APIs sirven para lo mismo, y elegir bien entre API Page o API Query te ahorrará dolores de cabeza, problemas de rendimiento… y alguna que otra conversación incómoda con tu compa de Power BI 😅.
Hemos visto que:
Las API Pages son tus aliadas cuando quieres hacer cosas: crear, modificar, borrar y controlar exactamente qué se puede tocar y qué no.
Las API Queries son las reinas del “solo mirar, no tocar”, perfectas para reporting, analítica y cargas masivas de datos rápidas y limpias.
Además, hemos mezclado todo esto con Power Apps, Power BI, Copilot Studio y el MCP de Business Central, demostrando que, con un poco de orden y buenas prácticas, puedes montar integraciones muy guapas y potentes sin que tu solución parezca un plato de espaguetis 🍝.
¿Lo mejor?
Que todo esto no va de hacer APIs “porque sí”, sino de dar contexto, limitar bien las acciones, y pensar desde el principio en quién va a consumir esa API y para qué (humanos, Power Platform… o una IA con muy buenas intenciones pero algo torpe 🤖).
Así que ya sabes:
- Piensa antes de exponer.
- Elige bien el objeto.
- Y documenta con cariño ese AboutText, que el Copilot del futuro te lo va a agradecer.
Nos vemos en la próxima parada del BC Scout Path 🧭
Spoiler: habrá más código, más integraciones… y probablemente más huevos fritos 🍳😉
Remember: Talk is cheap, show me the code!