Interoperabilidad ERP y API REST: guía práctica para integrar sin romperse

Resumen: Integrar un ERP con plataformas externas mediante API REST no es un proyecto de una tarde. Requiere definir contratos de datos antes de escribir la primera línea, elegir los estándares correctos y anticipar los puntos de rotura habituales. Esta guía recorre, paso a paso, lo que debe documentar un equipo de IT antes de empezar y cómo construir conexiones que aguanten en producción.

Tabla de contenidos

• Qué significa realmente la interoperabilidad ERP
• Estándares de integración que funcionan en la práctica
• Qué documentar antes de conectar nada
• Patrones para evitar integraciones frágiles
• Casos de uso habituales: ecommerce, marketplaces y software vertical
• TL;DR
• Lecturas recomendadas

Qué significa realmente la interoperabilidad ERP

Interoperabilidad no es sinónimo de tener una API. Significa que dos sistemas pueden intercambiar datos con semántica compartida: el campo stock_disponible del ERP y el campo qty_available del ecommerce hablan del mismo concepto, se actualizan en el mismo orden y la discrepancia entre ambos no supera el margen que la operativa del negocio tolera.

Un ERP sin API pública obliga a integraciones por base de datos o exportación de ficheros. Ambas opciones funcionan, pero acumulan deuda técnica rápido. Con API REST bien diseñada, la superficie de integración es predecible: endpoints documentados, versionado explícito y contratos de datos que no cambian sin previo aviso.

Lo que suele fallar no es la tecnología. Es la falta de acuerdo previo sobre qué dato es la fuente de verdad, quién escribe y quién solo lee, y qué ocurre cuando la conexión cae diez minutos.

Estándares de integración que funcionan en la práctica

REST sobre HTTP/S con JSON

Es el estándar de facto para integraciones ERP-ecommerce en 2024. La razón es pragmática: casi todos los marketplaces y plataformas SaaS exponen REST, la documentación es más accesible que SOAP y el ecosistema de herramientas de testing (Postman, Insomnia, Bruno) es maduro.

Un endpoint bien diseñado para actualizar stock sigue este patrón:

• PATCH /api/v1/products/{sku}/stock con cuerpo {"quantity": 42, "warehouse_id": "VGO01"}
• Respuesta 200 con el estado actualizado o 409 si hay conflicto de versión

OpenAPI 3.x como contrato

Documentar la API con una especificación OpenAPI 3.x antes de implementar tiene una ventaja concreta: el equipo del ERP y el equipo del ecommerce pueden validar el contrato sin desplegar nada. Herramientas como Spectral permiten hacer lint del esquema y detectar inconsistencias de tipos antes de que lleguen a producción.

Webhooks para eventos en tiempo real

Las integraciones que solo usan polling (consultar el estado cada N minutos) generan carga innecesaria y latencia variable. Los webhooks invierten el flujo: el ERP notifica al ecommerce cuando un pedido cambia de estado, en vez de que el ecommerce pregunte cada minuto. Latencia típica con webhooks bien implementados: menos de 2 segundos frente a los 5-15 minutos de un polling conservador.

OAuth 2.0 para autenticación

Las API keys estáticas son cómodas pero peligrosas: si se filtran, no hay mecanismo de revocación granular. OAuth 2.0 con client credentials es el mínimo razonable para integraciones B2B. Permite rotar credenciales sin interrumpir el servicio y auditar qué sistema accedió a qué recurso.

Qué documentar antes de conectar nada

Este es el paso que más equipos saltan. Lo que parece perder tiempo aquí se recupera multiplicado durante la fase de debugging en producción.

Mapa de flujos de datos

Documenta cada entidad que va a circular entre sistemas: productos, pedidos, stock, precios, clientes, facturas. Por cada entidad anota:

1. Sistema de origen (fuente de verdad)
2. Sistemas de destino (lectores o réplicas)
3. Frecuencia de sincronización requerida
4. Volumen estimado: número de registros por lote y operaciones por hora punta

Glosario de campos compartidos

Un campo llamado precio puede ser precio sin IVA, con IVA, tarifa especial de cliente o precio de coste, dependiendo del sistema. Antes de mapear campos, escribe un glosario con la definición exacta de cada uno. Incluye el tipo de dato, la unidad (si aplica) y el rango de valores válidos.

Política de errores y reintentos

Define por escrito qué hace cada sistema cuando recibe un error 500 del otro: ¿reintenta inmediatamente, aplica backoff exponencial, descarta el evento o lo encola para revisión manual? Sin esta política, una caída de cinco minutos puede dejar datos incoherentes durante horas.

Acuerdo de SLA entre sistemas

Si el ecommerce necesita que el stock esté actualizado en menos de 60 segundos tras una venta en tienda física, ese requisito debe estar pactado y, si el ERP no puede garantizarlo, hay que rediseñar el flujo antes de integrarlo.

Patrones para evitar integraciones frágiles

Idempotencia en todos los endpoints de escritura

Un endpoint idempotente produce el mismo resultado si se llama una o diez veces con los mismos datos. Esto permite que el cliente reintente sin miedo a duplicar registros. La forma más directa: aceptar un idempotency_key en la cabecera y almacenar el resultado de cada operación durante al menos 24 horas.

Cola de mensajes como buffer

Conectar dos sistemas directamente sin buffer intermedio crea acoplamiento temporal: si el ERP está caído, el ecommerce no puede procesar pedidos. Una cola de mensajes (RabbitMQ, Azure Service Bus, Amazon SQS) desacopla ambos sistemas: el ecommerce publica el pedido en la cola y el ERP lo consume cuando puede. La cola retiene los mensajes si el consumidor falla.

Versionado de API desde el primer día

Versionar desde /api/v1/ no es burocracia: es la única forma de cambiar el contrato sin romper a los consumidores existentes. La regla práctica: nunca elimines un campo de la respuesta en la misma versión; añade campos libremente, pero eliminarlos requiere una versión nueva.

Circuit breaker para llamadas síncronas

Si el sistema destino tarda más de X milisegundos en responder o devuelve errores de forma consecutiva, el circuit breaker abre el circuito durante un tiempo determinado y devuelve un error rápido al caller. Esto evita que una degradación en un extremo de la integración paralice toda la cadena.

Monitorización de la integración como servicio propio

Los logs de cada sistema por separado no son suficientes. Necesitas un dashboard que muestre el flujo completo: mensajes enviados, recibidos, procesados con error y tiempo de extremo a extremo. Sin esta visibilidad, depurar una incidencia de sincronización puede llevar horas.

Casos de uso habituales: ecommerce, marketplaces y software vertical

ERP + ecommerce (WooCommerce, PrestaShop, Shopify)

El flujo más crítico es la sincronización de stock. Una rotura aquí genera ventas de productos sin existencias. La integración debe ser bidireccional: el ERP actualiza el stock disponible en el ecommerce; el ecommerce envía los pedidos confirmados al ERP para generar el albarán y reservar unidades.

ERP + marketplaces (Amazon Seller Central, El Corte Inglés Marketplace)

Los marketplaces imponen sus propios formatos de datos y ventanas de actualización. Amazon acepta feeds de inventario con latencia de hasta 15 minutos. Eso significa que si vendes en tienda física y en Amazon simultáneamente, necesitas una lógica de reserva de stock que evite sobreventa antes de que la actualización llegue al marketplace.

ERP + software vertical (SGA, TMS, firma digital)

Aquí la integración es frecuentemente entre sistemas propios o del mismo proveedor. Si el ERP y el SGA comparten el mismo fabricante, la integración suele ser por eventos internos o base de datos compartida. Si son de proveedores distintos, aplica todo lo anterior: OpenAPI, idempotencia y cola de mensajes. En Rowan Tech conectamos el ERP con el SGA y con el módulo de firma digital de albaranes desde el mismo stack, lo que elimina una capa entera de integración externa.

ERP + Verifactu

La interoperabilidad con el sistema Verifactu de la AEAT tiene requisitos técnicos propios: los registros de facturación deben enviarse en tiempo real, firmados con certificado electrónico y con hash encadenado. No es una integración opcional ni un módulo añadido: si tu ERP genera facturas, debe estar preparado para Verifactu. Más información sobre cómo lo abordamos en Rowan ERP y cumplimiento Verifactu.

TL;DR

• La interoperabilidad ERP real requiere acuerdo sobre la fuente de verdad de cada dato antes de escribir código.
• REST + OpenAPI 3.x + webhooks es la combinación más pragmática para integraciones ERP-ecommerce en 2024.
• Documenta el mapa de flujos, el glosario de campos y la política de errores antes de la primera conexión.
• Idempotencia, colas de mensajes y circuit breakers son los tres patrones que separan una integración robusta de una frágil.
• Verifactu no es opcional: cualquier ERP que emita facturas en España debe integrar este sistema desde el núcleo, no como parche.

Lecturas recomendadas

• Rowan ERP: ERP a medida para pymes españolas — Cómo está construido el núcleo de ERP que conectamos con sistemas externos.
• Rowan SGA: gestión de almacén con trazabilidad en tiempo real — Integración nativa entre ERP y SGA sin middleware adicional.
• Desarrollo de software a medida — Proyectos de integración desde cero cuando el software de catálogo no llega.