Ruta | Duración | Nivel | Antes de empezar |
🔴 Integración | 90 min | Avanzado | Eventos - que el proceso avance solo · Nociones de APIs REST y JSON · Un endpoint de pruebas (por ejemplo, un flujo de n8n o un servicio de captura de peticiones) |
Mairu rara vez vive solo: hay un ERP con los pedidos, un MES con las órdenes de fabricación, una GMAO con los equipos. Esta lección te enseña las tres vías para que la información entre y salga de Mairu, y los cuidados que exige cada una.
🎯 Al terminar sabrás
Elegir la vía de integración adecuada: importación, API o Webhook.
Cargar datos de forma masiva con la plantilla de importación.
Encontrar y probar los endpoints en el Centro para desarrolladores.
Registrar una API en Fuentes de datos y llamarla desde un evento Webhook.
Prever el efecto de una integración sobre los eventos del formulario.
🧠 La idea: quién inicia la conversación
Vía | Dirección | Quién la inicia | Cuándo usarla |
Importación | Entra | Una persona, puntualmente | Cargas iniciales, migraciones, maestros |
API de Mairu | Entra y sale | El otro sistema llama a Mairu | El ERP crea respuestas o tareas, sincroniza productos, usuarios o Assets |
Webhook | Sale (y puede recoger la respuesta) | Mairu llama al otro sistema, desde un evento, un botón o una automatización | Enviar un control NO OK al ERP, avisar a un flujo de n8n, pedir datos a otra aplicación |
⚠️ Lo que entra por API o por importación se comporta como una respuesta nueva. Los eventos del formulario se evalúan para cada respuesta creada o modificada. Una importación de 500 filas en un formulario con un evento de email puede generar 500 emails. Revisa siempre los eventos antes de integrar.
🛠️ Práctica guiada
Parte 1 · Importar controles históricos
En el histórico del Control de envasado, menú de tres puntos → Importar.
Descarga la plantilla. Usa la versión LibreOffice si quieres elegir los datos maestros con desplegables.
Rellena tres filas de prueba:
Deja el ID vacío: así se crea una respuesta nueva. Si pones el ID de una respuesta existente, la reemplazas.
Para los datos maestros usa el formato Referencia – Nombre (por ejemplo,
ENV-L1 – Línea 1) o el valor tal como se muestra en el formulario.Respeta el formato de fecha que indica la cabecera de cada columna.
Pon una de las filas con resultado NO OK.
4. Sube el archivo y pulsa Importar. La carga se hace en segundo plano; si hay errores, la ventana de progreso indica la fila y el problema.
Comprueba: las tres respuestas aparecen en el histórico y calidad.prueba ha recibido un email: el de la fila NO OK. Es el comportamiento esperado de los eventos.
💡 Los maestros también se importan: usuarios desde Configuración > Usuarios, productos desde Productos y valores de entidades desde cada Entidad.
Parte 2 · Explorar la API
En Overview localiza la URL base, el método de autenticación (token Bearer en la cabecera
Authorization) y la tabla de campos soportados para las respuestas.En Endpoints, abre la categoría Forms y elige la operación para crear una respuesta. Revisa el cuerpo esperado y el ejemplo.
Si tienes un token de pruebas, pégalo en el bloque Try it y crea una respuesta del Control de envasado. Copia el comando cURL para dárselo al equipo que hará la integración.
⚠️ El token permite leer y escribir los datos de tu organización. Solicítalo a soporte o al administrador de la cuenta y no lo compartas por canales no seguros.
Parte 3 · Enviar los NO OK a otro sistema con un Webhook
Registrar la API. En Configuración > Fuentes de datos, registra tu endpoint de pruebas: nombre, URL base y métodos.
Crear el evento. En el Control de envasado, pestaña Eventos:
Cuando:
Resultadoes igual aNO OK.Sucederá esto: Webhook → la API registrada, método POST, y la ruta concreta del endpoint.
3. Construir el cuerpo. En la pestaña Body, envía los datos del control insertando campos del formulario, por ejemplo:
{
"origen": "Mairu",
"tipo": "control_envasado_no_ok",
"linea": "{linea}",
"producto": "{producto}",
"lote": "{lote}",
"motivo": "{motivo_rechazo}"
}
4. Recoger la respuesta (opcional). Si el otro sistema devuelve, por ejemplo, un número de incidencia, puedes guardarlo en un campo del formulario desde la pestaña Respuesta del Webhook, indicando la "dirección" del dato (por ejemplo incidencia.numero).
Comprueba: guarda un control NO OK y verifica que la petición llega a tu endpoint con los datos del control.
⚠️ Errores habituales
Importar sin revisar los eventos. Es la causa más habitual de avalanchas de emails o de tareas planificadas por error.
Poner un ID en la plantilla sin querer. Esa fila sustituye a la respuesta existente con ese ID.
"La API no aparece en el Webhook." Primero hay que registrarla en Fuentes de datos.
**Usar Ejecutar prueba sobre llamadas que crean o borran datos. La prueba del mapeo de la respuesta es una llamada real** contra el otro sistema y no se puede deshacer.
Diseñar una integración masiva como si fuera manual. Si la API crea muchas respuestas, todas disparan sus eventos. Piensa qué acciones deben ejecutarse cuando la respuesta viene de otro sistema.
🏋️ Reto
El ERP quiere crear automáticamente una tarea de control en Mairu cada vez que arranca una orden de fabricación, con la línea, el producto y el lote ya rellenos. Con lo que has visto en el Centro para desarrolladores, escribe (sin programarlo) el diseño de la integración: qué endpoint usarías, qué datos enviaría el ERP, a quién se asignaría la tarea y qué eventos del Control de envasado se dispararían cuando el operario la complete.
📚 Para saber más
Cómo mapear la respuesta de un Webhook a los campos del formulario
➡️ Siguiente lección: Proyecto final - diseña un proceso completo