Integraciones B2B en Magento 2: Profiles, Mappings y control de sincronización en B2B Suite
Integrar Magento 2 con ERP, PIM, WMS o CRM exige más que enviar datos a una API. Hay que identificar la empresa, vincular identificadores, comprobar resultados y gestionar mensajes rechazados. En B2B, esto determina si el pedido llega a preparación, el cliente se reconoce correctamente y la tarifa acordada alcanza el canal adecuado.
Integrations en Kowal B2B Suite organiza ese trabajo en cinco áreas: Profiles, Mappings, Sync Jobs, Dead Letter Queue y Sync Errors. Explicamos su funcionamiento y aplicación diaria.
La descripción corresponde a la implementación revisada en noviembre de 2026. Los ejemplos son ilustrativos y suponen un adaptador desplegado para el sistema y la operación indicados.
¿Qué proporciona Integrations y qué hace el adaptador?
Integrations aporta infraestructura común: perfiles, asociaciones de identificadores, registro de tareas, control de intentos, resultados e historial de errores. Un adaptador realiza la conexión concreta con ERP, PIM, WMS o CRM y conoce su API y reglas de intercambio.
El adaptador define autenticación, formatos de mensajes, transformación de campos y ejecución. Elegir «ERP» describe la finalidad del perfil; no instala automáticamente una conexión con cualquier ERP.
Guardar una tarea solo registra trabajo pendiente. El formulario no inicia un proceso periódico en segundo plano. El procesamiento y la selección de tareas deben conectarse durante la implantación, por ejemplo mediante un ejecutor, planificador o middleware que use la lógica y API disponibles.
Cinco pantallas, cinco preguntas concretas
| Pantalla | ¿Qué pregunta responde? | Aplicación |
|---|---|---|
| Profiles | ¿Con qué sistema, canal y configuración trabajamos? | Configurar un perfil ERP para un website |
| Mappings | ¿Qué registro Magento corresponde al registro externo? | Vincular una empresa B2B con su ficha ERP |
| Sync Jobs | ¿Qué debe ejecutarse y cuál es el resultado actual? | Controlar exportaciones de pedidos o importaciones |
| Dead Letter Queue | ¿Qué tareas agotaron sus intentos? | Operaciones que requieren intervención |
| Sync Errors | ¿Qué falló y en qué tarea? | Analizar errores con perfil, website e intentos |
Estas áreas describen el mismo proceso desde perspectivas distintas: el perfil define el contexto, las asociaciones conectan registros, la tarea representa la operación y las últimas vistas ayudan a gestionar fallos.
Profiles: configurar la integración para el website correcto
En B2B > Integrations > Profiles creas y editas perfiles. Cada uno pertenece a un website Magento con B2B activo. Así se separan canales nacionales y de exportación cuando funcionan en websites distintos.
Website es aquí la unidad organizativa del canal Magento. Varias vistas lingüísticas dentro del mismo website no implican varias integraciones independientes.
| Campo del perfil | Significado | Ejemplo |
|---|---|---|
| Website | Canal comercial del perfil | Website mayorista |
| Code y Name | Código único en el website y nombre legible | erp_orders, «Pedidos al ERP» |
| System Type | Tipo de sistema: ERP, PIM, WMS o CRM | ERP |
| Adapter Code | Identificador del adaptador de conexión | Código acordado con el integrador |
| Direction | Import, Export o Bidirectional | Export para enviar pedidos |
| Active | Actividad del perfil; las tareas nuevas usan perfiles activos | Activo tras configurar |
| Max Attempts | Límite predeterminado de intentos | 3 intentos |
| Config JSON | Configuración interpretada por el adaptador | Parámetros de entorno y referencia a credenciales |
Config JSON no tiene campos universales para todas las integraciones. El adaptador interpreta sus claves. El formulario valida JSON, pero no sustituye una prueba de conexión. Conviene referenciar una configuración segura para las credenciales, según las exigencias del adaptador.
El integrador utiliza un perfil con nombre en lugar de repetir parámetros ERP en scripts separados. El operador identifica sistema y dirección del proceso.
Mappings: vincular identificadores Magento y externos
Una empresa puede tener ID 42 en B2B Suite y código ERP-C-0084 en ERP. Una persona reconoce al mismo cliente; la integración necesita un vínculo explícito para leer o actualizar la ficha correcta.
Mappings guarda website, tipo de sistema, entidad, ID local, ID externo y metadatos JSON opcionales. La interfaz contempla empresas, clientes, productos, categorías, listas de precios, pedidos, RFQ y documentos.
| Tipo de entidad | Local ID | External ID | Significado |
|---|---|---|---|
| Company | 42 | ERP-C-0084 | Empresa B2B vinculada a una ficha de cliente ERP |
| Price List | 7 | ERP-PRICELIST-DEALERS | Lista Magento vinculada a condiciones comerciales |
| Order | 12345 | ERP-SO-92018 | Pedido con documento ERP asociado |
Los valores son ejemplos. El adaptador determina cómo representa el identificador local de cada entidad. Las asociaciones se consultan por ID local o externo.
Mappings relaciona identidades de registros; no es un editor visual de transformación de campos. Reglas como «el nombre del cliente ERP pasa al campo company de Magento» pertenecen al adaptador. Guardar una asociación tampoco descarga datos ni sincroniza por sí solo.
El contexto incluye website, tipo de sistema y entidad, no exclusivamente un perfil. Si hay varias conexiones del mismo tipo en un website, el integrador debe planificar una identificación coherente. La base de datos exige unicidad tanto del ID local como del externo en ese contexto.
Sync Jobs: registrar trabajo y seguir la sincronización
Un Sync Job representa una operación, como enviar un pedido a ERP. En Schedule Sync Job eliges perfil activo, entidad y operación. Puedes indicar dirección, entrada JSON, clave de idempotencia, límite de intentos y fecha programada. Si no se cambia, la dirección procede del perfil.
El adaptador debe comprender la entidad y el nombre de operación. export_order puede formar parte de la solución acordada, pero escribirlo no implementa una exportación.
View muestra resumen, entrada, resultado del adaptador, registros y errores. Permite revisar website, perfil, dirección, entidad, operación, intentos, clave de idempotencia y horas de programación, inicio y fin.
| Estado | Significado en el mecanismo |
|---|---|
pending | Tarea guardada y pendiente de procesamiento |
running | Intento iniciado y contador incrementado |
success | Adaptador finalizado sin excepción y resultado guardado |
failed | Falló el adaptador, pero quedan intentos |
retry | Tarea existente programada de nuevo |
dead | El fallo agotó el límite; tarea visible en Dead Letter Queue |
Interpreta success según el contrato del adaptador. Si la API externa solo acepta mensajes para procesarlos después, acuerda si el resultado significa recepción o finalización confirmada de la operación comercial.
La fecha programada informa al ejecutor. Establecerla no sustituye el proceso de ejecución ni sus reglas para seleccionar tareas listas.
Idempotencia: limitar tareas duplicadas
Tras una desconexión, el middleware puede volver a enviar la misma operación. Una clave de idempotencia permite reconocer la tarea. Publicar con la misma clave en el mismo website devuelve el registro existente en lugar de crear otro.
La clave debe identificar una operación comercial concreta, por ejemplo exportar una versión de un pedido. Es común al website: incluye un contexto reconocible de sistema y operación. Reutilizar una clave antigua no actualiza la entrada de la tarea existente.
Esto evita registros duplicados de tareas. Prevenir efectos repetidos en ERP, como un segundo documento tras una respuesta incierta, también requiere medidas en el adaptador y la API externa.
Dead Letter Queue: tareas que necesitan una decisión
Dead Letter Queue muestra tareas dead. Es una vista de los mismos registros, no otra copia de los mensajes. Separa operaciones que no terminaron dentro del límite de intentos.
Con un máximo de tres, la tercera ejecución fallida del adaptador establece dead. No significa que el módulo lance tres intentos seguidos automáticamente. Las ejecuciones y sus intervalos dependen del mecanismo de reintentos y del ejecutor implantados.
El operador abre la tarea, investiga y corrige la causa, por ejemplo una asociación de cliente ausente o la conexión. Después puede utilizar Retry Job.
El reintento está disponible para failed y dead. No crea otra tarea ni reinicia el historial de intentos. Establece retry, programa el momento actual y borra las horas anteriores de inicio y fin. Si se agotó el límite, lo amplía para permitir un intento más. El adaptador se ejecuta al procesar posteriormente la tarea.
Sync Errors: historial de errores con contexto
Sync Errors muestra errores de ejecución del adaptador: código, mensaje, hora y posibilidad de reintento. La lista los vincula al contexto actual de tarea, perfil y website. Así se distingue un problema individual de un fallo general de conexión.
Los detalles incluyen errores y registros técnicos asociados, como inicio, finalización y programación de reintentos. Los datos de error guardan también una traza útil al integrador.
Una tarea puede acumular varios errores de intentos sucesivos. Su número no equivale al de operaciones pendientes. Una tarea que luego termina correctamente puede conservar errores anteriores.
Retryable depende aquí de los intentos restantes al producirse el error. No identifica automáticamente una causa temporal. Un ID incorrecto no se corrige solo por repetir, aunque queden intentos.
La diferencia principal: Sync Errors permite analizar causas; Dead Letter Queue reúne tareas con intentos agotados.
Escenario 1: vincular una empresa B2B con su cliente ERP
Alfa tiene cuenta Magento y una ficha ERP existente. El equipo quiere evitar duplicar al cliente.
- El integrador prepara el adaptador ERP y el perfil del website correcto.
- Mappings vincula la empresa
42conERP-C-0084. - La tarea del adaptador usa la asociación para dirigirse al registro existente.
- El operador comprueba resultado e identificadores devueltos en Sync Jobs.
Se obtiene una identidad de cliente coherente. Los campos actualizados y el sistema que los gobierna forman parte del alcance acordado.
Escenario 2: un pedido B2B llega al ERP tras una interrupción
El cliente compra y el mecanismo implantado crea la tarea de exportación. ERP está temporalmente inaccesible. El adaptador falla, se registra el error y la tarea recibe failed o, tras agotar intentos, dead.
Restablecida la conexión, el operador revisa la ejecución anterior en ERP y programa Retry de la misma tarea. El adaptador debe reconocer documentos existentes para evitar duplicarlos si la primera petición se aceptó pese a perderse la respuesta.
Tras completarse, el resultado puede incluir el ID del documento ERP y el adaptador puede guardar una asociación. Su contenido y momento dependen de la implementación.
Escenario 3: actualizar la tarifa del canal B2B correcto
ERP es la fuente de condiciones comerciales. El canal mayorista dispone de perfil de importación y una asociación de la lista 7 con ERP-PRICELIST-DEALERS.
El adaptador lee ERP, comprueba SKU, moneda y tramos y guarda según las reglas de Pricing. Sync Job sigue la operación y el resultado puede resumir entradas procesadas. Ante problemas, el operador dispone de contexto y mensaje.
Integrations controla el flujo; Pricing elige el precio. Lo explicamos en listas B2B y Price List en Magento 2. El adaptador debe definir validaciones, escrituras parciales y actualización del índice.
Escenario 4: un error recurrente exige corregir datos
El almacén rechaza una operación porque no reconoce un producto. Repetir no cambia nada. La tarea agota intentos y aparece en Dead Letter Queue.
El operador abre View Job, lee el mensaje y comprueba ID. Si falta un vínculo, corrige Mappings. Tras resolverlo, elige Retry Job y revisa el resultado siguiente.
Esto demuestra la necesidad de asociaciones e historial. La cola permite volver a la operación; el diagnóstico señala qué corregir antes del nuevo intento.
Implantar Integrations paso a paso
- Elige el primer proceso. Por ejemplo, exportar pedidos antes de conectar todas las áreas.
- Establece las fuentes. Decide qué sistema gobierna cliente, tarifas o estado y cómo resolver conflictos.
- Prepara adaptador y ejecutor. Define operaciones, formatos, autenticación, ejecución y reintentos.
- Configura Profiles y Mappings. Comprueba website, dirección e ID con casos reales.
- Prueba éxitos y fallos. Incluye API inaccesible, datos inválidos, solicitudes repetidas e intentos agotados.
- Verifica el resultado comercial. Confirma el registro de destino además del estado.
- Asigna responsabilidades. Decide quién revisa Sync Errors y Dead Letter Queue y corrige datos o conexiones.
Así evalúas operaciones correctas y tiempo de resolución, no solo la existencia de una conexión API.
Preguntas frecuentes sobre Integrations en B2B Suite
¿Un perfil ERP ofrece integración lista para cualquier ERP?
No. Guarda contexto y configuración. Un adaptador específico para la API y los procesos acordados realiza la comunicación.
¿Mappings asocia campos de importación?
Vincula identificadores locales y externos. Las transformaciones de campos y formatos corresponden al adaptador.
¿Retry envía datos inmediatamente?
No. Reprograma la tarea existente. Los datos se envían o reciben en la siguiente ejecución del proceso conectado.
¿En qué difieren Dead Letter Queue y Sync Errors?
La primera muestra tareas dead; la segunda, errores con contexto. El historial puede conservar errores de operaciones posteriormente correctas.
¿El módulo reintenta automáticamente cada pocos minutos?
Guarda fechas, estados y contadores y permite reintentos. Calendario, intervalos y selección automática deben configurarse en la solución ejecutora.
¿Puede gestionarse por API?
La API B2B Suite permite gestionar perfiles y asociaciones, publicar, procesar y reintentar tareas y consultar tareas, registros y errores. Requiere permisos de integración y contexto de website cuando corresponda.
Integración B2B bajo control del equipo
Profiles organiza configuración, Mappings identidades, Sync Jobs progreso y Dead Letter Queue y Sync Errors fallos. Juntos forman una base ampliable para integrar Magento 2 con sistemas internos mediante adaptadores adecuados.
Consulta Kowal B2B Suite para Magento 2 Open Source o cuéntanos qué proceso quieres conectar a ERP, PIM, WMS o CRM. Basta empezar con sistema, dirección y una operación hoy manual.
Lee también: reducir la gestión manual de ventas B2B y el coste de gestionar pedidos B2B manualmente.