REST API

Met de REST API kan je eigen software doen wat de app doet: projecten en hun metingen, mappen en de productcatalogus; bij Enterprise je organisatie, zoals de pagina Enterprise die beheert; bij Open Guest je gastlink, gastprojecten en offerteaanvragen. Hij antwoordt in JSON. De volledige referentie, met elk veld en voorbeeld, is de API-documentatie; deze pagina is het overzicht.

Om de documentatie vanuit de app te openen, ga je naar codeOntwikkelaar > apiREST API en druk je op menu_bookDocumentatie bekijken.

Basis-URL#

Elk verzoek gaat naar:

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

Authenticatie#

Stuur je API-sleutel, zoals hij is, mee in de Authorization-header van elk verzoek. Maak de sleutel aan op de pagina Ontwikkelaar: zie API-sleutels.

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

Elk verzoek wordt gecontroleerd op de toegang van de sleutel (bijvoorbeeld Projecten Lezen), je abonnement en, bij een verzoek vanaf een webpagina, de websitebeperkingen van de sleutel. Houd sleutels die gegevens kunnen wijzigen op je server: zie houd je sleutel veilig.

Live en sandbox#

Er is één basis-URL voor beide. De sleutel bepaalt het: een sandbox-sleutel leest en schrijft sandbox-projecten, -mappen en -producten, die livesleutels nooit zien. De gebruikers, plekken en teams van je organisatie zijn in beide hetzelfde, dus om ze te wijzigen heb je een livesleutel nodig. Gastprojecten die met een sandbox-sleutel zijn gemaakt, worden nooit gefactureerd en sandbox-projecten kunnen niet op je website worden ingesloten. Tokens geven aan bij welke omgeving ze horen.

Wat de API omvat#

Een paar dingen om te weten:

• Een sleutel bereikt de projecten van het eigen account en, bij Enterprise, die van de gebruikers van de organisatie.
• Een project verwijderen zet het in de Prullenbak, zoals in de app, en alleen de maker kan dat; verwijder het definitief uit de Prullenbak met forever=true. Een map verwijderen zet de projecten erin in de Prullenbak.
• In de metingen van een project noemt een vorm zijn producten in productIds, op volgorde; productId is de eerste ervan.
• /projects/{pid}/mmp geeft hetzelfde .mmp-bestand dat de app exporteert. Het schema is gepubliceerd op github.com/blueblinkone/mmp-validator. Nieuwe elementen worden alleen als optionele toegevoegd, zodat een lezer die voor een ouder bestand is geschreven blijft werken.
• Bij Open Guest telt een gastproject dat via de API is gestart (POST /open-guest/projects) mee voor je Open Guest-gebruik en -budget, net als een project dat via je gastlink is gestart.
• Bij Open Guest heeft het onderdeel person_pin_circleGastlink de handleiding Open Guest API, met code voor je server en je pagina: je server haalt met je livesleutel een token op via POST /auth/token en stuurt de bezoeker naar een nieuw eigen project, met zijn of haar gegevens al ingevuld.
• Mensen komen alleen via een uitnodiging in je organisatie (POST /enterprise/invitations), zoals op de pagina Enterprise: wie geen account heeft, krijgt er een en kiest zelf een wachtwoord. De API maakt nooit een account aan en stelt nooit een wachtwoord in.
• Een gebruiker verwijderen uit de organisatie (POST /enterprise/users/{uid}/remove) laat hun account bestaan; er een verwijderen (DELETE /enterprise/users/{uid}) verwijdert het account. In beide gevallen blijft het werk dat ze maakten bij de organisatie, in een nieuwe map met hun naam die je beheerders delen.
• Wanneer een gast om je offerte vraagt, antwoordt GET /open-guest/requests/{pid} wie het is, wat de gast schreef, wat de gast mat en, met Producten: Lezen, de offerte zelf.
• Bij Open Guest starten tokens gastprojecten voor je bezoekers. POST /auth/iframe/token, dat een bezoeker inlogt in een ingesloten kaart, is voor Enterprise-sleutels.
• Producten worden via de API nooit verwijderd, alleen gearchiveerd, en de kostprijs van een product wordt nooit teruggegeven.
• Kadastrale percelen maken geen deel uit van de API.

Antwoorden en fouten#

Een geslaagd verzoek antwoordt met status 200 en JSON (de .mmp-export antwoordt met XML). Een mislukt verzoek antwoordt met een foutstatus en een body zoals:

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

De API proberen op de pagina Ontwikkelaar#

codeOntwikkelaar > terminalDe API uitproberen verstuurt echte verzoeken met je sleutel en toont precies wat er terugkomt.

1. Kies Live of Sandbox.
2. Kies een Endpoint, zoals "Je projecten weergeven", "Metingen ophalen" of "Het account ophalen". De lijst biedt de endpoints die je abonnement bevat.
3. Vul de parameters in. Een project of product kies je op naam uit degene die de sleutel kan lezen; waar een persoon nodig is, wordt je eigen account voor je ingevuld.
4. Druk op play_arrowVerzoek verzenden. De status en het antwoord verschijnen eronder.

Alleen verzoeken die lezen worden aangeboden, dus uitproberen wijzigt niets, en deze verzoeken tellen niet mee in je gebruik. Als je sleutel niet de toegang heeft die een endpoint nodig heeft, waarschuwt de pagina dat het met 403 zal antwoorden.

Webhooks#

Een webhook vertelt je server wanneer er iets gebeurt, zoals de meldingsmails jou dat vertellen. Webhooks horen bij de abonnementen Enterprise en Open Guest.

Een webhook instellen#

In codeOntwikkelaar > webhookWebhooks:

1. Typ je Endpoint-URL: een https://-adres op internet. Adressen op privénetwerken worden geweigerd, en dit wordt voor elke aflevering opnieuw gecontroleerd.
2. Vink de Gebeurtenissen aan die je wilt (zie gebeurtenissen). Een nieuw endpoint begint met de gebeurtenissen die je abonnement verstuurt en er moet er minstens één zijn aangevinkt.
3. Druk op saveOpslaan. De eerste keer toont de pagina je Ondertekeningssecret volledig. Kopieer hem dan: daarna worden alleen de laatste tekens getoond.
4. Druk op sendTestgebeurtenis verzenden en kies een gebeurtenis.

Een test verstuurt een voorbeeld van die gebeurtenis, met verzonnen waarden en "test": true in de data, naar je opgeslagen endpoint, ook als de gebeurtenis niet is aangevinkt of het endpoint uit staat. Om alle afleveringen te stoppen, druk je op delete_outlineVerwijderen: het endpoint en zijn secret worden verwijderd.

Onder de instellingen heeft de Webhook-referentie wat je nodig hebt om de ontvangende kant te schrijven: de headers en de body, code die de handtekening controleert in Node.js, Python en PHP, en voorbeeldgegevens voor elke gebeurtenis.

Wat je server ontvangt#

Elke gebeurtenis is één POST naar je endpoint, met een JSON-body:

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

id is uniek voor elke gebeurtenis, created is wanneer het gebeurde in milliseconden sinds 1 januari 1970 (UTC), en wat data bevat hangt af van de gebeurtenis. Het verzoek heeft ook deze headers:

• Antwoord met een 2xx-status binnen 8 seconden, vóór al het trage werk. Elke andere status, een redirect of een time-out telt als mislukt.
• Elke gebeurtenis wordt één keer verstuurd en nooit opnieuw geprobeerd. Het onderdeel toont de Laatste levering en de Opeenvolgende fouten.
• Na 10 mislukkingen op rij wordt het endpoint uitgezet en krijgt de eigenaar een e-mail. Herstel je server en druk op saveOpslaan om het weer aan te zetten.
• Af en toe komt een gebeurtenis twee keer of in de verkeerde volgorde aan. Gebruik id om herhalingen te negeren en created om gebeurtenissen op volgorde te zetten.

De handtekening controleren#

Iedereen die je adres kent, kan er iets naartoe sturen, dus controleer elke aflevering voordat je haar vertrouwt:

1. Splits de X-MMO-Signature-header bij de komma in t en v1.
2. Bereken een HMAC-SHA256 van t, een punt en de ruwe body van het verzoek, met je signing secret als sleutel, hexadecimaal geschreven.
3. Vergelijk het resultaat met v1 met een vergelijking in constante tijd.
4. Weiger de aflevering als t meer dan 5 minuten van de huidige tijd afwijkt. t is in milliseconden.

Gebruik de body precies zoals hij is aangekomen: het JSON parseren en weer uitschrijven verandert hem, en dan klopt de handtekening niet meer.

autorenewSecret vernieuwen vervangt het secret meteen en toont het nieuwe één keer volledig. Werk je server bij zodra je het vernieuwt.

Gebeurtenissen#