# Мегаплан API v3: Выгрузить задачи с фильтром и постранично

Сценарий из mcp-everything. Актуально на 2026-10-24.

Забрать задачи в отчёт или 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
```

## Методы сценария

### 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 |

## Нюансы

- Ответ всегда в конверте `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`.
- Пример ответа:

## Другие сценарии

- [Поставить задачу сотруднику](https://mcp-everything.ru/integrations/megaplan/scenarios/postavit-zadachu-sotrudniku.md)
- [Создать клиента и сделку](https://mcp-everything.ru/integrations/megaplan/scenarios/sozdat-klienta-i-sdelku.md)

---

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