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 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
- Reúnete con quien mantiene el ERP y rellenad juntos la hoja de mapeo.
- 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.
- Crea un webhook con la dirección que te dé el integrador y los eventos que necesite el ERP.
- Dale al integrador la clave y el secreto del webhook. Los dos se ven una sola vez: cópialos al crearlos.
- 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.
- Para pasar a producción, crea una clave y un webhook nuevos. Los de pruebas no se reutilizan.
- La primera semana, mira cada día las Entregas del webhook.
La clave del ERP
- En API y copias de datos, pulsa Nueva clave.
- Escribe el Nombre, por ejemplo «SAP PM».
- Marca Alta de incidencias. Marca también Órdenes de trabajo si el ERP tiene que leer horas y materiales.
- Si el ERP es de un cliente, elígelo en Solo de un cliente. Esa clave solo puede llevar Alta de incidencias.
- Pulsa Crear clave, pulsa Copiar y dásela al integrador.

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
- En la tarjeta Webhooks, pulsa Nuevo webhook.
- Escribe el Nombre y pega la URL de destino (https) que te dé el integrador.
- Si solo quieres los cambios de un cliente, elígelo en Cliente.
- Marca los Eventos. Para cerrar los avisos del ERP suelen bastar Orden de trabajo cerrada, Incidencia cerrada e Incidencia rechazada.
- Pulsa Crear webhook, copia el secreto y dáselo al integrador.
- Pulsa Probar: Maptainer envía un aviso de prueba y enseña lo que ha contestado el ERP.


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.

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: