API REST

L'API REST permette al tuo software di fare ciò che fa l'app: progetti e relative misure, cartelle e catalogo prodotti; con Enterprise, la tua organizzazione, come la gestisce la pagina Enterprise; con Open Guest, il tuo link per ospiti, i progetti ospite e le richieste di preventivo. Risponde in JSON. Il riferimento completo, con ogni campo ed esempio, è la documentazione API; questa pagina ne è la panoramica.

Per aprire la documentazione dall'app, vai in codeSviluppatori > apiREST API e premi menu_bookVedi la documentazione.

URL di base#

Ogni richiesta va a:

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

Autenticazione#

Invia la tua chiave API, così com'è, nell'intestazione Authorization di ogni richiesta. Crea la chiave nella pagina Sviluppatori: vedi chiavi API.

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

Ogni richiesta viene verificata rispetto all'accesso della chiave (per esempio Progetti Lettura), al tuo abbonamento e, per una richiesta inviata da una pagina web, alle restrizioni per i siti web della chiave. Tieni sul tuo server le chiavi che possono modificare i dati: vedi tenere al sicuro la chiave.

Live e sandbox#

C'è un solo URL di base per entrambi. Decide la chiave: una chiave sandbox legge e scrive progetti, cartelle e prodotti sandbox, che le chiavi live non vedono mai. Gli utenti, i posti e i team della tua organizzazione sono gli stessi in entrambi, quindi per modificarli serve una chiave live. I progetti ospite creati con una chiave sandbox non vengono mai fatturati, e i progetti sandbox non si possono incorporare nel tuo sito web. I token riportano l'ambiente a cui appartengono.

Cosa copre l'API#

Alcune cose da sapere:

• Una chiave raggiunge i progetti del proprio account e, con Enterprise, quelli degli utenti dell'organizzazione.
• Eliminare un progetto lo mette nel Cestino, come nell'app, e può farlo solo il suo creatore; eliminalo definitivamente dal Cestino con forever=true. Eliminare una cartella mette i suoi progetti nel Cestino.
• Nelle misurazioni di un progetto, una forma elenca i suoi prodotti in productIds, in ordine; productId è il primo di essi.
• /projects/{pid}/mmp restituisce lo stesso file .mmp che esporta l'app. Il suo schema è pubblicato su github.com/blueblinkone/mmp-validator. I nuovi elementi vengono sempre e solo aggiunti come facoltativi, quindi un lettore scritto per un file più vecchio continua a funzionare.
• Con Open Guest, un progetto ospite avviato tramite l'API (POST /open-guest/projects) conta per il tuo utilizzo e il tuo budget Open Guest, come uno avviato dal tuo link per ospiti.
• Con Open Guest, la sezione person_pin_circleLink per ospiti ha la guida Open Guest API, con il codice per il tuo server e la tua pagina: il tuo server ottiene un token da POST /auth/token con la tua chiave live e porta il visitatore su un nuovo progetto tutto suo, con i suoi dati già compilati.
• Le persone entrano nella tua organizzazione solo su invito (POST /enterprise/invitations), come nella pagina Enterprise: chi non ha un account ne riceve uno e sceglie la propria password. L'API non crea mai un account e non imposta mai una password.
• Rimuovere un utente (POST /enterprise/users/{uid}/remove) gli lascia il suo account; eliminarlo (DELETE /enterprise/users/{uid}) elimina l'account. In entrambi i casi il lavoro che ha fatto resta all'organizzazione, in una nuova cartella con il suo nome che i tuoi amministratori condividono.
• Quando un ospite chiede il tuo preventivo, GET /open-guest/requests/{pid} risponde chi è, cosa ha scritto, cosa ha misurato e, con Prodotti: Lettura, il preventivo stesso.
• Con Open Guest, i token avviano progetti ospite per i tuoi visitatori. POST /auth/iframe/token, che fa accedere un visitatore a una mappa incorporata, è per le chiavi Enterprise.
• I prodotti non vengono mai eliminati tramite l'API, solo archiviati, e il prezzo di costo di un prodotto non viene mai restituito.
• Le particelle catastali non fanno parte dell'API.

Risposte ed errori#

Una richiesta riuscita risponde con stato 200 e JSON (l'esportazione .mmp risponde con XML). Una richiesta fallita risponde con uno stato di errore e un corpo come:

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

Provare l'API dalla pagina Sviluppatori#

codeSviluppatori > terminalProva l'API invia richieste reali con la tua chiave e mostra esattamente cosa torna indietro.

1. Scegli Produzione oppure Sandbox.
2. Scegli un Endpoint, come "Elenca i tuoi progetti", "Ottieni le misure" o "Ottieni l'account". L'elenco propone gli endpoint inclusi nel tuo piano.
3. Compila i suoi parametri. Un progetto o un prodotto si sceglie per nome tra quelli che la chiave può leggere; dove serve una persona, il tuo account viene inserito al posto tuo.
4. Premi play_arrowInvia richiesta. Lo stato e la risposta compaiono sotto.

Vengono proposte solo richieste di lettura, quindi provare non cambia nulla, e queste richieste non rientrano nel tuo utilizzo. Se la tua chiave non ha l'accesso che un endpoint richiede, la pagina ti avvisa che risponderà 403.

Webhook#

Un webhook avvisa il tuo server quando succede qualcosa, come le email di notifica avvisano te. I webhook fanno parte dei piani Enterprise e Open Guest.

Configurare un webhook#

In codeSviluppatori > webhookWebhook:

1. Scrivi il tuo URL dell'endpoint: un indirizzo https:// su internet. Gli indirizzi su reti private vengono rifiutati, e il controllo si ripete prima di ogni consegna.
2. Seleziona gli Eventi che vuoi (vedi eventi). Un nuovo endpoint parte con gli eventi che il tuo piano invia, e ne va selezionato almeno uno.
3. Premi saveSalva. La prima volta, la pagina mostra per intero il tuo Segreto di firma. Copialo subito: in seguito ne vengono mostrati solo gli ultimi caratteri.
4. Premi sendInvia evento di prova e scegli un evento.

Un test invia un esempio di quell'evento, con valori inventati e "test": true nel suo data, al tuo endpoint salvato, anche quando l'evento non è selezionato o l'endpoint è disattivato. Per fermare tutte le consegne, premi delete_outlineRimuovi: l'endpoint e il suo secret vengono eliminati.

Sotto le impostazioni, il Riferimento webhook contiene ciò che serve per scrivere la parte ricevente: le intestazioni e il corpo, il codice che verifica la firma in Node.js, Python e PHP, e dati di esempio per ogni evento.

Cosa riceve il tuo server#

Ogni evento è una POST al tuo endpoint, con un corpo JSON:

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

id è univoco per ogni evento, created indica quando è avvenuto in millisecondi dal 1° gennaio 1970 (UTC), e il contenuto di data dipende dall'evento. La richiesta ha anche queste intestazioni:

• Rispondi con uno stato 2xx entro 8 secondi, prima di qualsiasi lavoro lento. Qualsiasi altro stato, un reindirizzamento o un timeout conta come errore.
• Ogni evento viene inviato una volta e mai ritentato. La sezione mostra Ultima consegna e Errori consecutivi.
• Dopo 10 errori di fila, l'endpoint viene disattivato e il proprietario riceve un'email. Correggi il tuo server e premi saveSalva per riattivarlo.
• Ogni tanto un evento arriva due volte o fuori ordine. Usa id per ignorare le ripetizioni e created per mettere gli eventi in ordine.

Verificare la firma#

Chiunque conosca il tuo indirizzo può inviarvi dati, quindi verifica ogni consegna prima di fidartene:

1. Dividi l'intestazione X-MMO-Signature alla virgola in t e v1.
2. Calcola un HMAC-SHA256 di t, un punto e il corpo grezzo della richiesta, con il tuo signing secret come chiave, scritto in esadecimale.
3. Confronta il risultato con v1 usando un confronto a tempo costante.
4. Rifiuta la consegna se t dista più di 5 minuti dall'ora attuale. t è in millisecondi.

Usa il corpo esattamente come è arrivato: analizzare il JSON e riscriverlo lo modifica, e la firma non corrisponde più.

autorenewRuota il segreto sostituisce subito il secret e mostra quello nuovo per intero, una sola volta. Aggiorna il tuo server appena lo ruoti.

Eventi#