El día que quieras irte, tus datos salen enteros. Y lo que la API no hace, está por escrito.
Con un proveedor nuevo el miedo razonable es doble: que la API prometa lo que no tiene y que tus datos no salgan completos cuando los necesites. Aquí hay sincronización incremental para mantener otro sistema al día, exportación completa para llevártelo todo y una referencia que puedes leer sin clave antes de firmar nada.
Las integraciones fracasan por lo que se prometió y no estaba, no por lo que faltaba y se avisó. Por eso esta página empieza por la salida y termina por los límites.
Te llevas toda tu información, sin pedírsela a nadie.
Veintidós recursos: activos con sus fotografías y documentos, órdenes de trabajo con su expediente completo —tareas, personal, materiales, histórico de estados, adjuntos y firmas—, incidencias y lecturas.
No es una descarga instantánea, porque un volcado serio no cabe en una petición web. Se solicita, se consulta el progreso y se descarga cuando está listo, con una URL firmada con caducidad.
Solicitar
Indicas qué recursos, desde qué fecha, si se incluyen los borrados y si se empaquetan los ficheros. La generación arranca en el acto.
Seguir
Estado, progreso y recuento de filas, hasta que termina.
Descargar
URL firmada, válida una hora. El paquete permanece disponible siete días y después se purga solo.
Pedir un recurso para el que la clave no tiene permiso devuelve error, no un volcado recortado en silencio. Un paquete incompleto que el integrador cree completo es peor que un fallo.
Un ZIP que se explica a sí mismo.
Los datos van en NDJSON —un objeto JSON por línea, un fichero por recurso— y no en un único JSON gigante. Así puedes procesar el volcado en flujo, sin cargar en memoria un fichero que puede rondar el gigabyte.
Un manifiesto describe el paquete: versión del formato, fecha de generación —que es el punto de partida de la siguiente sincronización—, filtros aplicados, y por cada recurso su fichero, su número de filas, si admite lectura incremental y si informa de bajas.
Las fotografías y documentos van aparte, con su propio índice y el hash SHA-256 de cada fichero, de modo que la integridad se verifica uno a uno.
- Geometrías Siempre GeoJSON en EPSG:4326, reproyectadas por el servidor.
- Fechas e identificadores ISO 8601 y UUID en texto.
- Textos multilingües Aplanados al idioma que se pida.
- Auditoría Cada exportación deja registro de quién la pidió, desde qué IP, con qué filtros, cuántas filas y el hash del paquete. Un volcado completo lleva datos personales, así que la traza no es opcional.
Cuatro endpoints, con propósitos distintos.
Conviene no confundirlos: uno dice qué puedes leer, otro lee, otro mantiene al día y el último se lo lleva todo.
| Endpoint | Qué hace |
|---|---|
/resources | Devuelve el catálogo de lo que esa clave concreta puede leer, con sus límites declarados. |
/data/{recurso} | Lectura de cualquier recurso, paginada por cursor: activos, órdenes de trabajo y su expediente completo, incidencias, lecturas, fotografías y documentos. |
/sync | Sincronización incremental: lo cambiado desde una fecha, por entidad, indicando si cada registro es alta, modificación o baja. |
/exports | Volcado completo asíncrono de toda la organización. |
La paginación es por cursor y no por número de página. Sobre millones de activos, saltar por desplazamiento obliga a la base de datos a recorrer y descartar todo lo anterior en cada página.
Mantener otro sistema al día sin descargarlo todo cada noche.
La diferencia importa cuando el inventario tiene cien mil elementos. Un endpoint devuelve todo lo cambiado desde una fecha, por entidad, con paginación por cursor. Tu sistema guarda su marca de agua y en la siguiente pasada pide solo la diferencia.
Es lo que permite alimentar un cuadro de mando corporativo sin descargar la cartera completa cada noche.
La clave alcanza lo que se le concedió, y nada más.
Cada API key lleva su lista de scopes: assets:read, readings:read, readings:write, work_orders:read, issues:read, inventory:read, personnel:read, files:read y export:full.
Un scope concedido no basta: se valida además contra los módulos que la organización tiene contratados, con la misma comprobación que gobierna los permisos de un usuario en la web. Una clave con readings:read sobre una organización sin módulo de lecturas recibe un error explícito, no una lista vacía.
Cuota de 120 peticiones por minuto y clave, y 10 en los endpoints de exportación, con las cabeceras estándar de límite y el tiempo de espera en la respuesta.
Identidad de máquina, sin usuario asociado.
- Claves con prefijo propio Identificables a simple vista en un log o en una configuración.
- Caducidad Cada clave lleva su fecha de expiración.
- Scopes La clave solo alcanza las entidades y verbos que se le concedieron.
- Gestión desde la aplicación Alta, revocación y consulta, con los permisos de configuración.
Lo que la API no hace, antes de que lo descubras tú.
La API no crea ni modifica órdenes de trabajo: se leen, con su expediente completo, pero no se escriben desde fuera. Y no hay eventos salientes: la integración es por consulta, con sincronización incremental.
Cada recurso publica además dos banderas, en la propia API y en el manifiesto del paquete. Si admite lectura incremental: hay recursos sin marca de modificación, en los que el filtro por fecha no acota y se exportan completos. Y si informa de bajas: solo los recursos con borrado lógico pueden decir que algo desapareció.
Publicar esos límites en lugar de esconderlos es deliberado: evita que alguien construya una réplica con huecos creyéndola al día.
Solo se admite una exportación activa por organización. La segunda petición recibe un error con el identificador de la que está en curso.
Cuando el inventario vive en otro sistema.
Maptainer puede conectarse a APIs REST externas para importar un inventario que vive en otro sitio y mantenerlo actualizado. Es la vía si ya tienes un sistema de patrimonio y no quieres duplicar la fuente de verdad.
Swagger y ReDoc, accesibles sin clave.
La referencia de la API pública es su propia documentación, generada del código y navegable sin credenciales. Puedes revisarla entera antes de firmar nada.
Preguntas frecuentes
¿Puedo crear o modificar órdenes de trabajo por API?
¿El sistema avisa a mis aplicaciones cuando algo cambia?
¿Puedo llevarme todos mis datos?
Última actualización:
La referencia está abierta, y el funcional también.
Tu equipo puede revisarlos antes de la sesión de evaluación. Si después queda una pregunta técnica, te responde quien desarrolla el producto.