REST API

REST API дає змогу вашій програмі робити те, що робить застосунок: проєкти та їхні вимірювання, папки й каталог продуктів; в Enterprise це ваша організація, як її веде сторінка Enterprise; в Open Guest це ваше гостьове посилання, гостьові проєкти та запити кошторису. Він відповідає у форматі JSON. Повна довідка з усіма полями та прикладами — це документація API; ця сторінка дає огляд.

Щоб відкрити документацію із застосунку, перейдіть у codeРозробник > apiREST API і натисніть menu_bookПереглянути документацію.

Базова адреса#

Кожен запит надсилається на:

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

Автентифікація#

Надсилайте свій ключ API як є в заголовку Authorization кожного запиту. Створіть ключ на сторінці розробника: див. ключі API.

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

Кожен запит перевіряється на відповідність доступу ключа (наприклад, Projects Читання), вашій підписці та, для запиту з вебсторінки, обмеженням вебсайтів ключа. Зберігайте ключі, що можуть змінювати дані, на своєму сервері: див. бережіть свій ключ.

Live і sandbox#

Для обох середовищ є одна базова адреса. Усе визначає ключ: ключ sandbox читає й записує проєкти, папки та продукти sandbox, яких робочі ключі ніколи не бачать. Користувачі, місця та команди вашої організації в обох середовищах ті самі, тому для їх зміни потрібен робочий ключ. Гостьові проєкти, створені ключем sandbox, ніколи не тарифікуються, а проєкти sandbox не можна вбудувати на ваш вебсайт. Токени повідомляють, до якого середовища належать.

Що охоплює API#

Кілька речей, які варто знати:

• Ключ дає доступ до проєктів власного облікового запису та, в Enterprise, до проєктів користувачів організації.
• Видалення проєкту поміщає його до Кошик, як у застосунку, і це може зробити лише його творець; видаліть його назавжди з Кошик за допомогою forever=true. Видалення папки поміщає її проєкти до Кошик.
• У вимірюваннях проєкту фігура перелічує свої продукти в productIds по порядку; productId — перший із них.
• /projects/{pid}/mmp повертає той самий файл .mmp, який експортує застосунок. Його схему опубліковано на github.com/blueblinkone/mmp-validator. Нові елементи додаються лише як необов’язкові, тож засіб читання, написаний для старішого файлу, продовжує працювати.
• В Open Guest гостьовий проєкт, запущений через API (POST /open-guest/projects), враховується у вашому використанні та бюджеті Open Guest так само, як проєкт, запущений за вашим гостьовим посиланням.
• В Open Guest у розділі person_pin_circleГостьове посилання є посібник Open Guest API із кодом для вашого сервера й сторінки: ваш сервер отримує токен із POST /auth/token за допомогою робочого ключа та спрямовує відвідувача на новий власний проєкт, з уже заповненими його даними.
• Люди потрапляють до вашої організації лише за запрошенням (POST /enterprise/invitations), як на сторінці Enterprise: хто не має облікового запису, тому він створюється, а пароль людина обирає сама. API ніколи не створює обліковий запис і не встановлює пароль.
• Вилучення користувача (POST /enterprise/users/{uid}/remove) залишає йому обліковий запис; видалення (DELETE /enterprise/users/{uid}) видаляє його. В обох випадках зроблена ним робота лишається в організації, в новій папці з його іменем, до якої мають доступ ваші адміністратори.
• Коли гість запитує ваш кошторис, GET /open-guest/requests/{pid} повідомляє, хто він, що написав, що виміряв і, за наявності Продукти: Читання, сам кошторис.
• В Open Guest токени запускають гостьові проєкти для ваших відвідувачів. POST /auth/iframe/token, що виконує вхід відвідувача у вбудовану карту, призначений для ключів Enterprise.
• Продукти через API ніколи не видаляються, лише архівуються, а собівартість продукту ніколи не повертається.
• Кадастрові ділянки не входять до API.

Відповіді та помилки#

Успішний запит відповідає статусом 200 і JSON (експорт .mmp відповідає XML). Невдалий відповідає статусом помилки й тілом на кшталт:

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

Спробуйте API зі сторінки розробника#

codeРозробник > terminalСпробувати API надсилає справжні запити з вашим ключем і показує, що саме приходить у відповідь.

1. Виберіть Робоче або Пісочниця.
2. Виберіть Кінцева точка, наприклад «Список ваших проєктів», «Отримати вимірювання» або «Отримати акаунт». Список пропонує кінцеві точки, що входять до вашого плану.
3. Заповніть його параметри. Проєкт чи продукт вибирається за назвою з тих, які ключ може читати; там, де потрібна людина, ваш власний обліковий запис підставляється за вас.
4. Натисніть play_arrowНадіслати запит. Нижче з’являються статус і відповідь.

Пропонуються лише запити на читання, тож спроби нічого не змінюють, а ці запити не враховуються у вашому використанні. Якщо ваш ключ не має доступу, потрібного кінцевій точці, сторінка попередить, що буде відповідь 403.

Вебхуки#

Вебхук повідомляє ваш сервер, коли щось відбувається, так само як листи-сповіщення повідомляють вас. Вебхуки входять до планів Enterprise і Open Guest.

Налаштуйте вебхук#

У codeРозробник > webhookВебхуки:

1. Введіть свою URL кінцевої точки: адресу https:// в інтернеті. Адреси у приватних мережах відхиляються, і це перевіряється знову перед кожною доставкою.
2. Позначте потрібні Події (див. події). Нова кінцева точка починається з подій, які надсилає ваш план, і має бути позначена принаймні одна.
3. Натисніть saveЗберегти. Перший раз сторінка показує Секрет підпису повністю. Скопіюйте його тоді: потім показуються лише його останні символи.
4. Натисніть sendНадіслати тестову подію і виберіть подію.

Тест надсилає зразок цієї події, зі вигаданими значеннями та "test": true у її data, на вашу збережену кінцеву точку, навіть якщо подію не позначено або кінцеву точку вимкнено. Щоб зупинити всі доставки, натисніть delete_outlineПрибрати: кінцеву точку та її секрет буде видалено.

Під налаштуваннями Довідник вебхуків містить усе, що потрібно для написання приймальної частини: заголовки й тіло, код перевірки підпису на Node.js, Python та PHP і приклади даних для кожної події.

Що отримує ваш сервер#

Кожна подія — це один POST на вашу кінцеву точку з тілом JSON:

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

id унікальний для кожної події, created — це момент події в мілісекундах від 1 січня 1970 року (UTC), а вміст data залежить від події. Запит також має такі заголовки:

• Відповідайте статусом 2xx протягом 8 секунд, перш ніж виконувати будь-яку повільну роботу. Будь-який інший статус, переадресація чи тайм-аут вважається невдачею.
• Кожну подію надсилають один раз і ніколи не повторюють. Розділ показує Остання доставка і Послідовні збої.
• Після 10 невдач поспіль кінцеву точку вимикають, а власник отримує лист. Виправте свій сервер і натисніть saveЗберегти, щоб увімкнути її знову.
• Іноді подія надходить двічі або не по порядку. Використовуйте id, щоб ігнорувати повтори, і created, щоб упорядковувати події.

Перевірте підпис#

Будь-хто, хто знає вашу адресу, може надсилати на неї запити, тому перевіряйте кожну доставку, перш ніж їй довіряти:

1. Розділіть заголовок X-MMO-Signature за комою на t і v1.
2. Обчисліть HMAC-SHA256 від t, крапки й необробленого тіла запиту, з вашим секретом підпису як ключем, записаний шістнадцятковим числом.
3. Порівняйте результат із v1 за допомогою порівняння сталого часу.
4. Відхиліть доставку, якщо t відрізняється від поточного часу більш ніж на 5 хвилин. t вказано в мілісекундах.

Використовуйте тіло в точності так, як воно надійшло: якщо розібрати JSON і записати його знову, він зміниться, і підпис не збігатиметься.

autorenewЗмінити секрет негайно замінює секрет і один раз показує новий повністю. Оновіть свій сервер одразу після заміни.

Події#