API REST

La API REST permite que tu propio software lea y cambie lo que hay en tu cuenta de Measure Map Online: los proyectos y sus mediciones, las carpetas, el catálogo de productos y, en Enterprise, los miembros de tu organización. Responde en JSON. La referencia completa, con todos los campos y ejemplos, es la documentación de la API; esta página es la visión general.

Para abrir la documentación desde la aplicación, ve a codeDesarrollador > apiAPI REST y pulsa menu_bookConsultar documentación.

URL base#

Todas las solicitudes van a:

https://api.measuremaponline.com/api/v2

Autenticación#

Envía tu clave de API, tal cual, en la cabecera Authorization de cada solicitud. Crea la clave en la página Desarrollador: consulta claves de API.

curl https://api.measuremaponline.com/api/v2/projects/YOUR_PROJECT_ID \
  -H "Authorization: YOUR_API_KEY"

Cada solicitud se comprueba con el acceso de la clave (por ejemplo, Proyectos Leer), tu suscripción y, en una solicitud enviada desde una página web, las restricciones de sitios web de la clave. Guarda en tu servidor las claves que pueden cambiar datos: consulta mantener segura tu clave.

Producción y pruebas#

Hay una sola URL base para los dos. La clave decide: una clave de pruebas lee y escribe proyectos, carpetas y productos de pruebas, que las claves de producción nunca ven. Los miembros son los mismos en los dos, pero para iniciar sesión como un miembro hace falta una clave de producción. Los proyectos de invitado creados con una clave de pruebas nunca se facturan, y los proyectos de pruebas no se pueden incrustar en tu sitio web. Los tokens indican el entorno al que pertenecen.

Qué cubre la API#

Algunas cosas que conviene saber:

• Una clave llega a los proyectos de su propia cuenta y, en Enterprise, a los de los miembros de la organización.
• Borrar un proyecto o una carpeta mediante la API es definitivo: nada va a la Papelera. Una carpeta se lleva consigo las carpetas y los proyectos que contiene y que son de tu cuenta o de tus miembros.
• En las mediciones de un proyecto, una figura lista sus productos en productIds, en orden; productId es el primero de ellos.
• /projects/{pid}/mmp da el mismo archivo .mmp que exporta la aplicación. Su esquema está publicado en github.com/blueblinkone/mmp-validator. Los elementos nuevos solo se añaden como opcionales, así que un lector escrito para un archivo más antiguo sigue funcionando.
• En Open Guest, un proyecto creado mediante la API con el nivel de acceso Open Guest cuenta para tu uso y tu presupuesto de Open Guest, igual que uno empezado desde tu enlace de invitado.
• En Open Guest, la sección person_pin_circleEnlace de invitado tiene la guía API Open Guest, con código para tu servidor y tu página: tu servidor obtiene un token de POST /auth/token con tu clave de producción y envía al visitante a un proyecto nuevo propio, con sus datos ya rellenados.
• Crear un miembro con POST /users/new ocupa una plaza, igual que una invitación, y le da el rol predeterminado de tu organización.
• Un token de POST /auth/{uid}/login abre la cuenta de ese miembro, así que necesita una clave que pueda cambiar miembros, nunca la clave de tus mapas incrustados. No se da para un Administrador ni un Gestor, ni con una clave de pruebas.
• Los productos nunca se borran mediante la API, solo se archivan, y nunca se devuelve el precio de coste de un producto.
• Las parcelas catastrales no forman parte de la API.

Respuestas y errores#

Una solicitud correcta responde con el estado 200 y JSON (la exportación .mmp responde con XML). Una fallida responde con un estado de error y un cuerpo como este:

{"errorCode": "insufficient_scope", "errorMessage": "This API key does not have the scope required for this endpoint"}

Probar la API desde la página Desarrollador#

codeDesarrollador > terminalPrueba la API envía solicitudes reales con tu clave y muestra exactamente lo que se recibe.

1. Elige Producción o Pruebas.
2. Elige un Endpoint, como «Listar todos los proyectos» u «Obtener mediciones».
3. Rellena sus parámetros. Un proyecto o un producto se elige por su nombre entre los que la clave puede leer; cuando hace falta una persona, se rellena por ti con tu propia cuenta.
4. Pulsa play_arrowEnviar petición. El estado y la respuesta aparecen debajo.

Solo se ofrecen solicitudes de lectura, así que probar no cambia nada, y estas solicitudes no cuentan en tu uso. Si tu clave no tiene el acceso que necesita un endpoint, la página te avisa de que responderá 403.

Webhooks#

Un webhook avisa a tu servidor cuando ocurre algo, igual que los correos de notificación te avisan a ti. Los webhooks forman parte de los planes Enterprise y Open Guest.

Configurar un webhook#

En codeDesarrollador > webhookWebhooks:

1. Escribe tu URL del endpoint: una dirección https:// accesible desde internet. Las direcciones de redes privadas se rechazan, y esto se vuelve a comprobar antes de cada envío.
2. Marca los Eventos que quieras (consulta eventos). Un endpoint nuevo empieza con los eventos que envía tu plan, y al menos uno tiene que estar marcado.
3. Pulsa saveGuardar. La primera vez, la página muestra tu Secreto de firma completo. Cópialo en ese momento: después solo se muestran sus últimos caracteres.
4. Pulsa sendEnviar evento de prueba y elige un evento.

Una prueba envía una muestra de ese evento, con valores inventados y "test": true en sus data, a tu endpoint guardado, incluso cuando el evento no está marcado o el endpoint está desactivado. Para detener todos los envíos, pulsa delete_outlineEliminar: se borran el endpoint y su secreto.

Debajo de la configuración, la Referencia de webhooks tiene lo que necesitas para escribir la parte que recibe: las cabeceras y el cuerpo, código que comprueba la firma en Node.js, Python y PHP, y datos de ejemplo de cada evento.

Qué recibe tu servidor#

Cada evento es un POST a tu endpoint, con un cuerpo JSON:

{"id": "evt_3f9a1c2b7d4e5f60718293a4", "type": "project.created", "created": 1790000000000, "data": { ... }}

id es único para cada evento, created es cuándo ocurrió, en milisegundos desde el 1 de enero de 1970 (UTC), y lo que contiene data depende del evento. La solicitud lleva además estas cabeceras:

• Responde con un estado 2xx en menos de 8 segundos, antes de cualquier trabajo lento. Cualquier otro estado, una redirección o que se agote el tiempo cuenta como un fallo.
• Cada evento se envía una vez y nunca se reintenta. La sección muestra el Último envío y los Fallos consecutivos.
• Tras 10 fallos seguidos, el endpoint se desactiva y el propietario recibe un correo. Arregla tu servidor y pulsa saveGuardar para volver a activarlo.
• De vez en cuando un evento llega dos veces o fuera de orden. Usa id para ignorar las repeticiones y created para ordenar los eventos.

Comprobar la firma#

Cualquiera que conozca tu dirección puede enviarle datos, así que comprueba cada envío antes de fiarte de él:

1. Divide la cabecera X-MMO-Signature por la coma en t y v1.
2. Calcula un HMAC-SHA256 de t, un punto y el cuerpo sin procesar de la solicitud, con tu secreto de firma como clave, escrito en hexadecimal.
3. Compara el resultado con v1 mediante una comparación de tiempo constante.
4. Rechaza el envío si t se aleja más de 5 minutos de la hora actual. t está en milisegundos.

Usa el cuerpo exactamente como llegó: si analizas el JSON y lo vuelves a escribir, cambia, y la firma deja de coincidir.

autorenewRotar secreto sustituye el secreto al momento y muestra el nuevo completo, una sola vez. Actualiza tu servidor en cuanto lo rotes.

Eventos#