Troubleshooting de APIs y Datos
Protocolos de respuesta frente a fallos de extracción masiva, latencia de red OData y restricciones arquitectónicas en Business Central.
En nuestra labor DevSecOps asegurando la integridad de las canalizaciones de datos (Data Pipelines), la integración entre Business Central y plataformas de Business Intelligence puede presentar cuellos de botella e impedimentos de red.
Este documento detalla las causas raíz de los fallos más graves encontrados y sus soluciones definitivas basadas en la arquitectura implementada.
Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)
Sección titulada «Incidente 1: “Host remoto forzó la interrupción” (Timeout OData)»Síntoma
Sección titulada «Síntoma»Al intentar actualizar un conjunto de datos histórico (ej. más de 200.000 filas) desde Power Query, Power BI Desktop o mediante un script de Python, la conexión carga durante varios minutos y, repentinamente, se aborta devolviendo el error: La conexión subyacente se cerró: El host remoto forzó la interrupción de la conexión. (OData Timeout).
Diagnóstico Raíz
Sección titulada «Diagnóstico Raíz»Este es un fallo por Agotamiento de Recursos en el NST (Navision Server Tier). Ocurre cuando el endpoint objetivo no es una API optimizada (Query), sino una página estándar publicada como Web Service (ej. Página 38). Al solicitar miles de filas a una página web, el servidor de Business Central intenta renderizar componentes visuales, ejecutar triggers y calcular subconsultas complejas (FlowFields) en la memoria RAM para cada fila. Cuando el procesamiento supera los límites temporales (habitualmente 10 o 15 minutos), el balanceador de Azure corta la conexión HTTP por seguridad para evitar una caída del ERP.
Solución DevSecOps (Implementada)
Sección titulada «Solución DevSecOps (Implementada)»- Abandonar Web Services basados en Page: Eliminar de la arquitectura cualquier consumo de datos masivos a través de Web Services tipo página.
- Desarrollar APIs Nativas (Query): Migrar la petición a un objeto
queryde AL. Al hacer esto, la ejecución salta la capa de interfaz y se convierte en una sentencia SQL pura, reduciendo el tiempo de respuesta de 15 minutos a menos de 30 segundos. - Paginación (Scripts Externos): Si usamos un lenguaje como Python para el ETL, debemos asegurarnos de respetar y programar el seguimiento del token
@odata.nextLinkdevuelto por el servidor, ya que Business Central impone un límite máximo de filas por página JSON devuelta.
Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API
Sección titulada «Incidente 2: Imposibilidad de Crear Subcarpetas en Rutas API»Síntoma (Nomenclatura y Enrutamiento)
Sección titulada «Síntoma (Nomenclatura y Enrutamiento)»Durante el desarrollo de una nueva API en AL, al intentar crear una jerarquía lógica de departamentos introduciendo una barra inclinada (/) en las propiedades de la API, el compilador de Visual Studio Code arroja un error fatal y bloquea la generación del archivo .app.
Ejemplo de código defectuoso:
// ERROR FATAL DE COMPILACIÓN: Microsoft prohíbe las barras en metadatos de enrutamientoAPIGroup = 'portelcore/departamentos/finanzas';Diagnóstico Raíz
Sección titulada «Diagnóstico Raíz»El motor de generación OData V4 de Microsoft Business Central tiene rutas estructurales estrictamente codificadas de fábrica (hardcoded).
El servidor espera siempre y únicamente un modelo de 3 niveles inmutables:
{APIPublisher} / {APIGroup} / {APIVersion}
No existe capacidad técnica ni permisos a nivel de contenedor para alterar el orquestador HTTP y añadir segmentos o “subcarpetas” extra en las URLs de las Custom APIs.
Solución / Workaround Arquitectónico
Sección titulada «Solución / Workaround Arquitectónico»Adoptar convenciones de nomenclatura estrictas (Naming Conventions).
Al no poder crear rutas físicas separadas por /, simulamos la jerarquía mediante guiones bajos (Snake_case) dentro del APIGroup o del APIPublisher.
-
Implementación correcta (Grupo Lógico):
APIPublisher = 'portelcore';APIGroup = 'api_portelcore_finanzas_1';APIVersion = 'v1.0';Resultado OData:
.../api/portelcore/api_portelcore_finanzas_1/v1.0/ -
Implementación alternativa (Publisher Lógico):
APIPublisher = 'portelcore_finanzas';APIGroup = 'analitica';APIVersion = 'v1.0';Resultado OData:
.../api/portelcore_finanzas/analitica/v1.0/
3. Checklist de Diagnóstico de API y Datos
Sección titulada «3. Checklist de Diagnóstico de API y Datos»- ✓ Rendimiento: Sustitución total de servicios de tipo página por objetos
Query APIpara evitar timeouts por desbordamiento de RAM en el NST. - ✓ Formato de Enrutamiento: Cumplimiento estricto del esquema de 3 niveles exigido por el compilador AL, empleando Snake_Case para jerarquías lógicas.
- ✓ Sincronización: Limpieza previa de cachés locales del cliente para forzar el redescubrimiento de esquemas tras la reconfiguración.

