Un canal nuevo no debería crear una integración nueva con el ERP

El caso práctico

El punto de partida fue un flujo capaz de leer pedidos recibidos por correo. El diseño también debía permitir que otros canales enviaran órdenes sin copiar la lógica de creación ni conocer las estructuras internas del ERP.

Las decisiones confirmadas fueron:

El propósito no es convertir la API en otro nombre para la misma interfaz del ERP. Es definir un contrato de negocio estable y lo bastante pequeño para representar una solicitud de pedido, mientras los adaptadores resuelven las diferencias de cada origen.

• El canal de correo usa un bot para interpretar el contenido recibido.
• Los datos pasan por homologación antes de crear el pedido.
• La creación se expone mediante una API para que otros canales puedan reutilizar el mismo ingreso.
• El ERP permanece detrás de una frontera controlada; los canales no dependen directamente de sus estructuras internas.

1. Cada canal conoce su propio formato

El bot entiende el correo. Una aplicación entiende su formulario. Un canal futuro conocerá su propio mecanismo de captura. Ninguno debería tener que saber qué tabla, función o estructura interna utiliza el ERP.

2. Los adaptadores traducen, no gobiernan el negocio

El adaptador transforma el contenido del canal a un modelo común. También puede identificar datos faltantes o formatos inválidos, pero las reglas compartidas no deberían quedar duplicadas en cada adaptador.

3. La API canónica representa la intención de negocio

El contrato común expresa “registrar una solicitud de pedido” con campos, estados y errores entendibles para cualquier consumidor autorizado. OpenAPI permite documentar esa interfaz de forma independiente del lenguaje de programación y hacer explícitas sus capacidades y restricciones.

Un modelo canónico añade una capa de traducción, pero evita que cada aplicación necesite conocer todos los demás formatos. El patrón no exige crear un objeto empresarial gigantesco: conviene limitarlo al contexto concreto de pedidos.

4. La homologación ocurre antes de comprometer el ERP

Clientes, productos, unidades o condiciones pueden llegar con identificadores distintos. La homologación debe resolver esas equivalencias y dejar visible lo que no pudo relacionarse. Rechazar o derivar una solicitud incompleta antes de crearla protege la calidad del dato y evita trasladar ambigüedad al sistema central.

5. La creación del pedido tiene un único límite de responsabilidad

Solo el componente de integración autorizado convierte una solicitud validada en una operación sobre el ERP. Esta capa funciona como una frontera anticorrupción: traduce entre modelos con semánticas diferentes y evita que la evolución de los canales quede condicionada por el modelo interno del sistema legado.

Controles que deben validarse antes de producción

Estos controles son recomendaciones de diseño; no afirmaciones sobre una implementación específica:

• Contrato y versión: esquema documentado, campos obligatorios, compatibilidad y política de cambios.
• Identidad y autorización: cada consumidor debe autenticarse y acceder únicamente a las operaciones y datos permitidos.
• Idempotencia: un reintento no debe crear dos pedidos. Una clave estable permite reconocer la misma solicitud recibida más de una vez.
• Errores utilizables: el consumidor necesita distinguir una validación de negocio, un dato sin homologar y una falla temporal. RFC 9457 ofrece una estructura estándar para describir problemas en APIs HTTP.
• Correlación y trazabilidad: un identificador debe acompañar el recorrido desde el canal hasta el resultado final. Las prácticas de trazas distribuidas permiten correlacionar lo ocurrido entre componentes.
• Reintentos controlados: solo las fallas transitorias deben reintentarse; los errores de datos requieren corrección o intervención.
• Conciliación: debe ser posible comparar solicitudes recibidas, aceptadas, rechazadas y creadas en el ERP.
• Observabilidad: métricas, logs y alertas deben mostrar volumen, latencia, errores y acumulaciones sin exponer información sensible.

Riesgos y compensaciones

La capa común no elimina la complejidad: la concentra en un lugar que necesita propietario, versionado, pruebas y monitoreo. Un contrato mal diseñado puede convertirse en un cuello de botella; uno demasiado cercano al ERP vuelve a crear el acoplamiento que se buscaba evitar.

También es necesario decidir qué debe ser síncrono y qué puede resolverse de forma diferida. La respuesta inmediata puede confirmar que la solicitud fue recibida, mientras la creación final requiere validación, homologación o recuperación ante indisponibilidad. Esa diferencia debe expresarse mediante estados claros, no ocultarse al consumidor.

Cómo evaluaría el diseño

Antes de ampliar el número de canales, probaría el flujo con escenarios verificables:

Las métricas útiles no son solo técnicas: porcentaje aceptado al primer intento, solicitudes pendientes de homologación, duplicados evitados, tiempo hasta el resultado final y capacidad de explicar cada estado.

• 1. Pedido válido desde correo y desde un segundo canal.
• 2. Reenvío de la misma solicitud sin duplicar el pedido.
• 3. Cliente o producto sin homologación.
• 4. Datos incompletos o con formato inválido.
• 5. Indisponibilidad temporal del ERP y recuperación posterior.
• 6. Seguimiento completo mediante un identificador de correlación.
• 7. Conciliación entre solicitudes recibidas y pedidos creados.

Conclusión accionable

Cuando aparece un canal nuevo, la primera pregunta no debería ser “¿cómo lo conectamos al ERP?”, sino “¿qué contrato de negocio puede reutilizar sin conocer el ERP?”.

Una API canónica, adaptadores por canal y una frontera controlada permiten incorporar nuevos orígenes sin multiplicar el acoplamiento. El valor no está en esconder el sistema central detrás de otra flecha, sino en hacer explícitas las responsabilidades, los estados y los controles que protegen la operación.