API REST (REST)

Qué es y cuándo aplica

REST (Representational State Transfer) es un estilo arquitectónico para sistemas distribuidos definido por Roy Fielding en su tesis doctoral de 2000 (“Architectural Styles and the Design of Network-based Software Architectures”). No es un protocolo, no es un estándar W3C, no es un producto: es un conjunto de restricciones arquitectónicas que, aplicadas sobre HTTP, producen sistemas escalables, cacheables y con bajo acoplamiento entre cliente y servidor.

Las seis restricciones REST originales son: arquitectura cliente-servidor, stateless (sin estado en el servidor entre llamadas), caché, interfaz uniforme (recursos identificados por URI, manipulación por representación, mensajes auto-descriptivos, HATEOAS), sistema en capas y código bajo demanda (opcional). Una API es RESTful cuando cumple esas restricciones; muchas APIs que se llaman “REST” en realidad son HTTP+JSON sin cumplir todas (en particular HATEOAS), por lo que el término más honesto en muchos casos sería “API HTTP-JSON”. En la práctica, “API REST” se usa como sinónimo de “API web sobre HTTP con verbos y recursos”.

El sentido común aplicable: una API REST se usa para que dos sistemas se hablen sobre HTTP, con verbos estándar, URLs predecibles y datos en formato textual (JSON predominantemente). Es la lingua franca de la integración moderna entre ERP, e-commerce, marketplaces, apps móviles, dashboards y sistemas de terceros.

Verbos, formatos y recursos

Los métodos HTTP se mapean a operaciones CRUD:

• GET /customers/{id}: lectura. Idempotente, cacheable, sin efectos secundarios.
• POST /customers: creación. No idempotente (cada POST crea un recurso distinto).
• PUT /customers/{id}: actualización completa. Idempotente (repetirlo deja el recurso en el mismo estado).
• PATCH /customers/{id}: actualización parcial. Idempotente si está bien diseñado.
• DELETE /customers/{id}: borrado. Idempotente.

Los códigos de respuesta importantes: 200 (OK), 201 (Created), 204 (No Content), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), 422 (Unprocessable Entity), 429 (Too Many Requests), 500 (Internal Server Error). Tratarlos como meros “errores genéricos” es un antipatrón: cada código tiene semántica diferente y la integración debe reaccionar diferente a cada uno.

El formato de datos dominante es JSON (RFC 8259). XML fue habitual hasta 2015 y persiste en integraciones legacy y en SOAP. Algunos casos especiales: multipart/form-data para subida de archivos, application/x-ndjson para streaming, text/csv para exportes masivos.

REST vs SOAP vs GraphQL vs gRPC

• REST: HTTP + JSON, recursos, sin estado, basado en estándares web. Ideal para CRUD y casos generales. Curva de aprendizaje suave.
• SOAP: XML + WSDL + WS-*. Pesado, verboso, pero con seguridad y transacciones distribuidas formales. Persiste en banca, sanidad, administración pública y algunas integraciones B2B clásicas.
• GraphQL: el cliente pide exactamente los campos que necesita en una sola consulta. Resuelve el problema del over-fetching / under-fetching de REST. Compleja la cacheabilidad y los rate limits. Útil cuando el consumidor es un front-end móvil con consultas muy variables.
• gRPC: HTTP/2 + Protocol Buffers binarios. Alto rendimiento, ideal para microservicios internos. Poco amigable con clientes web sin proxy. Habitual en el “service mesh” de plataformas modernas.

REST sigue siendo la opción por defecto en integraciones empresariales: amplísima compatibilidad, documentación con OpenAPI / Swagger, ecosistema maduro de herramientas (Postman, Insomnia, curl).

API REST en Business Central

Business Central expone su funcionalidad por dos vías de API:

• API estándar v2.0: REST sobre https://api.businesscentral.dynamics.com/v2.0/{tenantId}/{environment}/api/v2.0/. Endpoints canónicos para companies, customers, items, salesInvoices, purchaseInvoices, journalLines, vendors, accounts y un largo etcétera. Formato JSON. Filtrado, paginación y ordenación por OData ($filter, $top, $skip, $orderby, $select, $expand). Es la API recomendada para integraciones de terceros (e-commerce, EDI, CRM, BI) por su estabilidad de contrato.
• API custom (AL): cualquier desarrollador puede publicar páginas como APIs custom desde una extensión AL con el atributo APIPublisher, APIGroup, APIVersion, EntityName. Es la vía para exponer lógica de negocio propia o tablas que no están en la API estándar (proyectos dvproject, partes de producción dvproduction, libros de IVA dvimpuestos).
• OData v4: además de la API REST formal, BC expone OData v4 sobre las páginas marcadas como web service. Es la opción “legacy moderna”: cualquier página de BC puede convertirse en endpoint con dos clics, sin AL. Útil para PowerBI, Excel y dashboards ad hoc, pero sin las garantías de versionado de la API formal.

Autenticación

Desde Business Central 2022 Wave 2 (BC 21), la autenticación obligatoria es OAuth 2.0 sobre Azure AD (Microsoft Entra ID). Los flujos:

• Client Credentials: para integraciones servidor a servidor (S2S). Una app registration en Entra ID con secret o certificado, y los permisos delegados al tenant de BC. Es el patrón estándar para ERP-a-marketplace, ERP-a-eCommerce, ERP-a-BI.
• Authorization Code: para integraciones donde el usuario final se autentica (apps móviles, portales de cliente).

La basic auth con Web Service Access Key está deprecada y eliminada en SaaS.

Casos típicos de integración

• E-commerce y marketplaces (Shopify, PrestaShop, Magento, Amazon): sincronización de catálogo (items y precios desde BC al canal), pedidos (del canal a BC como pedidos de venta) y stock (de BC al canal en cuasi-tiempo real). Patrón habitual con conector intermedio (iPaaS o desarrollo a medida).
• EDI / B2B: pedidos de cliente, ASN, factura electrónica via dvfactura-e sobre APIs REST. Mejora dramática de tiempo de proceso.
• Logística: integración con plataformas de transporte (DHL, MRW, Seur, Correos), trackings y etiquetas vía REST.
• Dashboards y BI (Power BI, Qlik, Tableau) sobre las APIs estándar o vistas OData.
• Apps móviles de comerciales, almacén o producción que leen y escriben en BC sin requerir cliente pesado.

Errores frecuentes

1. No respetar los rate limits. Business Central SaaS impone límites por tenant y por endpoint (típicamente 600 req/min y 6.000 req/5 min por entorno productivo, ajustable). Saturar con sincronizaciones masivas en hora pico genera respuestas 429 Too Many Requests. La solución es backoff exponencial y batch endpoints, no aumentar la frecuencia.
2. Ignorar la paginación. Las consultas devuelven por defecto 20.000 registros máximo con @odata.nextLink. Una integración que asume “una página = todos los datos” pierde silenciosamente registros cuando el catálogo crece.
3. No manejar el lock optimista (ETag). Las actualizaciones (PATCH, DELETE) requieren cabecera If-Match con el ETag del recurso. Sin ETag, BC responde 412 Precondition Failed. Ignorarlo lleva a sobrescrituras silenciosas.
4. Confundir errores 4xx con 5xx. Un 4xx no se reintenta (es culpa del cliente: datos mal formados, autenticación caducada, recurso inexistente). Un 5xx sí se reintenta (problema temporal del servidor). Las integraciones que reintentan 401 indefinidamente acaban bloqueando la app registration.
5. Hardcodear el tenant ID o el entorno. Mover de sandbox a producción rompe la integración. Variables de entorno y configuración externalizada son obligatorias.
6. No versionar la API custom. Publicar una API AL sin APIVersion (“v1.0”, “v2.0”) y romper compatibilidad en una release rompe todas las integraciones del cliente sin previo aviso.
7. No firmar ni cifrar payloads sensibles. OAuth protege la sesión, pero el contenido viaja en JSON plano. Datos especialmente protegidos (cuentas bancarias, datos de salud, datos personales sensibles) requieren cifrado adicional a nivel de aplicación.