API-ul REST

API-ul REST îți permite software-ului tău să facă ce face aplicația: proiectele și măsurătorile lor, dosarele și catalogul de produse; la Enterprise, organizația ta, așa cum o conduce pagina Enterprise; la Open Guest, linkul tău de invitat, proiectele de invitat și cererile de ofertă. Răspunde în JSON. Referința completă, cu fiecare câmp și exemplu, este documentația API; această pagină este prezentarea generală.

Ca să deschizi documentația din aplicație, mergi la codeDezvoltator > apiREST API și apasă menu_bookVezi documentația.

URL de bază#

Fiecare cerere merge la:

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

Autentificare#

Trimite cheia ta API, așa cum este, în antetul Authorization al fiecărei cereri. Creează cheia în pagina Dezvoltator: vezi cheile API.

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

Fiecare cerere este verificată în raport cu accesul cheii (de exemplu, Proiecte Citire), cu abonamentul tău și, pentru o cerere trimisă dintr-o pagină web, cu restricțiile de site ale cheii. Ține pe serverul tău cheile care pot modifica date: vezi păstrează-ți cheia în siguranță.

Live și sandbox#

Există un singur URL de bază pentru ambele. Cheia decide: o cheie sandbox citește și scrie proiecte, dosare și produse sandbox, pe care cheile live nu le văd niciodată. Utilizatorii, locurile și echipele organizației tale sunt aceleași în ambele, așa că modificarea lor necesită o cheie live. Proiectele de invitat create cu o cheie sandbox nu se facturează niciodată, iar proiectele sandbox nu pot fi încorporate pe site-ul tău. Tokenurile indică mediul căruia îi aparțin.

Ce acoperă API-ul#

Câteva lucruri de știut:

• O cheie ajunge la proiectele propriului cont și, la Enterprise, la cele ale utilizatorilor organizației.
• Ștergerea unui proiect îl pune în Coș de gunoi, ca în aplicație, și numai creatorul lui poate face asta; șterge-l definitiv din Coș de gunoi cu forever=true. Ștergerea unui dosar pune proiectele lui în Coș de gunoi.
• În măsurătorile unui proiect, o formă își listează produsele în productIds, în ordine; productId este primul dintre ele.
• /projects/{pid}/mmp oferă același fișier .mmp pe care îl exportă aplicația. Schema lui este publicată la github.com/blueblinkone/mmp-validator. Elementele noi se adaugă întotdeauna doar ca elemente opționale, așa că un cititor scris pentru un fișier mai vechi continuă să funcționeze.
• La Open Guest, un proiect de invitat început prin API (POST /open-guest/projects) contează la utilizarea și bugetul tău Open Guest, ca unul început din linkul tău de invitat.
• Pe Open Guest, secțiunea person_pin_circleLink de invitat conține ghidul Open Guest API, cu cod pentru serverul și pagina ta: serverul tău obține un token de la POST /auth/token cu cheia ta live și îl trimite pe vizitator într-un proiect nou al lui, cu datele lui completate.
• Persoanele se alătură organizației tale doar prin invitație (POST /enterprise/invitations), ca pe pagina Enterprise: cine nu are cont primește unul și își alege singur parola. API-ul nu creează niciodată un cont și nu stabilește niciodată o parolă.
• Eliminarea unui utilizator (POST /enterprise/users/{uid}/remove) îi lasă contul; ștergerea lui (DELETE /enterprise/users/{uid}) șterge contul. În ambele cazuri munca lui rămâne la organizație, într-un dosar nou cu numele lui pe care îl partajează administratorii tăi.
• Când un invitat cere oferta ta, GET /open-guest/requests/{pid} răspunde cine este, ce a scris, ce a măsurat și, cu Produse: Citire, oferta însăși.
• Pe Open Guest, tokenurile pornesc proiecte de invitat pentru vizitatorii tăi. POST /auth/iframe/token, care autentifică un vizitator într-o hartă încorporată, este pentru cheile Enterprise.
• Produsele nu sunt șterse niciodată prin API, doar arhivate, iar prețul de cost al unui produs nu este returnat niciodată.
• Parcelele cadastrale nu fac parte din API.

Răspunsuri și erori#

O cerere reușită răspunde cu starea 200 și JSON (exportul .mmp răspunde cu XML). Una eșuată răspunde cu o stare de eroare și un corp ca acesta:

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

Încearcă API-ul din pagina Dezvoltator#

codeDezvoltator > terminalÎncearcă API-ul trimite cereri reale cu cheia ta și arată exact ce primești înapoi.

1. Alege Live sau Sandbox.
2. Alege un Endpoint, de exemplu „Listează proiectele tale", „Obține măsurătorile" sau „Obține contul". Lista oferă endpoint-urile incluse în planul tău.
3. Completează parametrii lui. Un proiect sau un produs se alege după nume dintre cele pe care cheia le poate citi; acolo unde este nevoie de o persoană, contul tău este completat pentru tine.
4. Apasă play_arrowTrimite cererea. Starea și răspunsul apar mai jos.

Se oferă doar cereri de citire, deci nimic nu se schimbă prin încercare, iar aceste cereri nu sunt numărate în utilizarea ta. Dacă cheia ta nu are accesul de care are nevoie un endpoint, pagina te avertizează că va răspunde cu 403.

Webhook-uri#

Un webhook anunță serverul tău când se întâmplă ceva, așa cum te anunță ție e-mailurile de notificare. Webhook-urile fac parte din planurile Enterprise și Open Guest.

Configurează un webhook#

În codeDezvoltator > webhookWebhook-uri:

1. Scrie URL endpoint: o adresă https:// de pe internet. Adresele din rețele private sunt refuzate, iar verificarea se repetă înainte de fiecare livrare.
2. Bifează Evenimente dorite (vezi evenimente). Un endpoint nou pornește cu evenimentele pe care le trimite planul tău și cel puțin unul trebuie bifat.
3. Apasă saveSalvează. Prima dată, pagina îți arată Secret de semnare în întregime. Copiază-l atunci: după aceea se afișează doar ultimele lui caractere.
4. Apasă sendTrimite un eveniment de test și alege un eveniment.

Un test trimite un exemplu al acelui eveniment, cu valori inventate și "test": true în data, la endpoint-ul tău salvat, chiar dacă evenimentul nu este bifat sau endpoint-ul este oprit. Ca să oprești toate livrările, apasă delete_outlineElimină: endpoint-ul și secretul lui sunt șterse.

Sub setări, Referință webhook conține ce ai nevoie ca să scrii partea care primește: antetele și corpul, cod care verifică semnătura în Node.js, Python și PHP și date de exemplu pentru fiecare eveniment.

Ce primește serverul tău#

Fiecare eveniment este un POST către endpoint-ul tău, cu un corp JSON:

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

id este unic pentru fiecare eveniment, created este momentul în care s-a întâmplat, în milisecunde de la 1 ianuarie 1970 (UTC), iar ce conține data depinde de eveniment. Cererea are și aceste antete:

• Răspunde cu o stare 2xx în 8 secunde, înainte de orice lucru lent. Orice altă stare, o redirecționare sau o expirare a timpului se numără ca eșec.
• Fiecare eveniment este trimis o singură dată și nu se reîncearcă niciodată. Secțiunea arată Ultima livrare și Eșecuri consecutive.
• După 10 eșecuri la rând, endpoint-ul este oprit, iar proprietarul primește un e-mail. Repară serverul și apasă saveSalvează ca să-l reactivezi.
• Din când în când un eveniment sosește de două ori sau în altă ordine. Folosește id ca să ignori repetările și created ca să pui evenimentele în ordine.

Verifică semnătura#

Oricine îți cunoaște adresa poate trimite către ea, așa că verifică fiecare livrare înainte să ai încredere în ea:

1. Împarte antetul X-MMO-Signature la virgulă în t și v1.
2. Calculează un HMAC-SHA256 din t, un punct și corpul brut al cererii, cu secretul tău de semnare drept cheie, scris în hexazecimal.
3. Compară rezultatul cu v1 printr-o comparație în timp constant.
4. Respinge livrarea dacă t diferă cu mai mult de 5 minute de ora curentă. t este în milisecunde.

Folosește corpul exact așa cum a sosit: dacă analizezi JSON-ul și îl scrii din nou, el se schimbă, iar semnătura nu se mai potrivește.

autorenewRotește secretul înlocuiește secretul imediat și îl afișează pe cel nou în întregime, o singură dată. Actualizează-ți serverul îndată ce rotești secretul.

Evenimente#