API_v3

Для работы с Мегапланом по API_v3 и обработки исходяших запросов на PHP доступна библиотека.

Здесь представлена общая информация про APIv3.

Описание всех методов и сущностей доступно внутри аккаунта Мегапалана по пути /api/v3/docs.

Описание формируется с учётом версии аккаунта Мегаплана, для текущей версии, можно посмотреть здесь.

Все ресурсы APIv3 доступны по URLs с префиксом /api/v3/, например: GET /api/v3/currency, возвращает JSON - массив сущностей валюты.

Вы можете посмотреть RAML-описание по адресу внутри аккаунта /api/v3 пример.

Все параметры запроса отправляются в виде JSON в теле запросов, а также в GET параметрах, например GET /api/v3/currency?{"limit": "3"}.

Базовый ответ API:

{
    "meta": {
        "status": 200,
        "errors": [ ],
        "pagination": {
            "count": 0,
            "limit": 100
        }
    },
    "data": [ ]
}

Ответ представляет собой два блока: meta и data.

Параметр data содержит данные ответа.

Параметр meta содержит дополнительную информацию:

Поле

Описание

status

Код ответа. Возможные варианта ответа приведены в таблице ниже

error

Описание ошибок

pagination

Информация о пагинации. Подробнее в разделе пагинации

Возможные коды ответа:

Код

Ответ

200

Успешный ответ

422

Ошибка в запросе

403

Ошибка доступа.

Время обработки запросов и таймауты

Время обработки вызова API зависит от настроек аккаунта, количества и сложности клиентских сценариев, выполняемых при создании или изменении объектов. Один и тот же запрос в разных аккаунтах может занимать разное время.

На стороне интеграции задавайте общий таймаут HTTP-запроса более 30 секунд. Рекомендуемое значение — 60 секунд на ожидание полного ответа API. Для аккаунтов со сложными сценариями может потребоваться больший таймаут: подбирайте его с учётом замеров времени выполнения запросов в конкретном аккаунте.

При таймауте на стороне интеграции операция на сервере могла выполниться. Перед повторной отправкой запроса на создание объекта проверьте результат предыдущего вызова, чтобы избежать создания дублей.

Аутентификация

Авторизационный токен нужно передавать с каждым запросом к API в заголовоке AUTHORIZATION:

AUTHORIZATION: Bearer MmMzNDc1NTQzN...

Получить токен можно двумя способами:

Для приложений, при установке - из входящего параметра data->token, см. <a href=»/apps/events.html#apps-events»>события приложений</a>

Для авторизации с использованием логина и пароля пользователя - запросом POST /api/v3/auth/access_token, используя grant_type=password:

Например:

curl --request POST \
    --url https://demo.megaplan.ru/api/v3/auth/access_token \
    --header 'content-type: multipart/form-data;' \
    --form username=dev-null@megoplan.ru \
    --form password=123 \
    --form grant_type=password

Ответ:

{
    "access_token": "YzE5OWEwM...",
    "expires_in": 172800,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "YTIzNTM4NW..."
}

Типы данных

APIv3 оперирует следующими типами данных:

Сущности

Сущность - это специальный тип данных для идентификации сложных ресурсов Мегаплана. Представляет из себя JSON объект с полям, среди которых обязательно присутствует contentType, который содержит название сущности. Для передачи вложенной сущности достаточно передать ее contentType и id. Все поддерживаемые сущности описаны в разделе сущности.

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

Скалярные типы Скалярные типы включают в себя: integer, float, string.

Специальные типы Тип any может включать в себя все возможные типы. Тип BaseEntity может включать в себя все возможные сущности.

Линк-сущности В качестве вложенных сущностей (которые предназначены для ссылок, а не для сохранений) API ожидает, так называемые, линк-сущности - это сущности, у которых есть всего два поля: ContentType и id, которые однозначно могут ссылаться на конкретную сущность.

Коллекция сущностей Представляет из себя массив сущностей определенного типа.

Объединение сущностей Представляет из себя объединение нескольких типов сущностей, которые могут быть одновременно в одном поле.

Объединение коллекций сущностей Представляет из себя коллекцию сущностей, которая может содержать одновременно несколько типов сущностей.

Пагинация

Для пагинации коллекции используйте следующие GET параметры в запросе:

https://demo.megaplan.ru/api/v3/example?{"limit": 100, "pageAfter": {...} ... }

limit указание макисмального количества сущностей в ответе. По умолчанию равен 100. pageAfter принимает линк-сущность и отобразит limit элементов, начиная с переданного. pageBefore принимает линк-сущность и отобразит limit элементов, перед переданным.

С пагинируемой коллекцией в metadata обязательно возвращается поле pagination с полями:

Поле

Описание

count

Общее количество сущностей по запросу

limit

Лимит количества сущностей в ответе

Загрузка файлов

В API3 в полях сущностей с типом файл устанавливается или отдаётся JSON с id и contentType сущности файл.

Например, вложения в сущности комментария

{
    contentType: "Comment"
    id: "777"
    attaches: [
        {
            contentType: "File",
            id: "888",
            mimeType: "image/jpeg"
            path: "/attach/SdfFileM_File/File/46/2/0f454c15da258dc3281f0a3c0bb2a1a2.jpeg/photo_2020-01-30%2019.13.10.jpeg",
            .......
        }
    ],
    ......
}

Для создания комментария или другой сущности с указанием файла, необходимо сначала загрузить файл, а потом указать сущность файла с contentType и id в создаваемой или изменяемой сущности.

Загрузка файла происходит через POST form-data:

curl 'https://demo.megaplan.ru/api/file'
-H 'content-type: multipart/form-data;'
-F 'files[]=@/path/to/file'

В ответ получаем id созданного файла. Используем потом его в нужной сущности при создании или редактировании