Introducción

Ni Maptainer se adapta a la estructura de cada ERP ni el ERP a la de Maptainer. Cada uno publica cómo habla, y en medio hay una capa de integración que traduce: la monta el consultor o el informático que mantiene el ERP, con una herramienta como SAP Integration Suite, Power Automate o un programa propio.

La capa de integración traduce en los dos sentidosERP del clienteSAP PM, Business Central…Capa de integraciónSAP CPI, Power Automate, n8n…MaptainerClave de API y webhooksAviso nuevonº, prioridad, equipoTraduce los códigosy da de alta sin duplicarIncidencia pendienteorigen Integración (API)Cierra el avisocon su número de avisoComprueba la firmay busca la referenciaAviso firmadoOT cerrada, incidencia…Imputa costeshoras y materialLee en lotey agrupa por OTDatos para leerhoras, material, réplica
Un flujo de ida (avisos del ERP) y dos de vuelta (cambios y costes).

La integración tiene tres piezas. Todas se configuran en el administrador → API y copias de datos.

Pieza Sentido Para qué
Alta de incidencias ERP → Maptainer Un aviso de avería del ERP entra en Maptainer como incidencia
Webhooks Maptainer → ERP Maptainer avisa al momento cuando cambia una orden de trabajo o una incidencia
Lectura de datos Maptainer → ERP El ERP lee horas, materiales y catálogos para imputar costes o tener una copia

Requisitos previos

  • El módulo de mantenimiento contratado: las incidencias y las órdenes de trabajo dependen de él.
  • Ser administrador de la organización. Las claves y los webhooks no se delegan por rol.
  • Alguien que configure el lado del ERP: el consultor o el informático del cliente. Necesita una dirección https:// donde recibir los avisos.
  • Un entorno de pruebas del ERP. Avantgeo puede preparar una organización de pruebas en Maptainer; se pide a soporte.

Quién manda en cada dato

Antes de empezar, decide qué sistema es el dueño de cada dato. Si los dos pueden cambiar lo mismo, gana el último que escribe y el otro no se entera. Esta es la propuesta habitual:

Dato Manda El otro sistema…
Que existe una avería o un aviso ERP Maptainer lo recibe como incidencia y guarda el número de aviso
Planificación, asignación de operarios y rutas Maptainer El ERP no lo toca
Ejecución: estados, horas, fotos, formularios y firma Maptainer El ERP lo recibe por webhook y lo lee
Cierre del aviso Maptainer avisa, el ERP cierra El ERP cierra el aviso cuando le llega el cierre
Costes y facturación ERP Lee de Maptainer las horas y el material consumido
Datos contables del activo (nº de inventario, centro de coste) ERP En Maptainer van como campo del activo, si hacen falta
Ubicación y geometría de los activos Maptainer El ERP no lo toca

Preparar la integración

  1. Reúnete con quien mantiene el ERP y rellenad juntos la hoja de mapeo.
  2. Crea una clave de API para el ERP con el permiso Alta de incidencias (ver más abajo). Si el ERP es de un cliente, limita la clave a ese cliente.
  3. Crea un webhook con la dirección que te dé el integrador y los eventos que necesite el ERP.
  4. Dale al integrador la clave y el secreto del webhook. Los dos se ven una sola vez: cópialos al crearlos.
  5. Probad en el entorno de pruebas: un alta normal, el mismo aviso enviado dos veces, un código desconocido y el cierre de una orden de trabajo.
  6. Para pasar a producción, crea una clave y un webhook nuevos. Los de pruebas no se reutilizan.
  7. La primera semana, mira cada día las Entregas del webhook.

La clave del ERP

  1. En API y copias de datos, pulsa Nueva clave.
  2. Escribe el Nombre, por ejemplo «SAP PM».
  3. Marca Alta de incidencias. Marca también Órdenes de trabajo si el ERP tiene que leer horas y materiales.
  4. Si el ERP es de un cliente, elígelo en Solo de un cliente. Esa clave solo puede llevar Alta de incidencias.
  5. Pulsa Crear clave, pulsa Copiar y dásela al integrador.
El formulario de nueva clave con el permiso «Alta de incidencias» marcado y un cliente elegido en «Solo de un cliente».
El formulario de nueva clave con el permiso «Alta de incidencias» marcado y un cliente elegido en «Solo de un cliente».

Una clave de un solo cliente da de alta las incidencias siempre a nombre de ese cliente y solo con sus activos. Tampoco ve las incidencias de los demás clientes. El resto de opciones de las claves está en Crear una clave de API.

El webhook

  1. En la tarjeta Webhooks, pulsa Nuevo webhook.
  2. Escribe el Nombre y pega la URL de destino (https) que te dé el integrador.
  3. Si solo quieres los cambios de un cliente, elígelo en Cliente.
  4. Marca los Eventos. Para cerrar los avisos del ERP suelen bastar Orden de trabajo cerrada, Incidencia cerrada e Incidencia rechazada.
  5. Pulsa Crear webhook, copia el secreto y dáselo al integrador.
  6. Pulsa Probar: Maptainer envía un aviso de prueba y enseña lo que ha contestado el ERP.
La tarjeta Webhooks de la pantalla API y copias de datos, todavía sin webhooks.
La tarjeta Webhooks de la pantalla API y copias de datos, todavía sin webhooks.
El formulario de nuevo webhook con la URL de destino y tres eventos marcados.
El formulario de nuevo webhook con la URL de destino y tres eventos marcados.

Las entregas, los reintentos, la rotación del secreto y qué pasa si el ERP deja de contestar están en Webhooks y Entregas, reintentos y desactivación.

Cómo entran los avisos del ERP

Un aviso del ERP entra como incidencia pendiente, con Integración (API) en Origen/Canal. Desde ahí sigue el camino de cualquier otra: se revisa, se convierte en orden de trabajo y se cierra. Se le aplican el SLA del cliente, la delegación del sector y los avisos de siempre.

  • El tipo, la criticidad y los activos llegan por su código. Por eso conviene que el código de cada activo en Maptainer sea el mismo que en el ERP.
  • El número de aviso del ERP se guarda con la incidencia. Maptainer no deja dar de alta dos incidencias con el mismo número.
  • Sin duplicados: si la conexión falla y el ERP repite el envío, no se crea otra incidencia.
  • Sin activo: el ERP puede mandar una dirección o unas coordenadas.

Limitación actual

El número de aviso del ERP no se ve en la ficha de la incidencia: lo guarda Maptainer y viaja en los webhooks. Cómo evitarlo: que el ERP lo ponga también al principio del título.

Cómo vuelven los cambios al ERP

Cada vez que pasa algo que el webhook tiene marcado, Maptainer envía un aviso al ERP en segundos. El aviso de una orden de trabajo lleva las incidencias que resuelve, con su número de aviso del ERP: así el ERP sabe qué aviso cerrar.

Evento Uso habitual en el ERP
Orden de trabajo cerrada Cerrar el aviso e imputar horas y material
Orden de trabajo completada o validada Marcar el aviso como terminado, si el cliente cierra más tarde
Incidencia cerrada o resuelta directamente Cerrar el aviso cuando no hizo falta orden de trabajo
Incidencia rechazada Cerrar el aviso como «no procede»
Incidencia aprobada (con OT) Poner el aviso «en tratamiento»
Medición confirmada o anulada Registrar la cantidad medida (kilos, litros, horas) o retirarla. Ver Mediciones
Entrega a un tercero registrada Registrar la salida hacia el gestor o la planta, con su albarán

Si el ERP no contesta, Maptainer lo vuelve a intentar durante casi dos días. Si en 3 días no acepta ningún aviso, el webhook se desactiva solo y los administradores reciben un correo.

Equivalencias con SAP PM y Business Central

Las tablas de cada ERP son distintas, pero los conceptos coinciden. Los nombres técnicos son orientativos: el integrador los confirma en la instalación del cliente.

Maptainer SAP PM Business Central
Incidencia Aviso de mantenimiento (clases M1 y M2) No viene de serie. Con el módulo de Servicio, una línea de pedido de servicio
Orden de trabajo Orden de mantenimiento Pedido de servicio, con el módulo de Servicio; si no, un proyecto
Activo Equipo o ubicación técnica Activo fijo o artículo de servicio
Tipo de incidencia Clase de aviso o código de daño —
Criticidad Prioridad: 1 Crítica, 2 Alta, 3 Media, 4 Baja Prioridad del pedido de servicio
Tipo de mantenimiento Clase de orden y clase de actividad Tipo de pedido de servicio o tarea de proyecto
Cliente Deudor Cliente
Delegación Centro de planificación Dimensión o almacén
Artículo y almacén Material y almacén del centro Producto y almacén
Horas de una orden Notificación de tiempos Diario de proyecto o línea de servicio
Material consumido Salida de material a la orden Diario de producto o línea de servicio

Los estados se traducen así (propuesta, que se ajusta en la hoja de mapeo):

Maptainer SAP PM
Incidencia pendiente Aviso pendiente
Incidencia aprobada Aviso en tratamiento
Incidencia resuelta o cerrada Aviso concluido
Incidencia rechazada Aviso concluido con motivo de rechazo
Orden pendiente Orden abierta
Orden en curso o en pausa Orden liberada
Orden completada Orden liberada con notificación final
Orden validada o cerrada Cierre técnico (y cierre tras la liquidación)
Orden cancelada Petición de borrado o cierre sin coste

Hoja de mapeo

Se rellena con el cliente en la primera reunión. Cada respuesta es una decisión que el integrador necesita para programar.

# Decisión Propuesta
1 Qué flujos: avisos a incidencias, cierres al ERP, costes al ERP, copia de datos
2 Qué clases de aviso del ERP se mandan a Maptainer
3 Equivalencia de cada clase de aviso o código de daño con un tipo de incidencia Una fila por valor
4 Equivalencia de prioridades y criticidades 1 Crítica, 2 Alta, 3 Media, 4 Baja
5 Si el código de los activos es el mismo en los dos sistemas Que lo sea
6 Equivalencia de los clientes
7 Una clave para toda la empresa o una por cliente Una por cliente si cada uno tiene su ERP
8 Qué evento cierra el aviso Orden de trabajo cerrada
9 Si se imputan horas y material, y a qué: la orden, el aviso o un proyecto
10 Tarifa o centro de coste de las horas
11 Dirección del webhook y quién guarda el secreto
12 Quién recibe el correo si el webhook se desactiva Los administradores de Maptainer
13 Entornos de prueba de los dos sistemas

Para quien programa la integración

Todo lo técnico está en Referencia de la API, arriba a la derecha de API y copias de datos: cada llamada, el cuerpo de cada webhook y cómo se comprueba su firma.

La referencia de la API con las llamadas para dar de alta y consultar incidencias.
La referencia de la API con las llamadas para dar de alta y consultar incidencias.

Lo esencial, para la primera conversación con el integrador:

Tema Cómo funciona
Alta de un aviso POST /issues con la clave en la cabecera X-API-Key. Tipo, criticidad y activos por código; los códigos salen de GET /issues/catalog
Número de aviso Campo external_ref. Un segundo alta con el mismo número se rechaza y dice qué incidencia existe
Reintentos sin duplicar Cabecera Idempotency-Key, una por aviso: repetir la llamada en 24 horas devuelve la misma respuesta
Webhooks Firma según el estándar Standard Webhooks. Hay que contestar 2xx en menos de 10 segundos; cada aviso trae un identificador para descartar repetidos
Horas y material En el propio aviso de cierre (tiempo activo total, inicio y fin reales) y en la lectura de datos de la orden
Evitar bucles Cada aviso dice si el cambio lo hizo una clave de la API, para no reenviar el eco de sus propias altas
Cuotas 120 lecturas y 60 altas por minuto y clave

Limitaciones actuales

  • Por la API solo se dan de alta incidencias: el ERP no puede crear órdenes de trabajo ni cambiar o cancelar incidencias ya creadas.
  • Los webhooks avisan de órdenes de trabajo e incidencias; de activos, stock o lecturas, no.
  • Las horas y el material de una orden no se pueden pedir sueltos: se leen en lote.
  • La API da horas y cantidades, no importes: el ERP valora con sus tarifas.
  • El número de aviso del ERP no se ve en la ficha de la incidencia.

Problemas frecuentes

Síntoma Causa probable Solución
El webhook sale como Desactivado El ERP no aceptó ningún aviso en 3 días Cuando el ERP funcione, pulsa Activar y reenvía lo pendiente desde Entregas
Probar dice que el certificado no es válido El servidor del integrador tiene un certificado caducado o propio El integrador tiene que poner un certificado válido
No deja guardar la URL del webhook No empieza por https:// o apunta a una dirección interna Pide al integrador una dirección pública con https
El ERP dice que el aviso ya existe Ya hay una incidencia con ese número de aviso Es correcto: la incidencia ya estaba. El integrador debe tomarla como creada
El ERP dice que un código de activo es ambiguo Varios activos de Maptainer comparten ese código Corrige los códigos repetidos o pide al integrador que use el identificador del activo
El ERP no puede leer horas con su clave La clave solo tiene Alta de incidencias Crea otra clave con Órdenes de trabajo: los permisos de una clave no se cambian. Una clave de un solo cliente no puede leer

Última actualización: