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

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

Поле	Описание
status	Код ответа. Возможные варианта ответа приведены в таблице ниже
error	Описание ошибок
pagination	Информация о пагинации. Подробнее в разделе пагинации

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

Код

Ответ

200

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

422

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

403

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

Код	Ответ
200	Успешный ответ
422	Ошибка в запросе
403	Ошибка доступа.

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

Авторизационный токен нужно передавать с каждым запросом к 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=[email protected] \
    --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

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

Поле	Описание
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 созданного файла. Используем потом его в нужной сущности при создании или редактировании