L'API REST

L'API REST permet à votre propre logiciel de lire et de modifier le contenu de votre compte Measure Map Online : les projets et leurs mesures, les dossiers, le catalogue de produits et, avec Enterprise, les membres de votre organisation. Elle répond en JSON. La référence complète, avec chaque champ et des exemples, se trouve dans la documentation de l'API ; cette page en donne une vue d'ensemble.

Pour ouvrir la documentation depuis l'application, allez dans codeDéveloppeur > apiAPI REST et appuyez sur menu_bookAfficher la documentation.

URL de base#

Chaque requête est envoyée à :

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

Authentification#

Envoyez votre clé d'API, telle quelle, dans l'en-tête Authorization de chaque requête. Créez la clé sur la page Développeur : voir les clés d'API.

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

Chaque requête est vérifiée par rapport à l'accès de la clé (par exemple Projets en Lecture), à votre abonnement et, pour une requête envoyée depuis une page web, aux restrictions de site web de la clé. Gardez sur votre serveur les clés qui peuvent modifier des données : voir protéger votre clé.

Production et bac à sable#

Il n'y a qu'une URL de base pour les deux. C'est la clé qui décide : une clé de bac à sable lit et écrit les projets, dossiers et produits du bac à sable, que les clés de production ne voient jamais. Les membres sont les mêmes dans les deux, mais se connecter en tant que membre nécessite une clé de production. Les projets invités créés avec une clé de bac à sable ne sont jamais facturés, et les projets du bac à sable ne peuvent pas être intégrés à votre site web. Les jetons indiquent l'environnement auquel ils appartiennent.

Ce que couvre l'API#

Quelques points à connaître :

• Une clé accède aux projets de son propre compte et, avec Enterprise, à ceux des membres de l'organisation.
• Supprimer un projet ou un dossier via l'API est définitif : rien ne passe par la Corbeille. Un dossier emporte avec lui les dossiers et les projets qu'il contient et qui appartiennent à votre compte ou à vos membres.
• Dans les mesures d'un projet, une forme liste ses produits dans productIds, dans l'ordre ; productId est le premier d'entre eux.
• /projects/{pid}/mmp fournit le même fichier .mmp que celui exporté par l'application. Son schéma est publié sur github.com/blueblinkone/mmp-validator. Les nouveaux éléments ne sont jamais ajoutés qu'en tant qu'éléments facultatifs : un lecteur écrit pour un fichier plus ancien continue donc de fonctionner.
• Avec Open Guest, un projet créé via l'API avec le niveau d'accès Open Guest compte dans votre utilisation et votre budget Open Guest, comme un projet démarré depuis votre lien invité.
• Avec Open Guest, la section person_pin_circleLien invité contient le guide API Open Guest, avec du code pour votre serveur et votre page : votre serveur obtient un jeton de POST /auth/token avec votre clé de production et envoie le visiteur vers un nouveau projet à lui, ses coordonnées déjà remplies.
• Créer un membre avec POST /users/new occupe une place, comme une invitation, et lui donne le rôle par défaut de votre organisation.
• Un jeton obtenu avec POST /auth/{uid}/login ouvre le compte de ce membre : il faut donc une clé autorisée à modifier les membres, jamais la clé de vos intégrations. Il n'est pas délivré pour un Administrateur ni pour un Gestionnaire, ni avec une clé de bac à sable.
• Les produits ne sont jamais supprimés via l'API, seulement archivés, et le prix de revient d'un produit n'est jamais renvoyé.
• Les parcelles cadastrales ne font pas partie de l'API.

Réponses et erreurs#

Une requête réussie répond avec le code 200 et du JSON (l'export .mmp répond en XML). Une requête qui échoue répond avec un code d'erreur et un corps comme celui-ci :

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

Essayer l'API depuis la page Développeur#

codeDéveloppeur > terminalEssayer l’API envoie de vraies requêtes avec votre clé et affiche exactement ce qui est renvoyé.

1. Choisissez Production ou Bac à sable.
2. Choisissez un Endpoint, comme « Lister tous les projets » ou « Obtenir les mesures ».
3. Renseignez ses paramètres. Un projet ou un produit se choisit par son nom parmi ceux que la clé peut lire ; quand il faut une personne, votre propre compte est rempli pour vous.
4. Appuyez sur play_arrowEnvoyer la requête. Le code d'état et la réponse apparaissent en dessous.

Seules des requêtes de lecture sont proposées : essayer ne modifie donc rien, et ces requêtes ne comptent pas dans votre utilisation. Si votre clé n'a pas l'accès dont un point de terminaison a besoin, la page vous prévient qu'il répondra 403.

Les webhooks#

Un webhook prévient votre serveur quand quelque chose se produit, comme les e-mails de notification vous préviennent vous. Les webhooks font partie des offres Enterprise et Open Guest.

Configurer un webhook#

Dans codeDéveloppeur > webhookWebhooks :

1. Saisissez votre URL du point de terminaison : une adresse https:// accessible sur Internet. Les adresses de réseaux privés sont refusées, et ce contrôle est refait avant chaque envoi.
2. Cochez les Évènements voulus (voir les événements). Un nouveau point de terminaison démarre avec les événements que votre offre envoie, et au moins un doit rester coché.
3. Appuyez sur saveEnregistrer. La première fois, la page affiche votre Secret de signature en entier. Copiez-le à ce moment-là : ensuite, seuls ses derniers caractères sont affichés.
4. Appuyez sur sendEnvoyer un évènement test et choisissez un événement.

Un test envoie un exemple de cet événement, avec des valeurs fictives et "test": true dans ses data, à votre point de terminaison enregistré, même quand l'événement n'est pas coché ou que le point de terminaison est désactivé. Pour arrêter tous les envois, appuyez sur delete_outlineSupprimer : le point de terminaison et son secret sont supprimés.

Sous les réglages, la Référence des webhooks contient ce qu'il vous faut pour écrire la partie qui reçoit les envois : les en-têtes et le corps, du code qui vérifie la signature en Node.js, Python et PHP, et des exemples de données pour chaque événement.

Ce que reçoit votre serveur#

Chaque événement est un POST vers votre point de terminaison, avec un corps JSON :

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

id est unique pour chaque événement, created indique quand il s'est produit, en millisecondes depuis le 1er janvier 1970 (UTC), et le contenu de data dépend de l'événement. La requête contient aussi ces en-têtes :

• Répondez avec un code 2xx dans les 8 secondes, avant tout traitement long. Tout autre code, une redirection ou un délai dépassé compte comme un échec.
• Chaque événement est envoyé une seule fois et n'est jamais renvoyé. La section affiche le Dernier envoi et les Échecs consécutifs.
• Après 10 échecs consécutifs, le point de terminaison est désactivé et le propriétaire reçoit un e-mail. Réparez votre serveur et appuyez sur saveEnregistrer pour le réactiver.
• Il arrive qu'un événement arrive deux fois ou dans le désordre. Utilisez id pour ignorer les doublons et created pour remettre les événements dans l'ordre.

Vérifier la signature#

N'importe qui connaissant votre adresse peut y envoyer des requêtes : vérifiez donc chaque envoi avant de lui faire confiance.

1. Séparez l'en-tête X-MMO-Signature à la virgule en t et v1.
2. Calculez un HMAC-SHA256 de t, d'un point et du corps brut de la requête, avec votre secret de signature comme clé, écrit en hexadécimal.
3. Comparez le résultat à v1 avec une comparaison en temps constant.
4. Rejetez l'envoi si t s'écarte de plus de 5 minutes de l'heure actuelle. t est en millisecondes.

Utilisez le corps exactement tel qu'il est arrivé : analyser le JSON puis le réécrire le modifie, et la signature ne correspond plus.

autorenewRenouveler le secret remplace le secret immédiatement et affiche le nouveau en entier, une seule fois. Mettez à jour votre serveur dès que vous l'avez renouvelé.

Les événements#