Qué es el bulk insert

Por defecto, el servidor de Business Central no ejecuta cada Insert() en el momento. Los guarda en un búfer y, cuando hace falta, los envía a SQL Server todos juntos.

Esto tiene dos ventajas:

• Menos llamadas al servidor de base de datos. Mil inserciones agrupadas cuestan mucho menos que mil viajes de ida y vuelta.
• Menos tiempo con las tablas bloqueadas. La inserción real se retrasa hasta el último momento posible de la transacción, así que los bloqueos duran menos. Se nota sobre todo en tablas con índices SIFT (los que alimentan los FlowField de sumas), que se actualizan con cada fila.

El bulk insert es automático: no hay que activarlo en el código. Lo que sí puede hacer el código es impedirlo sin querer.

Cuándo se envía el búfer a SQL Server

Los registros que esperan en el búfer se escriben en cuanto ocurre cualquiera de estas cosas:

1. Se hace Commit() de la transacción.
2. Se llama a Modify() o Delete() sobre la tabla.
3. Se llama a cualquier método Find o Calc sobre la tabla: Find(), FindFirst(), FindLast(), FindSet(), Get(), CalcFields(), CalcSums()...

La clave está en "sobre la tabla": leer de otra tabla no vacía el búfer. Si dentro del bucle lees la misma tabla en la que estás insertando, cada vuelta envía lo acumulado y el búfer nunca llega a llenarse. Tienes el coste de un insert por fila, como si el bulk insert no existiera.

Cuándo no se usa el búfer

Hay casos en los que Business Central ni siquiera intenta agrupar las inserciones:

El primero es el más traicionero, porque el patrón if not Rec.Insert() then Rec.Modify() es muy común para "insertar o actualizar". Es cómodo, pero en un bucle grande convierte cada fila en una llamada a SQL. Si sabes que el registro no existe, usa Rec.Insert() sin mirar el resultado; si no lo sabes, a menudo compensa comprobarlo antes en bloque.

El error típico: buscar el último número dentro del bucle

Este es el ejemplo que da Microsoft, adaptado a la sintaxis actual de AL. Se registran líneas de diario y cada movimiento necesita el siguiente "Entry No.":

// No aprovecha el bulk insert
GLEntry.LockTable();
if JnlLine.FindSet() then
    repeat
        GLEntry.FindLast();                         // Find sobre G/L Entry: vacía el búfer
        GLEntry.Init();
        GLEntry."Entry No." := GLEntry."Entry No." + 1;
        GLEntry."G/L Account No." := JnlLine."Account No.";
        GLEntry.Amount := JnlLine.Amount;
        GLEntry.Insert();
    until JnlLine.Next() = 0;
Commit();

El FindLast() está sobre G/L Entry, la misma tabla en la que se inserta. En cada vuelta obliga a escribir lo que había en el búfer, así que todas las inserciones van una a una.

La corrección es buscar el último número una sola vez, antes del bucle, y llevar la cuenta en una variable:

// Aprovecha el bulk insert
GLEntry.LockTable();
if GLEntry.FindLast() then
    NextEntryNo := GLEntry."Entry No." + 1
else
    NextEntryNo := 1;

if JnlLine.FindSet() then
    repeat
        GLEntry.Init();
        GLEntry."Entry No." := NextEntryNo;
        GLEntry."G/L Account No." := JnlLine."Account No.";
        GLEntry.Amount := JnlLine.Amount;
        GLEntry.Insert();
        NextEntryNo += 1;
    until JnlLine.Next() = 0;
Commit();                                           // aquí se hacen las inserciones

JnlLine.Next() sigue leyendo dentro del bucle, pero es otra tabla, así que no afecta al búfer de G/L Entry. Las inserciones se acumulan y se envían juntas en el Commit().

El LockTable() antes del FindLast() es importante: bloquea la tabla para que ningún otro proceso coja el mismo número entre la lectura y la inserción.

Cómo revisar tus propios bucles

Antes de dar por bueno un proceso que inserta muchas filas, repasa el cuerpo del bucle con estas preguntas:

1. ¿Hay algún Get, Find*, CalcFields o CalcSums sobre la tabla destino? Sácalo fuera del bucle o guarda el dato en una variable.
2. ¿Se hace Modify() o Delete() sobre la tabla destino entre inserciones? Si puedes, rellena el registro completo antes del Insert() en lugar de insertar y modificar después.
3. ¿Se usa el resultado de Insert()? Si no lo necesitas, quítalo.
4. ¿Hay un Commit() dentro del bucle? Además de vaciar el búfer en cada vuelta, rompe la atomicidad del proceso. Casi nunca es buena idea.
5. ¿La tabla tiene Blob o AutoIncrement? Si es una tabla tuya y vas a insertar en volumen, valora si de verdad hacen falta. Para imágenes y ficheros, los tipos Media y MediaSet guardan el contenido en otra tabla del sistema.

Ojo también con los suscriptores de eventos. Si llamas a Insert(true), se ejecutan el trigger OnInsert y los eventos asociados; si alguna extensión lee o modifica la tabla desde ahí, el búfer se vacía aunque tu bucle esté limpio.

Desactivarlo para depurar: BufferedInsertEnabled

Hay un efecto secundario del búfer que conviene conocer: como la fila no se escribe en el Insert(), un error de inserción (una clave duplicada, por ejemplo) puede aparecer más tarde, en el Commit() o en el siguiente Find, y no en la línea que lo provoca. Eso despista mucho al depurar.

Para estos casos, en instalaciones on-premise se puede desactivar el bulk insert en el fichero CustomSettings.config del servidor de Business Central:

<add key="BufferedInsertEnabled" value="false" />

Hay que reiniciar la instancia del servicio para que se aplique. Con el búfer desactivado, el error aparece en el Insert() que lo causa. Una vez localizado el problema, vuelve a dejarlo como estaba: desactivarlo de forma permanente penaliza el rendimiento de todos los procesos.

En Business Central online no tienes acceso a la configuración del servidor, así que lo único que está en tu mano es escribir bien los bucles.

Resumen

• Business Central agrupa los Insert() y los envía juntos a SQL Server: menos llamadas y bloqueos más cortos.
• El búfer se vacía con Commit(), con Modify()/Delete() y con cualquier Find/Calc sobre la misma tabla.
• No se agrupa si usas el resultado de Insert() o si la tabla tiene campos Blob o AutoIncrement.
• Calcula los números de movimiento antes del bucle y no leas la tabla destino dentro de él.
• Para depurar errores de inserción on-premise, BufferedInsertEnabled = false en CustomSettings.config, y solo mientras depuras.

Fuente: Bulk Inserts – Microsoft Learn.

La salida fácil es una rama de Git por versión. Funciona el primer mes; después, cada corrección hay que llevarla a mano a tres ramas, y alguna se olvida. La alternativa es una sola base de código que se compila distinta según la versión de destino, con las directivas de preprocesador de AL.

Qué son las directivas de preprocesador

Desde Business Central 2020 release wave 2 (v17), el compilador de AL entiende líneas que empiezan por #. No son código: se evalúan antes de compilar y deciden qué trozos llegan al compilador y cuáles se descartan.

Las condiciones admiten and, or, not y paréntesis. Se puede hacer condicional cualquier cosa: una línea dentro de un procedimiento, un procedimiento entero, un campo de una tabla o un objeto completo.

Los símbolos: interruptores encendidos o apagados

Un símbolo es un nombre que está definido (vale true) o no (vale false). No tiene valor numérico: no existe #if VERSION >= 24.

Los símbolos para toda la extensión se declaran en app.json:

{
  "preprocessorSymbols": [ "BC22PLUS", "BC24PLUS" ]
}

Y con #define se pueden añadir solo para un fichero, siempre antes del primer objeto:

#define DEBUG

codeunit 50100 "CM Diagnostics"
{
    ...
}

Un detalle importante: AL no trae símbolos de versión de serie. El compilador no sabe "para qué versión estás compilando" a efectos de #if; esos símbolos los defines tú.

Símbolos acumulativos: el truco para comparar versiones

Como no hay comparaciones, el patrón que mejor funciona es definir un símbolo por cada versión mínima que se cumple. Al compilar para la v26, se encienden también los de la v22 y la v24:

Así, #if BC24PLUS significa "de la v24 en adelante", y #if not BC24PLUS, "anterior a la v24". Es el mismo enfoque que usa Microsoft en la Base App con sus símbolos CLEAN22, CLEAN23... para el código que va a eliminar.

Un ejemplo real: las series numéricas en la v24

En la v24 (2024 release wave 1), Microsoft marcó como obsoleta la codeunit NoSeriesManagement y la sustituyó por la nueva "No. Series". Si tu extensión numera documentos propios, en la v24 te salta el aviso de obsoleto y, cuando Microsoft la elimine, dejará de compilar. Pero en la v22 la codeunit nueva todavía no existe.

Con directivas, el mismo fichero sirve para todas:

table 50100 "CM Service Order"
{
    ...
    trigger OnInsert()
    var
        ServiceSetup: Record "CM Service Setup";
#if BC24PLUS
        NoSeries: Codeunit "No. Series";
#else
        NoSeriesMgt: Codeunit NoSeriesManagement;
#endif
    begin
        if "No." <> '' then
            exit;
        ServiceSetup.Get();
#if BC24PLUS
        "No. Series" := ServiceSetup."Service Order Nos.";
        "No." := NoSeries.GetNextNo("No. Series", WorkDate());
#else
        NoSeriesMgt.InitSeries(ServiceSetup."Service Order Nos.", xRec."No. Series", WorkDate(), "No.", "No. Series");
#endif
    end;
}

Al compilar para la v22, el compilador solo ve la rama de NoSeriesManagement; para la v24 o la v26, solo la de "No. Series". Ninguna de las dos versiones del .app arrastra código que no entiende.

También se pueden condicionar campos y objetos enteros, por ejemplo una pageextension sobre una página que solo existe a partir de cierta versión:

#if BC26PLUS
pageextension 50110 "CM New Feature Page" extends "Some Page Added In 26"
{
    ...
}
#endif

Silenciar avisos en la rama antigua

Si una versión intermedia todavía tiene el objeto antiguo marcado como obsoleto, el compilador lanzará el aviso AL0432. Cuando conscientemente lo sigues usando en la rama de compatibilidad, #pragma lo silencia solo en ese trozo:

#pragma warning disable AL0432
        NoSeriesMgt.InitSeries(...);
#pragma warning restore AL0432

Cómo cambiar de versión: app.json por destino

El app.json no admite directivas, y es justo el fichero que más cambia entre versiones: application, platform, runtime, las dependencias y los símbolos.

La solución práctica es guardar los valores de cada destino y generar el app.json antes de compilar. Por ejemplo, con un pequeño script de PowerShell:

param([ValidateSet('22', '24', '26')] [string] $Version = '26')

$targets = @{
    '22' = @{ application = '22.0.0.0'; runtime = '11.0'; symbols = @('BC22PLUS') }
    '24' = @{ application = '24.0.0.0'; runtime = '13.0'; symbols = @('BC22PLUS', 'BC24PLUS') }
    '26' = @{ application = '26.0.0.0'; runtime = '15.0'; symbols = @('BC22PLUS', 'BC24PLUS', 'BC26PLUS') }
}
$t = $targets[$Version]

$app = Get-Content app.json -Raw | ConvertFrom-Json
$app.application = $t.application
$app.platform = $t.application -replace '^(\d+)\..*', '$1.0.0.0'
$app.runtime = $t.runtime
$app.preprocessorSymbols = $t.symbols
$app | ConvertTo-Json -Depth 10 | Set-Content app.json -Encoding utf8

En Visual Studio Code, usa además una carpeta de símbolos por versión (.alpackages/bc22, .alpackages/bc24...) con el ajuste al.packageCachePath, para no descargar los símbolos cada vez que cambias de destino.

Si compilas con AL-Go for GitHub, no hace falta el script: tiene el ajuste preprocessorSymbols en su settings.json, combinable con configuraciones condicionales para lanzar un build por versión.

Buenas prácticas

1. Compila todos los destinos en cada cambio. Una rama #if que nadie compila se rompe sin que te enteres. En el pipeline, un build por versión soportada.
2. Pocas ramas y pequeñas. Condiciona la línea o el procedimiento que cambia, no medio fichero. Si un bloque crece, sácalo a un procedimiento propio con dos implementaciones.
3. Nombres claros y documentados. BC24PLUS se entiende solo; NEWNOSERIES, no tanto. Apunta en el README qué símbolos existen y qué significan.
4. Limpia cuando dejes una versión. Cuando ya no des soporte a la v22, busca BC22PLUS, quita las ramas #else y el símbolo. Las directivas son deuda técnica con fecha de caducidad.
5. Las ramas de Git, para lo que no cabe. Si dos versiones divergen en casi todo (por ejemplo, NAV con C/AL frente a BC con AL), las directivas no son la herramienta: ahí sí tiene sentido separar.

Directivas o ramas de Git

Para una extensión que vive en varios clientes con versiones distintas, la base única gana casi siempre.

Resumen

• Las directivas (#if, #elif, #else, #endif) deciden qué código se compila.
• Los símbolos se definen en preprocessorSymbols de app.json o con #define; AL no trae símbolos de versión.
• Usa símbolos acumulativos (BC22PLUS, BC24PLUS...) para expresar "de esta versión en adelante".
• Genera el app.json de cada destino con un script o con AL-Go, y compila todas las versiones en cada cambio.

Fuente: AL Preprocessor Directives Overview – Microsoft Learn.

Qué ha pasado

Son dos fallos distintos, los dos con una puntuación de 9,2 sobre 10 (CVSS v4):

En la práctica, el atacante envía un formulario o una subida de archivos (multipart) preparada para provocar el fallo. No necesita cuenta, ni que tu aplicación tenga ningún error propio: en la configuración más expuesta, el ataque se produce antes de que se ejecute una sola línea de tu web.

Una filtración que adelantó el parche

La publicación estaba prevista para el jueves 22, pero el lunes 20 alguien publicó los detalles antes de tiempo. El post se borró, pero las capturas ya circulaban por redes. PHP respondió adelantando el parche al martes 21.

Al cierre de este artículo no hay exploit público ni ataques masivos confirmados, pero los investigadores coinciden en que es cuestión de días: varios equipos ya están reproduciendo el fallo y el propio aviso oficial confirma que existe un exploit funcional. El NCSC británico recomienda desconectar los sistemas que no se puedan actualizar ya.

A quién afecta

A cualquier instalación de PHP que sirva páginas web, sea cual sea la forma de ejecutarlo:

• Apache con mod_php: el caso más grave. El ataque funciona con una sola petición y sin tocar tu código.
• PHP-FPM (Nginx, la mayoría de hostings modernos): también vulnerable, con condiciones algo más difíciles de reunir.
• php-cgi, FrankenPHP y LiteSpeed: afectados.

Lo que importa es la versión de PHP, no la aplicación. Un WordPress perfectamente actualizado sobre un PHP sin parchear sigue siendo vulnerable.

Qué versiones están corregidas

Si estás en PHP 8.1 o anterior, no habrá actualización oficial. PHP ha publicado parches mínimos de código fuente para 7.4, 8.0 y 8.1, y algunas distribuciones Linux los incluirán en sus paquetes, pero lo sensato es subir a 8.3 o 8.4 cuanto antes.

Qué hacer hoy

1. Comprueba tu versión de PHP

En un hosting compartido, la verás en el panel de control (normalmente en un apartado Configuración de PHP). En WordPress: Herramientas > Salud del sitio > Información > Servidor. En un servidor propio:

php -v

Ojo: la versión de la línea de comandos puede no coincidir con la que usa la web. Si tienes dudas, crea un info.php con <?php phpinfo();, ábrelo en el navegador y bórralo en cuanto lo veas.

2. Actualiza

• Hosting compartido o gestionado: los proveedores recibieron el parche antes de hacerse público y la mayoría ya lo está aplicando. Confirma con tu proveedor que tu versión es igual o posterior a las de la tabla. Si estás en PHP 8.1 o anterior, cambia de versión desde el panel.
• Servidor propio (Debian, Ubuntu, RHEL…): actualiza los paquetes de PHP de tu distribución y reinicia PHP-FPM o Apache. Sin reinicio, los procesos siguen ejecutando el código viejo.

sudo apt update && sudo apt upgrade
sudo systemctl restart php8.3-fpm   # o apache2, según tu instalación

Si usas el repositorio de Remi (rpms.remirepo.net), no tuvo los paquetes el día 21: pasa a los paquetes de tu distribución o compila desde el código fuente.

3. Si no puedes actualizar ya: mitigaciones temporales

Reducen el riesgo, no lo eliminan. PHP lo deja claro: no hay mitigación completa, solo actualizar es seguro. Añádelas en el php.ini o en la configuración del pool de FPM (no en .user.ini ni con ini_set(), que llegan tarde) y reinicia todos los procesos:

; CVE-2026-109618
memory_limit = -1
post_max_size = 8M          ; 32M si tu web necesita subir archivos
upload_max_filesize = 8M    ; siempre por debajo de post_max_size

; CVE-2026-109619
session.upload_progress.enabled = 0
fatal_error_backtraces = 0  ; solo PHP 8.5

Además:

• Limita el tamaño de las peticiones en Nginx, Apache o tu proxy. Si tu web no tiene formularios con archivos, bloquea las peticiones multipart antes de que lleguen a PHP.
• Si usas Cloudflare, ya tiene reglas de WAF para los vectores conocidos, también en el plan gratuito.
• No uses RLIMIT_AS ni RLIMIT_DATA para limitar memoria: provocan justo el fallo que se quiere evitar.

4. Revisa que no te hayan entrado

Si tu web estuvo expuesta, vigila durante las próximas semanas: archivos .php nuevos o modificados en carpetas de subidas, usuarios administradores que no reconoces, tareas programadas extrañas o picos de tráfico saliente. Que no haya nada raro en los logs no garantiza que no te hayan atacado.

Resumen

• PHP2Shell son dos fallos críticos (CVE-2026-109618 y CVE-2026-109619) que permiten ejecutar código en tu servidor sin autenticación.
• Afecta a todo PHP que sirva webs, con o sin WordPress; el peor caso es Apache con mod_php.
• Versiones seguras: 8.5.12, 8.4.27, 8.3.36 y 8.2.35.
• PHP 8.1 o anterior: sin parche oficial; actualiza de rama.
• Las mitigaciones ayudan mientras actualizas, pero solo el parche te protege.

Si tienes una web y no sabes qué versión de PHP usa o cómo actualizarla, escríbeme y lo revisamos.

Fuentes: anuncio oficial de PHP, avisos GHSA-w8hw-w9fx-j79w y GHSA-6wmf-4rv5-p3rp, Rapid7, Huntress y Help Net Security.

Un poco de historia: el .flf

El .flf nace con Navision Financials a finales de los 90; de ahí el nombre que Microsoft sigue usando: fin.flf para las licencias de cliente y CRONUS.flf para la de demostración. Sobrevivió a Navision Attain, a todo Dynamics NAV hasta NAV 2018 y a las primeras versiones de Business Central on-premise.

Es un archivo binario firmado por Microsoft con el cliente, los módulos contratados (granules), los rangos de objetos autorizados y el número de usuarios. Hasta BC 14 (Spring 2019) se podía subir desde el entorno de desarrollo C/SIDE (Herramientas > Información de licencia > Cargar); siempre se ha podido subir también con PowerShell.

El relevo: .bclicense

Con licencias cada vez más grandes, sobre todo por los rangos de objetos de las extensiones AL, el .flf empezó a dar problemas al importar. Microsoft creó el .bclicense: los mismos permisos y condiciones, en un formato preparado para licencias grandes.

Durante la transición, Microsoft entregaba un .zip con ambos archivos (fin.flf y fin.bclicense) con permisos idénticos. Desde la v22 (2023 release wave 1) el .flf está retirado y solo vale el .bclicense.

En Business Central online (SaaS) no hay archivo de licencia: se asignan licencias por usuario desde el centro de administración de Microsoft 365.

Compatibilidad por versión

Regla rápida para saber qué archivo te toca:

• BC online: no necesitas archivo.
• NAV o BC 13–16: .flf.
• BC 17.12+, 18.7+, 19.1+, 20 o 21: cualquiera de los dos; mejor .bclicense.
• BC 22 o superior: solo .bclicense.

Cómo importarla

Desde el Business Central Administration Shell, como administrador:

Import-NAVServerLicense -ServerInstance BC -LicenseFile "C:\licencias\fin.bclicense"
Restart-NAVServerInstance -ServerInstance BC

La licencia se sube una vez por base de datos, no por cada cliente.

Si vas a migrar

1. Antes de subir a la v22 o superior, pide a tu partner el .bclicense. Con solo un .flf no podrás importar la licencia.
2. Si estás en v17 o v18, actualiza al menos a la 17.12 o la 18.7 para poder usar el .bclicense.
3. Si vienes de NAV, revisa los rangos de objetos de la nueva licencia: tus extensiones AL tienen que caber en los IDs autorizados.

Resumen

• .flf: el formato histórico, de Navision a BC 21. Retirado en la v22.
• .bclicense: admitido desde 17.12, 18.7 y 19.1; el único válido desde la v22.
• SaaS: sin archivo de licencia.

Fuente: Upload the License File – Microsoft Learn.

Este artículo es la versión práctica: arquitectura, qué sincronizar en cada sentido y el código de las partes delicadas.

Antes de programar: ¿existe ya un conector?

Para algunas plataformas no hace falta empezar de cero:

• Shopify: Business Central incluye un conector de Shopify publicado por Microsoft.
• WooCommerce, PrestaShop, Adobe Commerce (Magento) y otras: hay conectores de terceros en AppSource.

Si tu tienda es estándar y el conector cubre tu proceso, suele ser la opción más barata. Una integración a medida tiene sentido cuando la web es propia, cuando hay reglas B2B específicas (tarifas por cliente, condiciones, aprobaciones) o cuando lo que quieres es un portal de clientes y no una tienda.

La arquitectura que funciona

Navegador  →  tu backend (Node, PHP, .NET...)  →  API de Business Central
                     ↑
           webhooks de Business Central

Tres reglas que no conviene saltarse:

1. El navegador nunca habla con Business Central. El secreto de la aplicación de Entra ID y los permisos viven en tu servidor. Si llamas desde el navegador, cualquiera puede ver tus credenciales.
2. Tu backend es el que tiene el token y lo reutiliza hasta que caduca. Si no sabes cómo obtenerlo, lo explico en OData y API en Business Central.
3. Lo que se lee mucho, se cachea. El catálogo y los precios no cambian en cada visita: guárdalos en tu base de datos o en caché y actualízalos cuando Business Central avise de un cambio.

Qué sincronizar y en qué sentido

La regla general: cada dato tiene un dueño. Los precios, el stock y las condiciones mandan en Business Central; la web los muestra. Si permites editarlos en los dos sitios, tarde o temprano no sabrás cuál es el bueno.

Crear un pedido desde la web sin duplicados

Primero, un pequeño cliente HTTP con reintentos, porque Business Central limita las peticiones por usuario y antes o después recibirás un 429:

async function bc(path, init = {}, retries = 3) {
  const res = await fetch(BASE_URL + path, {
    ...init,
    headers: {
      Authorization: `Bearer ${await getToken()}`,
      'Content-Type': 'application/json',
      ...init.headers
    }
  });
  if ((res.status === 429 || res.status === 503) && retries > 0) {
    await new Promise(r => setTimeout(r, (4 - retries) * 2000)); // 2 s, 4 s, 6 s
    return bc(path, init, retries - 1);
  }
  if (!res.ok) throw new Error(`Business Central ${res.status}: ${await res.text()}`);
  return res.status === 204 ? null : res.json();
}

Ahora el pedido. La API v2.0 permite crear la cabecera y las líneas en una sola llamada:

async function createOrder(webOrder) {
  const ref = `WEB-${webOrder.id}`;

  // ¿Ya existe? Un reintento o un doble clic no debe crear otro pedido.
  const { value: existing } = await bc(
    `/companies(${COMPANY_ID})/salesOrders?$filter=externalDocumentNumber eq '${ref}'&$select=id,number`
  );
  if (existing.length) return existing[0];

  return bc(`/companies(${COMPANY_ID})/salesOrders`, {
    method: 'POST',
    body: JSON.stringify({
      customerNumber: webOrder.customerNumber,
      externalDocumentNumber: ref,
      salesOrderLines: webOrder.lines.map(l => ({
        lineType: 'Item',
        lineObjectNumber: l.sku,
        quantity: l.quantity
      }))
    })
  });
}

La clave es externalDocumentNumber: guardas ahí el número de pedido de la web y compruebas si ya existe antes de crearlo. Sin esa comprobación, un timeout seguido de un reintento te deja dos pedidos iguales en el ERP.

Fíjate también en lo que no se envía: el precio. Si la web manda el precio, Business Central lo acepta tal cual; si no lo manda, lo calcula con sus propias reglas. Decide quién manda (normalmente, el ERP) y sé coherente.

Enterarte de los cambios: webhooks

En lugar de preguntar cada cinco minutos si ha cambiado algo, puedes pedirle a Business Central que te avise. Te suscribes a una entidad:

POST https://api.businesscentral.dynamics.com/v2.0/{tenant}/{entorno}/api/v2.0/subscriptions
{
  "notificationUrl": "https://tu-backend.com/bc/webhook",
  "resource": "/api/v2.0/companies({companyId})/items",
  "clientState": "un-secreto-compartido"
}

Antes de dar de alta la suscripción, Business Central llama a tu notificationUrl con un parámetro validationToken, y tienes que devolverlo tal cual con un 200. Después, cada aviso llega a la misma URL:

app.post('/bc/webhook', express.json(), (req, res) => {
  // Alta y renovación: devolver el token tal cual.
  if (req.query.validationToken) return res.type('text/plain').send(req.query.validationToken);

  // Avisos: responder rápido y quedarse solo con los de nuestra suscripción.
  // Un error 4xx haría que Business Central borrase la suscripción, así que se ignoran sin más.
  const notifications = (req.body.value || []).filter(n => n.clientState === process.env.BC_CLIENT_STATE);
  res.sendStatus(200);
  queue.push(...notifications); // procesar después: leer cada `resource` con la API
});

Lo que conviene saber antes de fiarte de ellos:

• El aviso no trae los datos: trae qué recurso ha cambiado (created, updated o deleted). Luego tienes que leerlo.
• No son instantáneos: Business Central espera unos 30 segundos para agrupar cambios. Si en ese tiempo cambian más de 1.000 registros, recibes un único aviso de tipo collection con un filtro para leerlos todos.
• Caducan a los tres días. Hay que renovarlos con un PATCH, que vuelve a pedir el validationToken. Programa la renovación a diario.
• Responde rápido y procesa después. Si tu servidor contesta 408, 429 o un 5xx, Business Central reintenta durante 36 horas. Con cualquier otro error, borra la suscripción.
• Hay un máximo de 200 suscripciones por entorno, y no todas las entidades admiten webhooks: artículos, clientes, pedidos y facturas sí, y también tus APIs propias si cumplen ciertas condiciones (clave de un solo campo, como SystemId; tabla no temporal; página y no consulta).

Un buen esquema combina las dos cosas: webhooks para enterarte rápido y una sincronización incremental nocturna por lastModifiedDateTime para recuperar cualquier aviso que se haya perdido.

Errores típicos

• Llamar a Business Central desde el navegador. Credenciales expuestas y permisos de más.
• Leerlo todo cada pocos minutos. Con 6.000 peticiones cada 5 minutos por usuario, una sincronización completa y frecuente agota el límite y bloquea al resto de integraciones.
• Pedidos duplicados por reintentos sin comprobar externalDocumentNumber.
• Integraciones sobre páginas de Microsoft publicadas como OData, que dejarán de funcionar en la versión 30. Usa la API v2.0 o una API propia.
• No registrar los errores. Una integración que falla en silencio es peor que una que no existe: guarda cada error con el pedido o el artículo afectado y avisa a alguien.

Resumen

Una integración web con Business Central bien hecha tiene un backend en medio, sincroniza de forma incremental, se entera de los cambios con webhooks y crea pedidos que no se duplican. Si estás planteando una tienda, un portal B2B o quieres revisar una integración que da problemas, cuéntame tu caso.

Los cuatro pasos sirven igual para Business Central online (SaaS) y on-premises. Lo que cambia son las herramientas disponibles en cada caso, y te lo indico en cada paso.

1. Lee bien el error

El código HTTP te dice en qué capa está el problema:

Después, mira el cuerpo de la respuesta. Business Central devuelve un código de error cuyo prefijo, casi siempre, indica la categoría:

{
  "error": {
    "code": "Application_FieldValidationException",
    "message": "Customer Posting Group must have a value in Customer: No.=C00690. It cannot be zero or empty."
  }
}

Hay tres que conviene reconocer a la primera:

• Application_DialogException o Application_FieldValidationException: es un Error() o un TestField del código AL. Si haces lo mismo desde la pantalla, verás el mismo mensaje. El problema está en los datos, no en la integración.
• BadRequest_InvalidToken (Could not validate the client concurrency token): falta la cabecera If-Match en un PATCH o DELETE, o la etag que envías no es válida.
• Request_EntityChanged: alguien modificó el registro entre tu lectura y tu escritura. Vuelve a leerlo y repite el cambio.

2. Aísla la llamada

Antes de tocar código, reproduce la llamada fuera de tu integración, con un cliente REST como Bruno, Insomnia, la extensión REST Client de Visual Studio Code o simplemente curl. Mismo token, misma URL y mismo cuerpo:

curl -s "https://api.businesscentral.dynamics.com/v2.0/$TENANT/sandbox/api/v2.0/companies($COMPANY_ID)/salesOrders?\$top=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "client-request-id: $(uuidgen)" \
  -H "User-Agent: mi-integracion/1.4"

Tres comprobaciones que resuelven buena parte de los 401 y 404:

• Decodifica el token (por ejemplo, en jwt.ms, el decodificador de Microsoft). aud tiene que ser https://api.businesscentral.dynamics.com, tid el tenant correcto y, en un token de aplicación, roles debe incluir API.ReadWrite.All. Mira también exp: un token caducado da 401.
• Consulta el $metadata del endpoint (.../api/v2.0/$metadata, o .../api/{publisher}/{grupo}/v1.0/$metadata en una API propia). Ahí están los nombres reales de entidades y campos, y si tu API propia no aparece, la extensión no está instalada en ese entorno.
• Envía siempre client-request-id con un GUID, y un User-Agent que identifique tu integración. Las dos cabeceras se guardan en la telemetría, y con el GUID encontrarás tu llamada exacta en el paso siguiente.

3. Telemetría: lo que vio el servidor

Si el entorno envía telemetría a Azure Application Insights, cada llamada que recibe Business Central queda registrada con el evento RT0008: endpoint, método, código HTTP, tiempo de ejecución, objeto AL y extensión que la atendieron y, desde la versión 22, el motivo del error (failureReason) tal como lo vio el servidor.

Cómo se activa:

• SaaS: el administrador añade la cadena de conexión de Application Insights al entorno desde el Business Central Admin Center. Si publicas extensiones, también puedes ponerla en el app.json (applicationInsightsConnectionString) y recibir la telemetría de tus objetos.
• On-premises: la misma cadena de conexión se configura en la instancia del servidor (ApplicationInsightsConnectionString).

Esta consulta KQL lista las llamadas fallidas del último día con lo necesario para entender qué ha pasado:

traces
| where timestamp > ago(1d)
| where customDimensions has "RT0008"
| where customDimensions.eventId == "RT0008"
| where toint(customDimensions.httpStatusCode) >= 400
| project timestamp
, endpoint = tostring(customDimensions.endpoint)
, httpMethod = tostring(customDimensions.httpMethod)
, httpStatusCode = tostring(customDimensions.httpStatusCode)
, failureReason = tostring(customDimensions.failureReason)
, alObjectName = tostring(customDimensions.alObjectName)
, extensionName = tostring(customDimensions.extensionName)
, executionTimeMs = toreal(totimespan(customDimensions.serverExecutionTime)) / 10000
| order by timestamp desc

Para encontrar una llamada concreta, filtra por el GUID que enviaste añadiendo | where tostring(customDimensions.httpHeaders) has "tu-guid" antes del project (después, customDimensions ya no existe).

Otras dimensiones que ayudan:

• requestQueueTime: cuánto esperó la petición en cola antes de ejecutarse. Si sube, estás rozando los límites de peticiones simultáneas.
• sqlExecutes y sqlRowsRead: si una llamada lee cientos de miles de filas, falta un filtro o sobra un campo calculado.
• extensionPublisher: te dice de quién es el código que atendió la llamada. Muy útil cuando el error viene de una app de terceros.

Ten en cuenta que la telemetría llega a Application Insights con unos minutos de retraso, y que las llamadas SOAP no registran ni el código HTTP ni el motivo del error.

4. El depurador: ver el código AL que se ejecuta

Cuando el error viene de la lógica AL (los Application_*), lo más rápido es ver el código mientras atiende la llamada. Aquí es donde más cambia la cosa entre entornos.

Sandbox online: adjuntar a la siguiente llamada

En un sandbox puedes adjuntar el depurador de Visual Studio Code y decirle que se detenga en la siguiente sesión de servicio web:

{
  "name": "Attach: siguiente llamada web service (sandbox)",
  "type": "al",
  "request": "attach",
  "environmentType": "Sandbox",
  "environmentName": "sandbox",
  "breakOnNext": "WebServiceClient",
  "breakOnError": true
}

1. Publica la versión actual de la extensión (Ctrl+F5) para que el código local coincida con el del servidor.
2. Pon los puntos de interrupción y pulsa F5 para adjuntarte.
3. Lanza la llamada desde tu cliente REST. El depurador se detiene en tus puntos de interrupción y, con breakOnError, también en la línea que lanza el error.

Por defecto, solo puedes depurar las llamadas que haga tu propio usuario, así que lanza la llamada con un token de tu usuario. Si la que falla es la de una aplicación de Entra (servidor a servidor), añade "userId" con el id del usuario que Business Central crea para esa aplicación (lo encuentras en la tabla de usuarios). Para depurar sesiones de otro usuario, el tuyo necesita el conjunto de permisos D365 ATTACH DEBUG.

Producción online: snapshot debugging

En producción no puedes adjuntar el depurador, pero sí grabar una ejecución y depurarla después sin conexión. Es el snapshot debugging:

{
  "name": "Snapshot: siguiente llamada web service (producción)",
  "type": "al",
  "request": "snapshotInitialize",
  "environmentType": "Production",
  "environmentName": "production",
  "breakOnNext": "WebServiceClient",
  "userId": "id-del-usuario-de-la-aplicacion"
}

1. Marca los snappoints: se colocan igual que los puntos de interrupción, pero no detienen nada. Guardan el estado de las variables en ese punto. Los errores AL se graban siempre, aunque no pongas ninguno.
2. Pulsa F7 para iniciar la grabación y reproduce la llamada que falla.
3. Pulsa Alt+F7 para terminar. Visual Studio Code descarga el fichero .snapshot, que puedes depurar paso a paso como si fuera una sesión normal.

Lo que conviene saber:

• Tu usuario necesita el conjunto de permisos D365 Snapshot Debug.
• Los símbolos tienen que coincidir con los de producción. Si no, los puntos caen en líneas que no son.
• Si nadie hace la llamada en 30 minutos, la sesión se cierra; una vez empieza a grabar, hay que terminarla en 10 minutos.
• El snapshot puede contener datos personales de clientes. Trátalo como tal y bórralo cuando acabes.

Desde la versión 29 existe también, en preview, un servidor MCP de snapshot debugging para que un agente de IA prepare la grabación y la recoja por ti. El mecanismo de fondo es el mismo.

On-premises: adjuntar a tu servidor

En on-premises tienes las dos opciones (adjuntar y snapshot) contra tu propia instancia. La configuración cambia el entorno por el servidor:

{
  "name": "Attach: siguiente llamada web service (on-premises)",
  "type": "al",
  "request": "attach",
  "server": "https://bc-server",
  "serverInstance": "BC",
  "port": 7049,
  "authentication": "UserPassword",
  "breakOnNext": "WebServiceClient",
  "breakOnError": true
}

El puerto es el del endpoint de desarrollo de la instancia (7049 por defecto), que tiene que estar habilitado. Si el servidor usa autenticación de Windows, no puedes indicar userId: solo adjuntarte a la siguiente sesión o a una sesión concreta.

Cuando el depurador no se detiene

Hace poco me tocó depurar con un compañero una integración intercompany: al crear líneas en un pedido de venta de una empresa, Business Central llamaba a su propio servicio web para modificar el pedido de compra de otra empresa del mismo entorno. El servicio se ejecutaba (las líneas aparecían en la otra empresa, pero mal), y el depurador no se detenía en ningún punto. Estos fueron los problemas, por orden:

• breakOnNext tiene que ser WebServiceClient. Con WebClient te adjuntas a la siguiente sesión de la interfaz web, y con Background a una sesión en segundo plano. Si el valor se ha cambiado sin querer, el depurador se queda esperando una sesión que nunca llega. Borra el valor y pulsa Ctrl+Espacio para ver las opciones.
• La sesión del servicio web no es la tuya. Aunque tú lances el proceso desde la pantalla, la llamada la hace el usuario del servicio web (el de las credenciales que usa el código, a menudo guardadas en una tabla de configuración). Y por defecto solo te adjuntas a sesiones de tu propio usuario.
• userId no existe en versiones antiguas. Adjuntarse a la sesión de otro usuario llegó en versiones recientes (hacia la 22). Aquella instalación era una 18, así que la propiedad no hacía nada. La solución fue autenticarse en Visual Studio Code con el usuario del servicio web: ejecutar AL: Clear credentials cache, pulsar F5 e introducir sus credenciales. A partir de ahí, la siguiente llamada se detuvo en el punto de interrupción.
• Adjuntarse no publica. F5 con una configuración attach solo se engancha al servidor; no despliega tu código. Si lo que hay publicado no coincide con tu código local, los puntos de interrupción caen en líneas que no son o no se activan.
• Sin punto de interrupción ni error, no se para nada. Pon el punto en la primera línea del método que expone el servicio, no en el código que hace la petición: ese se ejecuta en otra sesión.
• breakOnError: "ExcludeTry" evita que el depurador se detenga en los errores capturados por funciones [TryFunction], que si no te frenan a cada paso. En versiones antiguas puede que no lo respete; en ese caso, dale a continuar.

Un detalle más: en la barra del depurador, en una sesión attach, el botón de parar es en realidad desconectar. La sesión del usuario sigue viva.

5. Lo que cambia en on-premises

Además del depurador, en on-premises hay errores que en SaaS no existen, porque el servidor lo administras tú:

• Los servicios tienen que estar activos. OData viene activado por defecto, pero las APIs no. Si una llamada a /api/ devuelve 405, empieza por aquí:

  Set-NAVServerConfiguration BC -KeyName ApiServicesEnabled -KeyValue true
  Restart-NAVServerInstance BC

  El cambio no se aplica en caliente: hay que reiniciar la instancia.

• La URL es la de tu servidor: https://bc-server:7048/BC/api/v2.0/companies(...), con el puerto de OData (7048 por defecto) abierto en el firewall. Si hay un proxy o un nombre público delante, revisa PublicODataBaseUrl: es la URL base que el servidor publica para sus servicios OData.

• La autenticación depende de la instalación: con NavUserPassword sigue existiendo la clave de acceso a servicios web como contraseña; con Microsoft Entra ID, el token funciona igual que en SaaS.

• El Visor de eventos de Windows es tu primera fuente de errores: Registros de aplicaciones y servicios → Microsoft → DynamicsNAV → Server → Admin. Desde PowerShell:

  Get-WinEvent -LogName 'Microsoft-DynamicsNAV-Server/Admin' -MaxEvents 50 -FilterXPath "*[System[(Level=2)]]" |
    Format-List TimeCreated, Message

  Si necesitas más detalle, el registro Debug de ese mismo canal recoge llamadas a servicios, SQL y trazas AL. Viene desactivado y oculto por defecto: actívalo solo mientras investigas, porque crece muy rápido.

• Los límites son tuyos: el tiempo máximo de una petición, el tamaño de página y el resto de límites se configuran en la instancia, así que un 408 en on-premises puede ser una configuración demasiado estricta.

6. Y cuando la llamada la hace Business Central

A veces el problema va en el otro sentido: es tu extensión la que llama a un servicio externo con HttpClient y falla.

• En un sandbox, las llamadas salientes están bloqueadas por defecto. Hay que permitirlas extensión a extensión: Administración de extensiones → Configurar → Permitir solicitudes de HttpClient (Allow HttpClient Requests). Incluye las extensiones de librería y, ojo, al copiar un entorno el permiso vuelve a desactivarse. Durante la ejecución de tests en un sandbox, las llamadas HTTP están bloqueadas para todas las extensiones.

• La telemetría registra cada llamada saliente con el evento RT0019: endpoint (solo la URL base), método, código HTTP, tiempo, la pila AL que hizo la llamada y, desde la versión 29, httpRequestError, que distingue un fallo de DNS, de conexión o de certificado.

• Comprueba siempre la respuesta en el código. Que Get o Send devuelvan true solo significa que hubo respuesta, no que fuera buena:

  procedure CallExternalService(Url: Text)
  var
      Client: HttpClient;
      Response: HttpResponseMessage;
      Body: Text;
  begin
      if not Client.Get(Url, Response) then
          Error('No se pudo conectar con %1: %2', Url, GetLastErrorText());
      Response.Content.ReadAs(Body);
      if not Response.IsSuccessStatusCode then
          Error('El servicio respondió %1: %2', Response.HttpStatusCode, CopyStr(Body, 1, 250));
  end;

Con el código de estado y el principio del cuerpo en el mensaje, el error se entiende desde la pantalla, desde la telemetría y desde el depurador.

Funciona en sandbox pero no en producción

Es el caso más habitual, y casi siempre es uno de estos:

• La aplicación de Entra no está dada de alta en la página Aplicaciones de Microsoft Entra de producción, o tiene otros conjuntos de permisos. Cada entorno tiene la suya.
• La URL apunta a otro entorno o usa un id de empresa que en producción es distinto.
• La extensión que publica la API propia no está instalada en producción, o está en otra versión (de ahí los 404).
• En el sentido contrario (funciona en producción y no en el sandbox), casi siempre es el permiso de HttpClient del apartado anterior.

Resumen

1. Código HTTP y código de error: te dicen en qué capa mirar.
2. Reproduce la llamada aislada y revisa el token y el $metadata.
3. Telemetría: RT0008 para lo que entra y RT0019 para lo que sale. Envía siempre client-request-id.
4. Depurador: adjuntar en sandbox y on-premises, snapshot en producción.

Si quieres repasar cómo autenticarte y construir las llamadas, lo tienes en OData y API en Business Central. Y si tienes una integración que falla y no hay manera de ver por qué, cuéntamelo.

En Business Central eso ya no se hace (en online, directamente no se puede). Todo lo que añades va en una extensión: un paquete aparte que se engancha al estándar sin tocarlo. Es la diferencia entre actualizar con miedo y actualizar dos veces al año sin que nadie se entere.

Qué es una extensión

Una extensión es un proyecto en AL (el lenguaje de Business Central) que se compila en un fichero .app. Dentro puede haber:

• Objetos nuevos: tablas, páginas, codeunits (lógica), informes, consultas, enums, APIs...
• Extensiones de objetos estándar: tableextension para añadir campos a una tabla de Microsoft, pageextension para mostrarlos en sus pantallas, reportextension para ampliar sus informes.
• Suscriptores de eventos: código que se ejecuta cuando el estándar "avisa" de que algo pasa.
• Conjuntos de permisos para que cada usuario vea solo lo que debe.

Las extensiones a medida usan el rango de identificadores 50.000 a 99.999. Se instalan, actualizan y desinstalan por separado del estándar.

Cómo se engancha al estándar: un ejemplo

Un caso típico: cada cliente tiene unas instrucciones de entrega y quieres que pasen solas a sus pedidos. Primero, el campo en el cliente y en la cabecera de venta:

tableextension 50100 "CM Customer" extends Customer
{
    fields
    {
        field(50100; "CM Delivery Instructions"; Text[250])
        {
            Caption = 'Instrucciones de entrega';
            DataClassification = CustomerContent;
        }
    }
}

tableextension 50101 "CM Sales Header" extends "Sales Header"
{
    fields
    {
        field(50100; "CM Delivery Instructions"; Text[250])
        {
            Caption = 'Instrucciones de entrega';
            DataClassification = CustomerContent;
        }
    }
}

Después, mostrarlo en la ficha del cliente (y del mismo modo en el pedido):

pageextension 50100 "CM Customer Card" extends "Customer Card"
{
    layout
    {
        addlast(Shipping)
        {
            field("CM Delivery Instructions"; Rec."CM Delivery Instructions")
            {
                ApplicationArea = All;
                ToolTip = 'Instrucciones que se copian a los pedidos de este cliente.';
            }
        }
    }
}

Y por último, la lógica. En lugar de modificar el código que rellena el pedido, nos suscribimos al evento que se dispara cuando se elige el cliente:

codeunit 50100 "CM Sales Subscribers"
{
    [EventSubscriber(ObjectType::Table, Database::"Sales Header", 'OnAfterValidateEvent', 'Sell-to Customer No.', false, false)]
    local procedure CopyDeliveryInstructions(var Rec: Record "Sales Header"; var xRec: Record "Sales Header"; CurrFieldNo: Integer)
    var
        Customer: Record Customer;
    begin
        if not Customer.Get(Rec."Sell-to Customer No.") then
            exit;
        Rec."CM Delivery Instructions" := Customer."CM Delivery Instructions";
    end;
}

Cuatro objetos, cero líneas de Microsoft modificadas. Cuando llegue la siguiente versión, el estándar se actualiza por debajo y la extensión sigue enganchada al mismo evento.

Un detalle: el prefijo CM en nombres y campos. Evita choques con otras extensiones que añadan un campo con el mismo nombre a la misma tabla, y es una buena práctica que conviene seguir desde el primer objeto. En las apps que se publican en el marketplace de Microsoft, además, es obligatorio: el prefijo se registra y tiene al menos tres caracteres.

Extensión a medida o app de AppSource

Hay dos tipos de extensión:

• PTE (per-tenant extension): se hace para una empresa concreta y solo se instala en su Business Central. Es lo que se usa para adaptar el ERP a un proceso propio.
• App de AppSource: un producto publicado en el marketplace de Microsoft (AppSource, hoy integrado en Microsoft Marketplace), que pasa su validación técnica y cualquiera puede instalar.

Antes de desarrollar una PTE, merece la pena buscar en AppSource: si ya hay una app que resuelve el caso (conectores de bancos, de transportistas, EDI, captura de documentos...), suele salir más a cuenta. Muchas veces la solución es mixta: una app de AppSource y una extensión pequeña que la adapta a tu forma de trabajar.

Lo que hace que una extensión sobreviva a las actualizaciones

Microsoft publica dos versiones mayores al año (en primavera y en otoño) y actualizaciones menores cada mes. Que una extensión las aguante sin problemas no es suerte:

• Usa eventos y procedimientos públicos, no copias del código estándar. Si copias una función de Microsoft para cambiarle una línea, te quedas con una versión que ya no se actualiza.
• Atiende a los avisos de obsoleto. Antes de retirar algo, Microsoft lo marca como ObsoleteState = Pending y lo mantiene así alrededor de un año. El compilador te avisa: esas advertencias son tareas pendientes, no ruido.
• Prueba en un sandbox con la versión preview. Microsoft publica la siguiente versión mayor en preview antes de lanzarla. Compilar y probar ahí la extensión te dice con margen si algo va a romperse.
• Ten tests automatizados de los procesos críticos. AL tiene codeunits de test (Subtype = Test) que puedes ejecutar en cada compilación.
• Control de versiones y compilación automática. El código en Git y un pipeline que compila y prueba cada cambio. Microsoft mantiene plantillas para esto (AL-Go for GitHub).

Cómo se publica

En Business Central online, las extensiones a medida se instalan desde el Business Central Admin Center (o su API), donde además puedes programar cuándo se actualizan. Desde la versión 28, subirlas desde la página Administración de extensiones dentro del propio Business Central se está retirando: en 2027 dejará de estar disponible para eso.

En on-premises, se publican con las herramientas de administración del servidor (PowerShell).

En los dos casos, el camino es el mismo: primero al sandbox, se prueba, y después a producción.

Resumen

• En Business Central no se modifica el estándar: se extiende.
• Una extensión bien hecha usa eventos, prefijos propios y el rango de identificadores reservado.
• Antes de programar, busca en AppSource.
• La compatibilidad con las actualizaciones se trabaja: avisos de obsoleto, sandbox con preview y tests.

Si tienes un proceso que el estándar no cubre o una personalización de Navision que hay que pasar a extensión, te cuento cómo trabajo el desarrollo de extensiones.

En este artículo te explico las tres, cómo autenticarte y las consultas que vas a usar a diario.

Las tres formas de leer y escribir datos

La diferencia de fondo: una API es un contrato. Microsoft no cambia la API v2.0 sin versionarla, y tus APIs propias solo cambian cuando tú quieres. Una página publicada como servicio web es una pantalla, y las pantallas cambian en cada versión sin que eso se considere un cambio que rompa nada.

Las URLs

Todas cuelgan del mismo dominio. Necesitas el id del tenant (o su dominio), el nombre del entorno (production, sandbox...) y la empresa:

# API estándar v2.0
https://api.businesscentral.dynamics.com/v2.0/{tenant}/{entorno}/api/v2.0/companies({companyId})/customers

# API propia: publisher, grupo y versión de tu página API
https://api.businesscentral.dynamics.com/v2.0/{tenant}/{entorno}/api/{publisher}/{grupo}/v1.0/companies({companyId})/{entitySetName}

# Servicio web OData publicado
https://api.businesscentral.dynamics.com/v2.0/{tenant}/{entorno}/ODataV4/Company('{nombre}')/{nombreServicio}

El companyId es un GUID. Lo obtienes con una primera llamada a .../api/v2.0/companies, que devuelve todas las empresas del entorno con su id.

Autenticación: OAuth 2.0 y nada más

Desde el 1 de octubre de 2022, Business Central online no acepta las claves de acceso a servicios web (la antigua autenticación básica con usuario y clave). La única opción es OAuth 2.0 con Microsoft Entra ID.

Para una integración de servidor a servidor (tu backend hablando con Business Central, sin usuario delante), el flujo es client credentials:

1. Registra una aplicación en Microsoft Entra ID (portal de Azure) y créale un secreto o, mejor, un certificado.
2. En Permisos de API, añade Dynamics 365 Business Central con el permiso de aplicación API.ReadWrite.All y concede el consentimiento de administrador.
3. En Business Central, abre la página Aplicaciones de Microsoft Entra, da de alta el id de cliente de la aplicación y asígnale solo los conjuntos de permisos que necesite (Business Central ni siquiera permite asignar SUPER a una aplicación).
4. Pide el token y úsalo en cada llamada:

const res = await fetch(`https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`, {
  method: 'POST',
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: clientId,
    client_secret: clientSecret,
    scope: 'https://api.businesscentral.dynamics.com/.default'
  })
});
const { access_token, expires_in } = await res.json();

const customers = await fetch(`${baseUrl}/companies(${companyId})/customers`, {
  headers: { Authorization: `Bearer ${access_token}` }
}).then(r => r.json());

Guarda el token en caché hasta que caduque (expires_in, en segundos) en lugar de pedir uno nuevo en cada llamada. Y todo esto vive en tu servidor: el secreto nunca debe llegar al navegador.

Consultas que vas a usar a diario

La API habla OData v4, así que filtras, eliges campos y expandes relaciones con parámetros en la URL:

GET .../companies({companyId})/salesOrders
    ?$filter=status eq 'Open' and orderDate ge 2026-01-01
    &$select=number,customerName,orderDate,totalAmountIncludingTax
    &$expand=salesOrderLines
    &$orderby=orderDate desc
    &$top=50

• $filter: filtra en el servidor. No te traigas 20.000 registros para quedarte con 10.
• $select: pide solo los campos que vas a usar. Las respuestas pesan menos y llegan antes.
• $expand: trae las líneas con la cabecera en una sola llamada.
• Paginación: si hay más resultados, la respuesta incluye @odata.nextLink. Síguelo hasta que no aparezca.
• Sincronización incremental: casi todas las entidades tienen lastModifiedDateTime. Filtra por la fecha de tu última sincronización ($filter=lastModifiedDateTime gt 2026-10-01T00:00:00Z) en lugar de leerlo todo cada vez.
• Ojo con status: los valores de la API no coinciden con los de la pantalla. Un pedido Abierto en Business Central sale como Draft, y Open es un pedido ya Lanzado (o pendiente de prepago). El filtro del ejemplo trae, por tanto, los pedidos lanzados.

Para modificar o borrar (PATCH, DELETE), Business Central exige la cabecera If-Match con el @odata.etag del registro que leíste. Es control de concurrencia: si alguien lo ha cambiado entretanto, la llamada falla en lugar de pisar su cambio.

Límites: el 429 te va a llegar

Business Central online limita las peticiones por usuario (y una aplicación de Entra cuenta como un usuario más):

En la práctica: implementa reintentos con espera creciente para 429 y 503, usa $batch cuando tengas que mandar muchas operaciones pequeñas y no hagas lecturas completas cada pocos minutos. Si una integración es muy intensiva, Microsoft recomienda repartir la carga entre varios usuarios o aplicaciones.

Lo que cambia en 2026 y 2027

Esto es lo que más integraciones va a romper en los próximos meses:

• SOAP en páginas de Microsoft: desde la versión 29 (2026 release wave 2, la actual) ya no se pueden publicar páginas de Microsoft como servicio SOAP.
• OData en páginas de Microsoft: a partir de la versión 30 (2027 release wave 1, primavera de 2027) tampoco se podrán publicar como servicio OData. Si tu integración lee, por ejemplo, la página Ficha cliente publicada en Servicios web, dejará de funcionar.
• API v1.0: se retiró en la versión 28. Si algo sigue llamando a /api/v1.0/, ya está roto o lo estará al actualizar.
• Delta links: retirados desde la versión 24. Para saber qué ha cambiado, usa webhooks o lastModifiedDateTime.

Microsoft lo justifica así: una página es una pantalla, no una API, y cambiarla no se considera un cambio incompatible. Las alternativas son pasar a la API v2.0, o copiar la página a una extensión propia o, mejor, crear una API propia.

Una API propia en AL

Cuando la API estándar no trae lo que necesitas, una página de tipo API en una extensión es la solución limpia. Este ejemplo expone el stock y el precio de los artículos para una tienda online:

page 50100 "CM Item Stock API"
{
    PageType = API;
    APIPublisher = 'cristianmartinez';
    APIGroup = 'shop';
    APIVersion = 'v1.0';
    EntityName = 'itemStock';
    EntitySetName = 'itemStocks';
    SourceTable = Item;
    ODataKeyFields = SystemId;
    Editable = false;
    DataAccessIntent = ReadOnly;

    layout
    {
        area(Content)
        {
            repeater(Records)
            {
                field(id; Rec.SystemId) { }
                field(number; Rec."No.") { }
                field(description; Rec.Description) { }
                field(unitPrice; Rec."Unit Price") { }
                field(inventory; Rec.Inventory) { }
                field(lastModifiedDateTime; Rec.SystemModifiedAt) { }
            }
        }
    }
}

Se consulta en .../api/cristianmartinez/shop/v1.0/companies({companyId})/itemStocks. Tres detalles importantes:

• ODataKeyFields = SystemId: la clave es un GUID inmutable, como en la API estándar: no cambia aunque alguien renumere el artículo.
• DataAccessIntent = ReadOnly: las lecturas van a la réplica de solo lectura, cuando está disponible, y no compiten con los usuarios que están trabajando.
• La versión en la URL (v1.0): cuando tengas que cambiar el contrato, publicas una v2.0 al lado y no rompes a quien ya consume la primera.

Resumen

• ¿Lo cubre la API v2.0? Úsala.
• ¿Necesitas campos o lógica propios? API propia en una extensión.
• ¿Tienes integraciones sobre páginas de Microsoft publicadas como OData? Revísalas antes de la versión 30.
• Autenticación: OAuth con una aplicación de Entra ID y los permisos justos.
• Diseña pensando en los límites: filtros, sincronización incremental y reintentos.

Si quieres ver cómo encaja todo esto en una integración completa, lo explico en cómo conectar tu web o tienda online con Business Central. Y si necesitas una API propia o revisar una integración antes de la versión 30, hablemos.

Hay tres caminos. Van de menos a más trabajo, y conviene agotar cada uno antes de pasar al siguiente.

1. Las apps de Power BI de Microsoft

Microsoft publica apps de Power BI listas para usar por área funcional: finanzas, ventas, compras, inventario, valoración de inventario, proyectos y fabricación, y en las últimas versiones también sostenibilidad y facturación de suscripciones. Llegaron en la versión 25.1 y sustituyen a las antiguas apps de CRM, Finance y Sales, que se retiraron en 2026.

• Se instalan desde Power BI (Aplicaciones → Obtener aplicaciones) o desde Microsoft Marketplace, y se conectan indicando el nombre completo de la empresa (el de la página Empresas, no el nombre para mostrar) y el entorno.
• Funcionan por empresa: si tienes varias, instalas y configuras una por cada una, cada una en su área de trabajo.
• Se integran en Business Central: los informes aparecen dentro del propio ERP, en la página de inicio de cada rol.
• Leen de la Analytics API, una API de solo lectura pensada para informes (/api/microsoft/analytics/v1.0/).

Las apps no tienen coste. Lo que necesitas son licencias de Power BI Pro (o capacidad Premium) para quien instale la app, actualice los datos y vea los informes, además de su licencia de Business Central; revisa qué incluye tu tenant.

Si tus indicadores son los habituales (ventas por cliente, márgenes, antigüedad de saldos, rotación de stock...), empieza aquí. Te ahorras semanas de modelado y Microsoft las mantiene con cada versión.

2. Power BI Desktop con el conector de Business Central

Cuando quieres tu propio modelo o combinar Business Central con otras fuentes:

1. En Power BI Desktop, Obtener datos → Servicios en línea → Dynamics 365 Business Central.
2. Inicia sesión con tu cuenta de organización.
3. En el navegador aparecen tus entornos, dentro de cada uno sus empresas, y dentro de cada empresa tres carpetas: Advanced APIs, Standard APIs v2.0 y los servicios web publicados (legacy).

Microsoft recomienda usar las APIs y no los servicios web. Hay un motivo más: a partir de la versión 30 (primavera de 2027) ya no se podrán publicar páginas de Microsoft como servicio OData, así que un informe construido sobre, por ejemplo, la página de movimientos de clientes publicada en Servicios web dejará de actualizarse. Lo explico con más detalle en OData y API en Business Central.

3. APIs propias para informes

Cuando necesitas campos de tus extensiones, tablas propias o datos agregados que la API estándar no trae, la herramienta adecuada es una consulta de tipo API en AL. A diferencia de una página, una consulta puede unir tablas y agregar en el servidor: Power BI recibe el resultado ya resumido en lugar de millones de movimientos.

query 50110 "CM Sales By Customer API"
{
    QueryType = API;
    APIPublisher = 'cristianmartinez';
    APIGroup = 'reporting';
    APIVersion = 'v1.0';
    EntityName = 'customerSale';
    EntitySetName = 'customerSales';
    DataAccessIntent = ReadOnly;

    elements
    {
        dataitem(CustLedgerEntry; "Cust. Ledger Entry")
        {
            column(customerNumber; "Customer No.") { }
            column(postingYear; "Posting Date") { Method = Year; }
            column(postingMonth; "Posting Date") { Method = Month; }
            column(salesAmount; "Sales (LCY)") { Method = Sum; }
        }
    }
}

Esta consulta devuelve las ventas por cliente, año y mes ya sumadas. Una vez instalada la extensión, la ves en el navegador del conector de Power BI, en Advanced APIs, bajo el APIPublisher y el APIGroup que hayas definido.

DataAccessIntent = ReadOnly indica que la consulta puede leer de la réplica de solo lectura de la base de datos, así que un informe pesado no compite con los usuarios que están registrando pedidos. El conector de Power BI ya pide esa réplica por defecto, pero dejarlo declarado en la consulta protege también al resto de clientes que la usen.

Que el informe no tarde una eternidad

• Trae solo las columnas que usas. Quita en Power Query todo lo que no vaya al modelo, lo antes posible.
• Filtra por fecha. Los movimientos de cinco años atrás rara vez hacen falta en el informe diario.
• Agrega en Business Central, con consultas API, en lugar de traerte todos los movimientos para sumarlos en Power BI.
• Usa la actualización incremental de Power BI en las tablas grandes de movimientos: solo se recargan los últimos días.
• Ojo con los límites. Power BI hace peticiones como cualquier otra integración y cuenta para el límite de 6.000 peticiones cada 5 minutos por usuario. Si programas muchos informes a la misma hora con el mismo usuario, repártelos.

Qué opción elegir

• KPIs estándar de finanzas, ventas, compras o inventario → apps de Power BI de Microsoft.
• Modelo propio con datos estándar → Power BI Desktop con las Standard APIs v2.0.
• Campos de extensiones, tablas propias o grandes volúmenes → consultas API propias con DataAccessIntent = ReadOnly.
• Informes sobre páginas de Microsoft publicadas como servicio web → toca migrarlos antes de la versión 30.

Si necesitas una consulta API a medida o revisar por qué un informe tarda tanto, escríbeme.