Мегаплан API v3 API

Отрасль: CRM и продажи. Актуально на 2026-10-24.

REST API системы управления задачами, проектами и сделками Мегаплан: задачи, проекты, сделки и схемы сделок, клиенты (компании и люди), сотрудники, комментарии, файлы. Запросы выполняются к адресу конкретного аккаунта с префиксом /api/v3/. Все сущности — JSON-объекты с полем contentType, а ссылки на другие сущности передаются «ссылочными» объектами из contentType и id.

Сценарии

Поставить задачу сотруднику

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

Получи токен: POST /api/v3/auth/access_token с username, password и grant_type = password (multipart-форма). Токен живёт 48 часов — сохрани его и обновляй заранее. Передавай в заголовке AUTHORIZATION: Bearer .
Найди ответственного: GET /api/v3/employee — в ответе id сотрудников.
Создай задачу: POST /api/v3/task с contentType = Task, name и responsible — ссылочным объектом {"contentType": "Employee", "id": ...}. Описание — subject, срочность — isUrgent.
Ответ приходит в конверте meta + data: id новой задачи — в data.id, ошибки — в meta.
Чтобы поменять задачу, отправь POST /api/v3/task/{id} с изменяемыми полями — Мегаплан меняет сущности POST-запросом на их адрес, а не PUT или PATCH.

TOKEN=$(curl -s -X POST https://<аккаунт>.megaplan.ru/api/v3/auth/access_token \
  -F username=<логин> -F password=<пароль> -F grant_type=password | jq -r .access_token)

curl -X POST https://<аккаунт>.megaplan.ru/api/v3/task \
  -H "AUTHORIZATION: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
        "contentType": "Task",
        "name": "Перезвонить клиенту по заявке с сайта",
        "responsible": {"contentType": "Employee", "id": 1000003},
        "subject": "Иван Петров, +7 999 000-11-22, интересуется доставкой",
        "isUrgent": true
      }'

Создать клиента и сделку

Заявка превращается в клиента-компанию и сделку по нужной схеме.

Узнай схему сделки: GET /api/v3/program — у каждой схемы свой id и набор этапов.
Создай клиента: POST /api/v3/contractorCompany с contentType = ContractorCompany, name и contactInfo — списком контактов (type = email или phone, value, isMain).
Создай сделку: POST /api/v3/deal с contentType = Deal, program (схема), manager (сотрудник) и contractor — ссылкой на созданного клиента {"contentType": "ContractorCompany", "id": ...}.
Все ссылки на другие сущности — ссылочные объекты из contentType и id, а не просто числа.

curl -X POST https://<аккаунт>.megaplan.ru/api/v3/contractorCompany \
  -H "AUTHORIZATION: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"contentType": "ContractorCompany", "name": "ООО \"Ромашка\"",
       "contactInfo": [{"contentType": "ContactInfo", "isMain": true, "type": "email", "value": "info@romashka.ru"}]}'

curl -X POST https://<аккаунт>.megaplan.ru/api/v3/deal \
  -H "AUTHORIZATION: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"contentType": "Deal",
       "program": {"contentType": "Program", "id": 8},
       "manager": {"contentType": "Employee", "id": 1000003},
       "contractor": {"contentType": "ContractorCompany", "id": 1000666},
       "description": "Заявка с сайта: поставка оборудования"}'

Выгрузить задачи с фильтром и постранично

Забрать задачи в отчёт или BI: открытые, по ответственному, с нужными полями.

Запроси список: GET /api/v3/task. Параметры передаются JSON-объектом прямо в строке запроса — его нужно URL-кодировать.
Фильтр — объект с contentType = TaskFilter и условиями в config.termGroup.terms. Чтобы ответ был легче, передай fields со списком полей и onlyRequestedFields = true.
Пагинация курсорная: для следующей страницы передай pageAfter — ссылочный объект последней полученной задачи ({"contentType": "Task", "id": ...}), а не номер страницы. Размер страницы — limit, по умолчанию 100.
Коллекции отдают только базовые поля; полную карточку получай через GET /api/v3/task/{id}.

Q='{"fields": ["name", "status", "deadline", "responsible"], "onlyRequestedFields": true, "limit": 100}'
curl -G "https://<аккаунт>.megaplan.ru/api/v3/task" \
  -H "AUTHORIZATION: Bearer $TOKEN" \
  --data-urlencode "$Q"

# Следующая страница — после последней задачи из предыдущего ответа
Q='{"limit": 100, "pageAfter": {"contentType": "Task", "id": 1000245}}'
curl -G "https://<аккаунт>.megaplan.ru/api/v3/task" -H "AUTHORIZATION: Bearer $TOKEN" --data-urlencode "$Q"

Базовые URL

Боевой: https://<ваш-аккаунт>.megaplan.ru/api/v3/
Тестовый (демо-аккаунт): https://demo.megaplan.ru/api/v3/

Авторизация

Тип: Bearer-токен

Токен передаётся в каждом запросе в заголовке AUTHORIZATION: Bearer <token>. Для авторизации по логину и паролю токен получают запросом POST /api/v3/auth/access_token с grant_type=password; он живёт 48 часов (expires_in 172800). Приложения Мегаплана получают токен в data->token событий приложения.

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

Методы

POST /api/v3/auth/access_token — Получение токена

В ответе: access_token, expires_in, token_type, scope, refresh_token.

Параметр	Где	Тип	Обяз.	Описание
`username`	body	string	да	Логин пользователя
`password`	body	string	да	Пароль
`grant_type`	body	string	да	password

GET /api/v3/task — Список задач

Параметры передаются JSON-объектом в GET-параметрах.

Параметр	Где	Тип	Обяз.	Описание
`filter`	query	object	нет	Фильтр с contentType: "TaskFilter" и config.termGroup.terms — условия по полям (userCreated, responsible, status и др.)
`onlyRequestedFields`	query	boolean	нет	Отдавать только запрошенные поля
`fields`	query	array	нет	Список запрашиваемых полей
`limit`	query	integer	нет	Размер страницы, по умолчанию 100
`pageAfter`	query	object	нет	Ссылочная сущность, после которой начать страницу
`pageBefore`	query	object	нет	Ссылочная сущность, до которой выдать страницу

GET /api/v3/task/{id} — Карточка задачи

Коллекции возвращают только базовые поля; полный набор — в карточке.

Параметр	Где	Тип	Обяз.	Описание
`id`	path	integer	да	ID задачи
`onlyRequestedFields`	query	boolean	нет	Отдавать только запрошенные поля
`fields`	query	array	нет	Поля, например name, status, deadline, responsible

POST /api/v3/task — Создать задачу

Параметр	Где	Тип	Обяз.	Описание
`contentType`	body	string	да	Task
`name`	body	string	да	Название задачи
`responsible`	body	object	да	Ответственный: {"contentType": "Employee", "id": ...}
`subject`	body	string	нет	Описание
`isUrgent`	body	boolean	нет	Срочная
`isTemplate`	body	boolean	нет	Шаблон
`Category...CustomField...`	body	any	нет	Расширенные (пользовательские) поля

Пример запроса:

{
    "contentType": "Task",
    "name": "Название задачи",
    "responsible": {
        "contentType": "Employee",
        "id": 1000003
    },
    "subject": "Описание задачи",
    "isUrgent": false,
    "isTemplate": false
}

POST /api/v3/task/{id} — Изменить задачу

Изменение выполняется POST-запросом на адрес задачи с изменяемыми полями.

Параметр	Где	Тип	Обяз.	Описание
`id`	path	integer	да	ID задачи
`name`	body	string	нет	Новое название

DELETE /api/v3/task/{id} — Удалить задачу

Параметр	Где	Тип	Обяз.	Описание
`id`	path	integer	да	ID задачи

POST /api/v3/deal — Создать сделку

Параметр	Где	Тип	Обяз.	Описание
`contentType`	body	string	да	Deal
`program`	body	object	да	Схема сделки: {"contentType": "Program", "id": ...}
`manager`	body	object	нет	Менеджер: {"contentType": "Employee", "id": ...}
`contractor`	body	object	нет	Клиент: {"contentType": "ContractorCompany", "id": ...}
`description`	body	string	нет	Описание

Пример запроса:

{
    "contentType": "Deal",
    "program": {
        "contentType": "Program",
        "id": 8
    },
    "manager": {
        "contentType": "Employee",
        "id": 1000003
    },
    "contractor": {
        "contentType": "ContractorCompany",
        "id": 1000666
    },
    "description": "Описание"
}

GET /api/v3/deal — Список сделок

Параметр	Где	Тип	Обяз.	Описание
`filter`	query	object	нет	Фильтр с contentType: "TradeFilter"; условия по manager, state и др.; для расширенных полей — program
`limit`	query	integer	нет	Размер страницы

POST /api/v3/contractorCompany — Создать клиента-компанию

Параметр	Где	Тип	Обяз.	Описание
`contentType`	body	string	да	ContractorCompany
`name`	body	string	да	Название
`contactInfo`	body	array	нет	Контакты: contentType: "ContactInfo", type (например email), value, isMain

Пример запроса:

{
    "contentType": "ContractorCompany",
    "name": "ООО \"Ромашка\"",
    "contactInfo": [{
        "contentType": "ContactInfo",
        "isMain": true,
        "type": "email",
        "value": "romashka45986521@gmail.com"
    }]
}

GET /api/v3/employee — Список сотрудников

Список сотрудников аккаунта; карточка — GET /api/v3/employee/{id}.

GET /api/v3/program — Схемы сделок

Список схем сделок; карточка — GET /api/v3/program/{id}.

POST /api/file — Загрузка файла

Загрузка файла multipart-формой (поле files[]). В ответе — id файла, который затем указывают в создаваемой сущности вместе с contentType.

Пример запроса:

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

Нюансы

Ответ всегда в конверте meta + data: в meta — status, ошибки и pagination (count, limit).
Параметры GET-запросов передаются JSON-объектом прямо в строке запроса, например GET /api/v3/currency?{"limit": "3"}.
Пагинация курсорная: pageAfter/pageBefore принимают ссылочную сущность (contentType + id), а не номер страницы.
Коллекции отдают только базовые поля; для полного набора запросите карточку по id или передайте fields.
Изменение сущности — POST на её адрес (/api/v3/task/{id}), а не PUT или PATCH.
Пользовательские поля имеют имена вида Category130CustomField...; для фильтра по расширенным полям сделок нужно указать схему program.
Полный список сущностей и эндпоинтов публикуется на каждом аккаунте: /api/v3/docs; RAML-описание — /api/v3.
Пример ответа:

Ошибки

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

Источники

Если этого недостаточно — официальная документация: https://dev.megaplan.ru/apiv3/index.html JSON: https://mcp-everything.ru/api/integrations/megaplan. MCP: https://mcp-everything.ru/mcp