API REST

L'API REST deixa que el teu propi programari faci el que fa l'app: projectes i les seves mesures, carpetes i el catàleg de productes; a Enterprise, la teva organització, tal com la gestiona la pàgina Enterprise; a Open Guest, el teu enllaç de convidat, els projectes de convidat i les sol·licituds de pressupost. Respon en JSON. La referència completa, amb tots els camps i exemples, és la documentació de l'API; aquesta pàgina n'és la visió general.

Per obrir la documentació des de l'aplicació, ves a codeDesenvolupador > apiREST API i prem menu_bookMostra la documentació.

URL base#

Cada petició va a:

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

Autenticació#

Envia la teva clau d'API, tal com és, a la capçalera Authorization de cada petició. Crea la clau a la pàgina Desenvolupador: consulta claus d'API.

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

Cada petició es comprova segons l'accés de la clau (per exemple, Projectes Lectura), la teva subscripció i, per a una petició enviada des d'una pàgina web, les restriccions de llocs web de la clau. Mantén al teu servidor les claus que poden canviar dades: consulta mantén la clau segura.

Live i sandbox#

Hi ha una sola URL base per als dos. Ho decideix la clau: una clau sandbox llegeix i escriu projectes, carpetes i productes sandbox, que les claus reals no veuen mai. Els usuaris, les places i els equips de la teva organització són els mateixos en tots dos, de manera que canviar-los necessita una clau real. Els projectes de convidat fets amb una clau sandbox no es facturen mai, i els projectes sandbox no es poden incrustar al teu lloc web. Els tokens informen de l'entorn al qual pertanyen.

Què cobreix l'API#

Algunes coses que cal saber:

• Una clau arriba als projectes del seu propi compte i, a Enterprise, als dels usuaris de l'organització.
• Eliminar un projecte el posa a la Paperera, com a l'app, i només el seu creador pot fer-ho; elimina'l definitivament des de la Paperera amb forever=true. Eliminar una carpeta posa els seus projectes a la Paperera.
• A les mesures d'un projecte, una figura llista els seus productes a productIds, en ordre; productId és el primer.
• /projects/{pid}/mmp dona el mateix fitxer .mmp que exporta l'aplicació. El seu esquema està publicat a github.com/blueblinkone/mmp-validator. Els elements nous només s'afegeixen com a opcionals, de manera que un lector escrit per a un fitxer més antic continua funcionant.
• A Open Guest, un projecte de convidat iniciat per l'API (POST /open-guest/projects) compta per a l'ús i el pressupost màxim d'Open Guest, igual que un iniciat des del teu enllaç de convidat.
• A Open Guest, la secció person_pin_circleEnllaç de convidat té la guia Open Guest API, amb codi per al teu servidor i la teva pàgina: el teu servidor obté un token amb POST /auth/token i la teva clau real, i envia el visitant a un projecte nou propi, amb les seves dades emplenades.
• Les persones només s'incorporen a la teva organització per invitació (POST /enterprise/invitations), com a la pàgina Enterprise: qui no té compte en rep un i tria la seva contrasenya. L'API mai no crea un compte ni defineix una contrasenya.
• Treure un usuari (POST /enterprise/users/{uid}/remove) li deixa el seu compte; eliminar-lo (DELETE /enterprise/users/{uid}) l'elimina. En tots dos casos la feina que ha fet es queda a l'organització, en una carpeta nova amb el seu nom que comparteixen els teus administradors.
• Quan un convidat demana el teu pressupost, GET /open-guest/requests/{pid} respon qui és, què ha escrit, què ha mesurat i, amb Productes: Lectura, el pressupost mateix.
• A Open Guest, els tokens inicien projectes de convidat per als teus visitants. POST /auth/iframe/token, que fa iniciar la sessió a un visitant en un mapa incrustat, és per a claus Enterprise.
• Els productes mai no s'eliminen amb l'API, només s'arxiven, i el preu de cost d'un producte no es retorna mai.
• Les parcel·les cadastrals no formen part de l'API.

Respostes i errors#

Una petició correcta respon amb l'estat 200 i JSON (l'exportació .mmp respon amb XML). Una de fallida respon amb un estat d'error i un cos com aquest:

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

Prova l'API des de la pàgina Desenvolupador#

codeDesenvolupador > terminalProva l'API envia peticions reals amb la teva clau i mostra exactament què torna.

1. Tria Producció o Sandbox.
2. Tria un Punt final, com ara "Llista els teus projectes", "Obté les mesures" o "Obté el compte". La llista ofereix els punts finals que inclou el teu pla.
3. Omple'n els paràmetres. Un projecte o un producte es tria pel nom entre els que la clau pot llegir; quan cal una persona, s'omple el teu propi compte per tu.
4. Prem play_arrowEnvia la sol·licitud. L'estat i la resposta apareixen a sota.

Només s'ofereixen peticions que llegeixen, de manera que provar no canvia res, i aquestes peticions no es compten a l'ús. Si la teva clau no té l'accés que necessita un punt final, la pàgina t'avisa que respondrà 403.

Webhooks#

Un webhook avisa el teu servidor quan passa alguna cosa, com et criden l'atenció els correus de notificació. Els webhooks formen part dels plans Enterprise i Open Guest.

Configura un webhook#

A codeDesenvolupador > webhookWebhooks:

1. Escriu la teva URL del punt final: una adreça https:// a internet. Les adreces de xarxes privades es rebutgen, i es torna a comprovar abans de cada lliurament.
2. Marca els Esdeveniments que vols (consulta esdeveniments). Un punt final nou comença amb els esdeveniments que envia el teu pla, i n'hi ha d'haver almenys un de marcat.
3. Prem saveDesa. La primera vegada, la pàgina et mostra el Secret de signatura sencer. Copia'l aleshores: després només se'n mostren els darrers caràcters.
4. Prem sendEnvia un esdeveniment de prova i tria un esdeveniment.

Una prova envia un exemple d'aquell esdeveniment, amb valors inventats i "test": true al seu data, al teu punt final desat, encara que l'esdeveniment no estigui marcat o el punt final estigui desactivat. Per aturar tots els lliuraments, prem delete_outlineElimina: el punt final i el seu secret s'eliminen.

Sota la configuració, la Referència dels webhooks té el que necessites per escriure la part receptora: les capçaleres i el cos, codi que comprova la signatura en Node.js, Python i PHP, i dades d'exemple per a cada esdeveniment.

Què rep el teu servidor#

Cada esdeveniment és un POST al teu punt final, amb un cos JSON:

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

id és únic per a cada esdeveniment, created és quan va passar en mil·lisegons des de l'1 de gener de 1970 (UTC), i el que conté data depèn de l'esdeveniment. La petició també té aquestes capçaleres:

• Respon amb un estat 2xx en menys de 8 segons, abans de qualsevol feina lenta. Qualsevol altre estat, una redirecció o un temps d'espera esgotat compta com a error.
• Cada esdeveniment s'envia una sola vegada i no es reintenta mai. La secció mostra l'Darrer lliurament i els Errors consecutius.
• Després de 10 errors seguits, el punt final es desactiva i el propietari rep un correu. Arregla el teu servidor i prem saveDesa per tornar-lo a activar.
• De tant en tant un esdeveniment arriba dues vegades o desordenat. Fes servir id per ignorar les repeticions i created per ordenar els esdeveniments.

Comprova la signatura#

Qualsevol que conegui la teva adreça hi pot enviar peticions, així que comprova cada lliurament abans de fiar-te'n:

1. Divideix la capçalera X-MMO-Signature per la coma en t i v1.
2. Calcula un HMAC-SHA256 de t, un punt i el cos en brut de la petició, amb el teu secret de signatura com a clau, escrit en hexadecimal.
3. Compara el resultat amb v1 amb una comparació de temps constant.
4. Rebutja el lliurament si t difereix més de 5 minuts de l'hora actual. t és en mil·lisegons.

Fes servir el cos exactament tal com ha arribat: analitzar el JSON i tornar-lo a escriure el canvia, i la signatura ja no coincideix.

autorenewRota el secret substitueix el secret a l'instant i mostra el nou sencer, una sola vegada. Actualitza el teu servidor tan bon punt el rotis.

Esdeveniments#