---
slug: "megaplan"
name: "Мегаплан API v3"
vendor: "Мегаплан"
industry: "crm"
docsUrl: "https://dev.megaplan.ru/apiv3/index.html"
version: 2
updatedAt: "2026-10-24"
---

# Мегаплан API v3

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

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

## Сценарии

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

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

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

```bash
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
      }'
```

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

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

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

```bash
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: открытые, по ответственному, с нужными полями.

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

```bash
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` | Ошибка в запросе |

## Источники

- [API v3](https://dev.megaplan.ru/apiv3/index.html)
- [Документация для разработчиков](https://dev.megaplan.ru/)
- [Официальный PHP SDK с примерами запросов](https://github.com/megaplan/megaplansdk)

---

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