REST API

REST API позволяет вашим программам читать и изменять содержимое аккаунта Measure Map Online: проекты и их измерения, папки, каталог продуктов и, на тарифе Enterprise, участников вашей организации. Ответы приходят в формате JSON. Полный справочник со всеми полями и примерами — это документация по API; эта страница — обзор.

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

Базовый URL#

Все запросы отправляются на:

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"

Каждый запрос проверяется на соответствие доступу ключа (например, «Проекты: Чтение»), вашей подписке и — для запроса, отправленного с веб-страницы, — ограничениям ключа по сайтам. Ключи, которые могут изменять данные, храните на своём сервере: см. как защитить ключ.

Рабочая среда и песочница#

Базовый URL у них общий. Всё решает ключ: ключ песочницы читает и записывает проекты, папки и продукты песочницы, которых рабочие ключи никогда не видят. Участники в обеих средах одни и те же, но для входа от имени участника нужен рабочий ключ. Гостевые проекты, созданные ключом песочницы, никогда не оплачиваются, а проекты песочницы нельзя встроить на ваш сайт. Токены сообщают, к какой среде они относятся.

Что охватывает API#

Что нужно знать:

• Ключ имеет доступ к проектам своего аккаунта, а на тарифе Enterprise — и к проектам участников организации.
• Удаление проекта или папки через API окончательно: ничего не попадает в раздел «Корзина». Папка удаляется вместе с вложенными папками и проектами, которые принадлежат вашему аккаунту или вашим участникам.
• В измерениях проекта фигура перечисляет свои продукты в productIds по порядку; productId — первый из них.
• /projects/{pid}/mmp отдаёт тот же файл .mmp, который экспортирует приложение. Его схема опубликована на github.com/blueblinkone/mmp-validator. Новые элементы добавляются только как необязательные, поэтому программа, написанная для более старого файла, продолжает работать.
• На тарифе Open Guest проект, созданный через API с уровнем доступа Open Guest, учитывается в использовании и бюджете Open Guest так же, как проект, начатый по вашей гостевой ссылке.
• На тарифе Open Guest в разделе person_pin_circleГостевая ссылка есть руководство Open Guest API с кодом для вашего сервера и страницы: сервер получает токен через POST /auth/token с вашим рабочим ключом и отправляет посетителя в его собственный новый проект с уже заполненными данными.
• Создание участника через POST /users/new занимает место, как и приглашение, и даёт ему роль по умолчанию вашей организации.
• Токен от POST /auth/{uid}/login открывает аккаунт этого участника, поэтому для него нужен ключ, которому разрешено изменять участников, и никогда не ключ из ваших встроенных карт. Его не выдают для участников с ролью «Администратор» или «Менеджер», а также с ключом песочницы.
• Продукты через 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Сменить секрет сразу заменяет секрет и один раз показывает новый полностью. Обновите сервер сразу после смены секрета.

События#