REST-API

REST-API:t låter din egen programvara göra det appen gör: projekt och deras mätningar, mappar och produktkatalogen; med Enterprise din organisation, så som sidan Enterprise sköter den; med Open Guest din gästlänk, gästprojekt och offertförfrågningar. Det svarar i JSON. Den fullständiga referensen, med alla fält och exempel, är API-dokumentationen; den här sidan är översikten.

För att öppna dokumentationen från appen går du till codeUtvecklare > apiREST API och trycker på menu_bookVisa dokumentation.

Bas-URL#

Varje förfrågan går till:

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

Autentisering#

Skicka din API-nyckel, precis som den är, i Authorization-huvudet i varje förfrågan. Skapa nyckeln på utvecklarsidan: se API-nycklar.

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

Varje förfrågan kontrolleras mot nyckelns åtkomst (till exempel Projekt Läsa), din prenumeration och, för en förfrågan som skickas från en webbsida, nyckelns webbplatsbegränsningar. Förvara nycklar som kan ändra data på din server: se håll din nyckel säker.

Live och sandbox#

Det finns en bas-URL för båda. Nyckeln avgör: en sandbox-nyckel läser och skriver sandbox-projekt, mappar och produkter, som livenycklar aldrig ser. Din organisations användare, platser och team är desamma i båda, så för att ändra dem krävs en livenyckel. Gästprojekt som skapas med en sandbox-nyckel faktureras aldrig, och sandbox-projekt kan inte bäddas in på din webbplats. Token anger vilken miljö de tillhör.

Vad API:t omfattar#

Några saker att känna till:

• En nyckel når projekten på sitt eget konto och, med Enterprise, organisationens användares projekt.
• Att ta bort ett projekt lägger det i Papperskorg, som i appen, och bara dess skapare kan göra det; ta bort det för gott från Papperskorg med forever=true. Att ta bort en mapp lägger dess projekt i Papperskorg.
• I ett projekts mätningar listar en form sina produkter i productIds, i ordning; productId är den första av dem.
• /projects/{pid}/mmp ger samma .mmp-fil som appen exporterar. Dess schema är publicerat på github.com/blueblinkone/mmp-validator. Nya element läggs bara till som valfria, så en läsare skriven för en äldre fil fortsätter fungera.
• Med Open Guest räknas ett gästprojekt som startats via API:t (POST /open-guest/projects) in i din Open Guest-användning och -budget, som ett som startats från din gästlänk.
• På Open Guest har avsnittet person_pin_circleGästlänk guiden Open Guest API, med kod för din server och din sida: din server hämtar en token från POST /auth/token med din livenyckel och skickar besökaren till ett nytt projekt som är deras eget, med deras uppgifter ifyllda.
• Personer går bara med i din organisation via inbjudan (POST /enterprise/invitations), som på sidan Enterprise: den som saknar konto får ett och väljer sitt eget lösenord. API:t skapar aldrig ett konto och anger aldrig ett lösenord.
• Att ta bort en användare från organisationen (POST /enterprise/users/{uid}/remove) låter dem behålla sitt konto; att radera en (DELETE /enterprise/users/{uid}) raderar kontot. Oavsett vilket blir det arbete de gjort kvar hos organisationen, i en ny mapp med deras namn som dina administratörer delar.
• När en gäst ber om din offert svarar GET /open-guest/requests/{pid} vem gästen är, vad hen skrev, vad hen mätte och, med Produkter: Läsa, själva offerten.
• På Open Guest startar token gästprojekt åt dina besökare. POST /auth/iframe/token, som loggar in en besökare på en inbäddad karta, är till för Enterprise-nycklar.
• Produkter raderas aldrig via API:t, bara arkiveras, och en produkts inköpspris returneras aldrig.
• Katastralparceller ingår inte i API:t.

Svar och fel#

En lyckad förfrågan svarar med status 200 och JSON (.mmp-exporten svarar med XML). En misslyckad svarar med en felstatus och en kropp som denna:

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

Prova API:t från utvecklarsidan#

codeUtvecklare > terminalTesta API:t skickar riktiga förfrågningar med din nyckel och visar exakt vad som kommer tillbaka.

1. Välj Live eller Sandbox.
2. Välj en Endpoint, till exempel "Lista dina projekt", "Hämta mätningar" eller "Hämta kontot". Listan erbjuder de endpoints som din plan omfattar.
3. Fyll i dess parametrar. Ett projekt eller en produkt väljs med namn bland dem nyckeln kan läsa; där en person behövs fylls ditt eget konto i åt dig.
4. Tryck på play_arrowSkicka förfrågan. Statusen och svaret visas nedanför.

Bara förfrågningar som läser erbjuds, så ingenting ändras av att prova, och de här förfrågningarna räknas inte i din användning. Om din nyckel inte har den åtkomst en endpoint kräver varnar sidan dig för att den kommer att svara 403.

Webhooks#

En webhook talar om för din server när något händer, på samma sätt som aviseringsmejlen talar om det för dig. Webhooks ingår i planerna Enterprise och Open Guest.

Ställ in en webhook#

I codeUtvecklare > webhookWebhooks:

1. Skriv din Endpoint-URL: en https://-adress på internet. Adresser på privata nätverk avvisas, och det kontrolleras igen före varje leverans.
2. Kryssa i de Händelser du vill ha (se händelser). En ny endpoint börjar med de händelser som din plan skickar, och minst en måste vara ikryssad.
3. Tryck på saveSpara. Första gången visar sidan din Signeringshemlighet i sin helhet. Kopiera den då: efteråt visas bara dess sista tecken.
4. Tryck på sendSkicka testhändelse och välj en händelse.

Ett test skickar ett exempel på den händelsen, med påhittade värden och "test": true i dess data, till din sparade endpoint, även när händelsen inte är ikryssad eller endpointen är avstängd. För att stoppa alla leveranser trycker du på delete_outlineTa bort: endpointen och dess hemlighet raderas.

Under inställningarna har Webhook-referens det du behöver för att skriva mottagarsidan: huvudena och kroppen, kod som kontrollerar signaturen i Node.js, Python och PHP, och exempeldata för varje händelse.

Vad din server får#

Varje händelse är en POST till din endpoint, med en JSON-kropp:

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

id är unikt för varje händelse, created är när den inträffade i millisekunder sedan 1 januari 1970 (UTC), och vad data innehåller beror på händelsen. Förfrågan har också dessa huvuden:

• Svara med en 2xx-status inom 8 sekunder, före allt långsamt arbete. Varje annan status, en omdirigering eller en timeout räknas som ett misslyckande.
• Varje händelse skickas en gång och försöks aldrig igen. Avsnittet visar Senaste leverans och Misslyckanden i rad.
• Efter 10 misslyckanden i rad stängs endpointen av och ägaren får ett e-postmeddelande. Rätta till din server och tryck på saveSpara för att slå på den igen.
• Då och då kommer en händelse två gånger eller i fel ordning. Använd id för att ignorera upprepningar och created för att lägga händelser i ordning.

Kontrollera signaturen#

Vem som helst som känner till din adress kan skicka till den, så kontrollera varje leverans innan du litar på den:

1. Dela X-MMO-Signature-huvudet vid kommatecknet i t och v1.
2. Beräkna en HMAC-SHA256 av t, en punkt och den råa förfrågningskroppen, med din signeringshemlighet som nyckel, skriven hexadecimalt.
3. Jämför resultatet med v1 med en jämförelse i konstant tid.
4. Avvisa leveransen om t ligger mer än 5 minuter från aktuell tid. t är i millisekunder.

Använd kroppen exakt som den kom: att tolka JSON och skriva ut den igen ändrar den, och signaturen stämmer inte längre.

autorenewByt hemlighet byter ut hemligheten direkt och visar den nya i sin helhet, en gång. Uppdatera din server så snart du har bytt.

Händelser#