Мегаплан API v3: Создать клиента и сделку

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

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

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, а не просто числа.

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": "Заявка с сайта: поставка оборудования"}'

Базовые 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/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": "Описание"
}

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/program — Схемы сделок

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

Нюансы

• Ответ всегда в конверте 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://dev.megaplan.ru/apiv3/index.html Вся интеграция одним документом: https://mcp-everything.ru/integrations/megaplan.md