REST API

REST API pozwala Twojemu oprogramowaniu robić to, co robi aplikacja: projekty i ich pomiary, foldery i katalog produktów; w planie Enterprise Twoją organizację, tak jak prowadzi ją strona Enterprise; w planie Open Guest Twój link dla gościa, projekty gości i prośby o wycenę. Odpowiada w formacie JSON. Pełna dokumentacja, z każdym polem i przykładem, to dokumentacja API; ta strona jest jej przeglądem.

Aby otworzyć dokumentację z aplikacji, przejdź do codeDeweloper > apiREST API i naciśnij menu_bookZobacz dokumentację.

Adres bazowy#

Każde żądanie trafia pod adres:

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

Uwierzytelnianie#

Wysyłaj swój klucz API, bez zmian, w nagłówku Authorization każdego żądania. Klucz utworzysz na stronie Developer: zobacz klucze API.

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

Każde żądanie jest sprawdzane pod kątem dostępu klucza (na przykład Projekty Odczyt), Twojej subskrypcji oraz, w przypadku żądania wysłanego ze strony internetowej, ograniczeń stron klucza. Klucze, które mogą zmieniać dane, trzymaj na swoim serwerze: zobacz dbaj o bezpieczeństwo klucza.

Live i sandbox#

Dla obu środowisk jest jeden adres bazowy. Decyduje klucz: klucz sandbox odczytuje i zapisuje projekty, foldery i produkty sandbox, których klucze live nigdy nie widzą. Użytkownicy, miejsca i zespoły Twojej organizacji są takie same w obu, więc ich zmiana wymaga klucza live. Projekty gości utworzone kluczem sandbox nigdy nie są rozliczane, a projektów sandbox nie można osadzić na Twojej stronie. Tokeny zawierają informację o środowisku, do którego należą.

Co obejmuje API#

Kilka rzeczy, o których warto wiedzieć:

• Klucz ma dostęp do projektów własnego konta i, w planie Enterprise, do projektów użytkowników organizacji.
• Usunięcie projektu przenosi go do kosza (Kosz), tak jak w aplikacji, i może to zrobić tylko jego twórca; usuń go na stałe z kosza (Kosz) za pomocą forever=true. Usunięcie folderu przenosi jego projekty do kosza (Kosz).
• W pomiarach projektu kształt wymienia swoje produkty w productIds, po kolei; productId to pierwszy z nich.
• /projects/{pid}/mmp daje ten sam plik .mmp, który eksportuje aplikacja. Jego schemat jest opublikowany pod adresem github.com/blueblinkone/mmp-validator. Nowe elementy są zawsze dodawane wyłącznie jako opcjonalne, więc czytnik napisany dla starszego pliku nadal działa.
• W planie Open Guest projekt gościa rozpoczęty przez API (POST /open-guest/projects) wlicza się do zużycia i budżetu Open Guest, tak jak projekt rozpoczęty z Twojego linku dla gościa.
• W Open Guest sekcja person_pin_circleLink dla gościa zawiera poradnik Open Guest API z kodem dla Twojego serwera i Twojej strony: serwer pobiera token przez POST /auth/token za pomocą klucza live i kieruje odwiedzającego do nowego, własnego projektu, z wypełnionymi jego danymi.
• Osoby dołączają do Twojej organizacji tylko przez zaproszenie (POST /enterprise/invitations), tak jak na stronie Enterprise: kto nie ma konta, dostaje je i sam wybiera hasło. API nigdy nie tworzy konta ani nie ustawia hasła.
• Usunięcie użytkownika z organizacji (POST /enterprise/users/{uid}/remove) zostawia mu konto; usunięcie go (DELETE /enterprise/users/{uid}) usuwa konto. W obu przypadkach jego praca zostaje w organizacji, w nowym folderze z jego nazwą, który współdzielą Twoi administratorzy.
• Gdy gość prosi o Twoją wycenę, GET /open-guest/requests/{pid} odpowiada, kim jest, co napisał, co zmierzył i, z Produkty: Odczyt, samą wycenę.
• W Open Guest tokeny rozpoczynają projekty gości dla Twoich odwiedzających. POST /auth/iframe/token, który loguje odwiedzającego w osadzonej mapie, jest przeznaczony dla kluczy Enterprise.
• Produkty nigdy nie są usuwane przez API, tylko archiwizowane, a cena zakupu produktu nigdy nie jest zwracana.
• Działki katastralne nie są częścią API.

Odpowiedzi i błędy#

Udane żądanie odpowiada statusem 200 i JSON-em (eksport .mmp odpowiada XML-em). Nieudane odpowiada statusem błędu i treścią w rodzaju:

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

Wypróbuj API na stronie Developer#

codeDeweloper > terminalWypróbuj API wysyła prawdziwe żądania z Twoim kluczem i pokazuje dokładnie, co wraca.

1. Wybierz Produkcyjne lub Piaskownica.
2. Wybierz Punkt końcowy, na przykład „Lista Twoich projektów”, „Pobierz pomiary” lub „Pobierz konto”. Lista oferuje endpointy, które obejmuje Twój plan.
3. Wypełnij jego parametry. Projekt lub produkt wybierasz po nazwie spośród tych, które klucz może odczytać; tam, gdzie potrzebna jest osoba, Twoje własne konto jest wypełniane za Ciebie.
4. Naciśnij play_arrowWyślij żądanie. Status i odpowiedź pojawią się poniżej.

Dostępne są tylko żądania odczytu, więc próbowanie niczego nie zmienia, a te żądania nie są wliczane do Twojego wykorzystania. Jeśli Twój klucz nie ma dostępu, którego wymaga endpoint, strona ostrzega, że odpowie 403.

Webhooki#

Webhook informuje Twój serwer, gdy coś się dzieje, tak jak e-maile z powiadomieniami informują Ciebie. Webhooki są częścią planów Enterprise i Open Guest.

Skonfiguruj webhook#

W codeDeweloper > webhookWebhooki:

1. Wpisz swój Adres punktu końcowego: adres https:// w internecie. Adresy w sieciach prywatnych są odrzucane, a sprawdzane jest to ponownie przed każdym dostarczeniem.
2. Zaznacz Zdarzenia, które chcesz otrzymywać (zobacz zdarzenia). Nowy endpoint zaczyna od zdarzeń, które wysyła Twój plan, a co najmniej jedno musi być zaznaczone.
3. Naciśnij saveZapisz. Za pierwszym razem strona pokazuje Twój Klucz podpisujący w całości. Skopiuj go wtedy: potem widać tylko jego ostatnie znaki.
4. Naciśnij sendWyślij zdarzenie testowe i wybierz zdarzenie.

Test wysyła próbkę tego zdarzenia, z wymyślonymi wartościami i "test": true w data, na zapisany endpoint, nawet gdy zdarzenie nie jest zaznaczone lub endpoint jest wyłączony. Aby zatrzymać wszystkie dostarczenia, naciśnij delete_outlineUsuń: endpoint i jego klucz tajny zostają usunięte.

Pod ustawieniami Dokumentacja webhooków zawiera wszystko, czego potrzebujesz do napisania strony odbierającej: nagłówki i treść, kod sprawdzający podpis w Node.js, Pythonie i PHP oraz przykładowe dane dla każdego zdarzenia.

Co otrzymuje Twój serwer#

Każde zdarzenie to jedno żądanie POST na Twój endpoint, z treścią JSON:

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

id jest unikalne dla każdego zdarzenia, created to moment zdarzenia w milisekundach od 1 stycznia 1970 (UTC), a zawartość data zależy od zdarzenia. Żądanie ma też te nagłówki:

• Odpowiedz statusem 2xx w ciągu 8 sekund, przed jakąkolwiek powolną pracą. Każdy inny status, przekierowanie lub przekroczenie czasu liczy się jako niepowodzenie.
• Każde zdarzenie jest wysyłane raz i nigdy ponawiane. Sekcja pokazuje Ostatnie dostarczenie i Kolejne niepowodzenia.
• Po 10 niepowodzeniach z rzędu endpoint zostaje wyłączony, a właściciel dostaje e-mail. Napraw serwer i naciśnij saveZapisz, aby włączyć go ponownie.
• Czasem zdarzenie przychodzi dwa razy lub w złej kolejności. Użyj id, aby ignorować powtórzenia, i created, aby ustawić zdarzenia w kolejności.

Sprawdź podpis#

Każdy, kto zna Twój adres, może na niego wysyłać żądania, więc sprawdzaj każde dostarczenie, zanim mu zaufasz:

1. Podziel nagłówek X-MMO-Signature na przecinku na t i v1.
2. Oblicz HMAC-SHA256 z t, kropki i surowej treści żądania, z Twoim kluczem tajnym do podpisywania jako kluczem, zapisany szesnastkowo.
3. Porównaj wynik z v1 porównaniem w stałym czasie.
4. Odrzuć dostarczenie, jeśli t różni się od bieżącego czasu o więcej niż 5 minut. t jest w milisekundach.

Używaj treści dokładnie takiej, w jakiej przyszła: sparsowanie JSON-a i zapisanie go z powrotem zmienia go, a podpis przestaje się zgadzać.

autorenewZmień klucz tajny natychmiast wymienia klucz tajny i pokazuje nowy w całości, jednorazowo. Zaktualizuj serwer zaraz po wymianie.

Zdarzenia#