soil-dev/capsulemcp

Фильтруй возможности по структурированным условиям (веха, сумма, дата закрытия, теги). Используйте этот инструмент, а не search_opportunities, для вопросов вроде «последняя выигранная сделка», «сделки, закрытые в этом месяце», «воронка X на этапе Y». API Capsule не поддерживает сортировку на лету, но для запроса «самый последний X» можно отфильтровать по полю даты (например, {field: 'closedOn', operator: 'is within last', value: 90}) и выбрать строку с наибольшим id, идентификаторы Capsule монотонны, поэтому самый новый id = самая новая запись.

Фильтрует стороны по структурированным условиям (диапазоны дат, метки, поля). Используйте этот инструмент, а не search_parties, для вопросов вроде «самый новый клиент», «стороны, добавленные на этой неделе», «стороны с меткой VIP». API Capsule не поддерживает произвольную сортировку, но для «самого нового X» можно отфильтровать по полю с датой (например {field: 'addedOn', operator: 'is within last', value: 30}) и взять строку с наибольшим id — идентификаторы Capsule монотонны, поэтому самый новый id = самая новая запись.

Фильтрует проекты по структурированным условиям (диапазоны дат, статус, теги, владелец). Используйте этот инструмент, а не list_projects, для вопросов вроде «самый свежий проект», «проекты, открытые в этом месяце». API Capsule не поддерживает сортировку «на лету», но для «самых свежих X» можно отфильтровать по полю даты и выбрать строку с наибольшим ID: идентификаторы Capsule монотонны, поэтому новейший ID = новейшая запись.

Скачивает вложение по идентификатору. Возвращает содержимое изображения для типов image/* (Claude может описать его нативно); декодированный текст для text/* и application/json (небольшие файлы); JSON-метаданные + полезная нагрузка в base64 для других двоичных типов (PDF, документы Office и т.д.). Файлы, превышающие maxSizeBytes (по умолчанию 5 МБ), возвращают только метаданные с флагом truncated: true.

Показывает пользователя, владеющего API-токеном, который использует этот коннектор. Полезно для аудита («под какой Capsule-идентификацией работает коннектор?») и для подтверждения, что ротация токена передала владение ожидаемой учётной записи. Обёртка над Capsule GET /users/current: обратите внимание, что эндпоинт /users/current, а не /users/me.

Показывает одно ОПРЕДЕЛЕНИЕ пользовательского поля по id. Сначала используйте list_custom_fields, чтобы узнать идентификаторы полей.

Получает одну запись временной шкалы по её числовому ID. Возвращает полные данные: для заметки — текст тела; для захваченного письма — тему, тело, от/кому и временные метки; для записи выполненной задачи — исходные поля задачи. Полезно, когда у вас есть ID записи из одного из вызовов list_*_entries и вы хотите получить полное содержимое. Чтобы изменить тело или тип действия существующей записи, используйте update_entry; для удаления — delete_entry.

Пакетно загружает до 50 сделок по id. Для 1–10 id — один запрос к Capsule (родная конечная точка с множеством id); для 11–50 id коннектор прозрачно разбивает на части по 10 id и запускает параллельные запросы Capsule, поэтому вызывающий видит один вызов инструмента со всеми объединёнными результатами. Возвращает полную запись каждой сделки (сумма, этап, ответственный, сторона). Для одного id используйте get_opportunity.

Получает одну сделку по её числовому идентификатору. Возвращает полную запись, включая сумму, этап, ответственного, контрагента и любые встроенные теги/пользовательские поля. Используйте embed='tags,fields', чтобы включить их за один запрос. Для пакетного получения до 50 сделок за раз используйте get_opportunities.

Пакетно загружает до 50 parties по ID. Для 1-10 id — это один раунд-трип к Capsule (родная мульти-ID конечная точка); для 11-50 id коннектор прозрачно разбивает на куски по 10 id и параллельно рассылает запросы Capsule, так что вызывающая сторона видит один вызов инструмента со всеми объединёнными результатами. Используйте это, когда у Claude есть несколько ID parties, чтобы избежать N последовательных раунд-трипов get_party.

Получает одну сущность (человека или организацию) по её числовому идентификатору. Возвращает полную запись, включая тип, поля имени, email, телефоны, адреса, веб-сайты, а также любые встроенные теги или пользовательские поля. Используйте embed='tags,fields', чтобы включить их за один запрос. Для пакетного получения до 50 сущностей за раз используйте get_parties.

Получает один проект по его числовому идентификатору. Возвращает полную запись: имя, описание, статус (OPEN/CLOSED), владельца, этап, доску, opportunityId (если привязан) и временные метки. Используйте embed='tags,fields', чтобы одним запросом подключить прикреплённые теги и значения настраиваемых полей. Для пакетной загрузки до 50 проектов за раз используйте get_projects. Для временной шкалы проекта (заметки, захваченные письма, записи выполненных задач) используйте list_project_entries.

Пакетно извлекает до 50 проектов по идентификаторам. Для 1–10 ID это один обмен с Capsule; для 11–50 ID коннектор прозрачно разбивает на части по 10 ID и запускает параллельные запросы к Capsule, так что вызывающая сторона видит один вызов инструмента со всеми объединёнными результатами.

Возвращает аккаунт Capsule, к которому в данный момент аутентифицирован этот коннектор (поддомен, отображаемое имя, URL). Диагностика для вопроса «какой это аккаунт Capsule?». Для получения идентичности пользователя-владельца PAT используйте get_current_user.

Получает одну задачу по её числовому идентификатору. Возвращает описание задачи, срок выполнения, ответственного, статус завершения и сущность, к которой она привязана (контрагент/сделка/проект, если есть - отдельные задачи, не привязанные к записи, тоже допустимы). Для массового получения до 50 задач за раз используйте get_tasks.

Пакетная загрузка до 50 задач по их ID. Для 1–10 ID — это один запрос к Capsule; для 11–50 ID коннектор прозрачно разбивает их на блоки по 10 и распараллеливает запросы к Capsule, так что вызывающий видит один вызов инструмента со всеми объединёнными результатами.

Получить один экземпляр трека по id. Возвращает минимальную проекцию Capsule: id, description, trackDateOn, direction и массив задач, прикреплённых к треку. Capsule GET /tracks/{id} НЕ включает ссылку на trackDefinition, ссылку на сущность или поле completion. Чтобы найти сущность, к которой применяется трек, используйте list_entity_tracks (этот метод перечисляет экземпляры треков по их родительской сущности); чтобы проверить completion, используйте статусы самих задач трека как прокси.

Глобальная лента активности по всем сущностям: всё, что произошло в тенанте, сначала новые: типизированные строки (Заметка, Задача выполнена, Email отправлен, Email получен, плюс пользовательские типы) с указанием действующего пользователя, apiClient, который внёс изменение, и ссылок на соответствующую сделку/возможность/проект/задачу/запись. Поддерживает since (ISO-8601, серверный фильтр) и пагинацию. ИНСТРУМЕНТ для вопросов «что произошло на этой неделе по всей книге», «что <пользователь> трогал сегодня» или «какие письма приходили»: один вызов вместо запросов по каждой записи. Нет серверного фильтра по каждой сущности: фильтруйте на клиенте по возвращённым ссылкам. ПРЕДУПРЕЖДЕНИЕ: недокументированная конечная точка Capsule (стабильна в наблюдениях; обнаружена живым зондированием) может измениться без уведомления.

Выводит список всех настроенных типов активностей (например Call, Meeting, Email). Это категории, которые используются при записи записей на временной шкале через add_note. Возвращает id и name каждого типа. Набор настраивается в учётной записи, а не фиксированный enum, поэтому вызывайте этот метод, чтобы узнать допустимые значения перед указанием activityType при создании записи.

Список связей вторичных участников в сделке или проекте. 'Основной' участник находится в самой сущности (opportunity.party); дополнительные участники: например, партнёры, консультанты или рефереры, также участвующие в сделке. Установите сущность в 'opportunities' или 'projects'.

Возвращает список проектов, связанных с указанной возможностью. Возвращает ту же структуру записи, что и list_projects, отфильтрованную по одной opportunity. Обратное направление (project → opportunity) доступно напрямую через поле opportunity каждого проекта, так что этот инструмент нужен только для поиска проектов по opportunity — для поиска party → projects используйте list_party_projects.

Вывести все доски проектов, определенные в Capsule. Доска - это группировка этапов, через которые проходят проекты - аналог воронки сделок для проектов. Возвращает id, название и этапы каждой доски. Используйте это, чтобы узнать boardId при создании проекта, затем выберите начальный этап через list_stages. Как и воронки, доски стабильны для каждого аккаунта.

Выводит настроенные категории записей/задач (Call, Email, Meeting, Follow-up и т.д.) с их цветами. Возвращает идентификатор, название и цвет каждой категории. Набор настраивается на уровне аккаунта, а не фиксированным перечислением — вызывайте этот метод, чтобы узнать допустимые идентификаторы категорий, прежде чем ссылаться на один из них в add_note или create_task. Используется для маркировки и фильтрации записей временной шкалы и задач.

Выводит словарь стран Capsule (250 строк: name, alpha2Code, alpha3Code, numericCode, dialCode). Значения name - это ТОЧНЫЕ написания, принимаемые полями country адреса стороны: Capsule отклоняет всё остальное с ошибкой 422 'unknown country' (например, принимаются: 'Czechia', 'United Kingdom'; отклоняются: 'Czech Republic', 'UK'). Обращайтесь к этому словарю перед записями add_party_address / update_party_address, если не уверены в написании. Полный список в одном ответе; кэшируется (справочные данные).

Перечисляет словарь валют Capsule (80 строк: код ISO 4217, символ, название). Допустимые коды для opportunity value.currency. Полный список в одном ответе; кэшируется (справочные данные).

Выводит ОПРЕДЕЛЕНИЯ настраиваемых полей для типа сущности (parties, opportunities или projects). Возвращает схему: имя, тип, параметры для полей типа список и т.д., а НЕ значения для какой-либо конкретной записи. Чтобы прочитать значения в записи, используйте get_party / get_opportunity / get_project с параметром embed=fields.

Функция аудита: список возможностей, удалённых в указанный момент времени или после него. Параметр since ОБЯЗАТЕЛЕН. Ответ также включает ключ restrictedOpportunities для записей, которые пользователь интеграции не может прочитать полностью.

Функция аудита: список сторон, удалённых в указанную метку времени или после неё. Параметр since ОБЯЗАТЕЛЕН (Capsule отклоняет запрос без него). В ответ также входит ключ restrictedParties — записи, которые интеграционный пользователь видит как удалённые, но не может прочитать полностью.

Функция аудита: список проектов, удаленных в указанную временную метку или после нее. Параметр since ОБЯЗАТЕЛЕН. Ответ также включает ключ restrictedProjects для записей, которые пользователь интеграции не может прочитать полностью.

Выводит список людей, работающих в указанной организации (party). Возвращает записи (parties), поле organisation которых ссылается на переданный partyId. Используйте этот запрос, чтобы ответить на вопрос «кто работает в X?» вместо перечисления всех записей.

Перечисляет экземпляры треков для конкретной записи — то есть какие треки были применены к этой сделке / проекту / контрагенту. Отличается от list_track_definitions, который перечисляет шаблоны. ПРИМЕЧАНИЕ: на некоторых досках есть автоматизация по этапам, которая сама применяет треки, когда сущность попадает на определённый этап — треки, возвращаемые здесь, могут включать КАК треки, добавленные вручную (через apply_track), ТАК и треки, добавленные автоматически по правилам доски Capsule. Чтобы их различить, сравнивайте trackDefinition.id каждого трека с историей вызовов apply_track в вашем приложении.

Глобальная лента событий: все заметки, захваченные письма и записи о выполненных задачах по всей учётной записи Capsule, с постраничной разбивкой. Порядок по умолчанию: сначала самые новые. Используйте это для вопроса «какие действия произошли сегодня / на этой неделе по всей компании?» вместо перебора list_party_entries / list_opportunity_entries / list_project_entries.

Выводит список целей по продажам / активности, настроенных в аккаунте (целевые показатели по выручке или активности для каждого пользователя или команды). Возвращает пустой список для аккаунтов, которые не используют функцию Goals.

Перечисляет все настроенные причины потери сделки (например, 'Poor Qualification', 'Lost to competitor', 'Price too high'). Возвращает id и название каждой причины; набор настраивается на уровне аккаунта, а не фиксирован как перечисление, поэтому вызывайте эту команду, чтобы узнать допустимые id перед передачей lostReason в update_opportunity при закрытии сделки как проигранной. Полезно для анализа закрытых-проигранных сделок по причине.

Перечисляет этапы (стадии сделки) в рамках конкретного пайплайна сделок. Возвращает id, название, вероятность и позицию каждого этапа. Используется при создании сделок (передайте milestoneId в create_opportunity) или перемещении по этапам (укажите milestoneId в update_opportunity). Сначала узнайте pipelineId через list_pipelines. Этапы привязаны к пайплайну, не взаимозаменяемы между разными пайплайнами.

Выводит записи временной шкалы (заметки, захваченные письма, записи выполненных задач) для сделки. Возвращает записи от новых к старым. Каждая запись имеет тип ('note', 'email', 'task'), произвольный текст и временные метки. Используйте это, чтобы ответить на вопрос «что нового по сделке X?». Для временных шкал контрагента или проекта используйте соответственно list_party_entries или list_project_entries.

Выводит записи временной шкалы (заметки, захваченные письма, записи выполненных задач) для контрагента. Возвращает записи от новых к старым. У каждой записи есть тип ('note', 'email', 'task'), произвольный текст и временные метки. Используйте это, чтобы прочитать историю переписки с контактом или организацией — отвечает на вопросы вроде «что нового с X?». Для временных шкал сделок или проектов используйте list_opportunity_entries или list_project_entries соответственно. ВАЖНО для организаций: передайте includeLinkedPersons: true, чтобы отобразить записи, привязанные к связанным с организацией людям (письма в рамках продаж почти всегда попадают на запись человека, а не организации — API Capsule привязывает каждую запись ровно к одному контрагенту). Без этого флага организация с активной перепиской с клиентами будет выглядеть тихой, даже если её lastContactedAt актуален. Для любого запроса вида «что нового с $ORG?» установите includeLinkedPersons: true.

Перечисляет сделки, связанные с указанной стороной. Возвращает ту же структуру записей, что и get_opportunity, но с фильтром по одной стороне — используйте, чтобы ответить на вопрос «какие сделки у нас с X?», не перебирая все сделки. Принимает необязательный параметр embed (например, 'tags,fields'), чтобы включить их за один запрос.

Выводит проекты, связанные с указанной стороной. Возвращает ту же структуру записи, что и get_project, отфильтрованную по одной стороне — используйте это, чтобы ответить на вопрос «в каких проектах участвует X?» без перечисления всех проектов. Принимает необязательный параметр embed (например, 'tags,fields'). Для аналогичного вызова со стороны возможностей используйте list_party_opportunities.

Выводит список всех воронок продаж, определённых в Capsule CRM. Возвращает id, название и этапы сделок (упорядоченные по позиции) для каждой воронки. Используйте это, чтобы узнать pipelineId при создании сделки, затем выберите этап из той же воронки через list_milestones. Воронки стабильны для каждого аккаунта Capsule: выведите один раз и закешируйте; они редко меняются.

Выводит записи временной шкалы (заметки, захваченные письма, записи выполненных задач) для проекта. Возвращает записи от новых к старым. У каждой записи есть тип ('note', 'email', 'task'), текстовое содержимое и временные метки. Используйте это, чтобы ответить на вопрос «что нового по проекту X?». Для временных шкал контрагента или сделки используйте соответственно list_party_entries или list_opportunity_entries.

Перечисляет проекты в Capsule CRM, опционально отфильтрованные по статусу. Возвращает результаты в порядке по умолчанию Capsule (параметр сортировки здесь не поддерживается). Для поиска по произвольному тексту используйте search_projects. Для структурированных запросов (например, «последний проект», «проекты, открытые в этом месяце», «проекты с тегом X») используйте вместо этого filter_projects.

Перечисляет все фильтры, которые пользователи сохранили в веб-интерфейсе Capsule для типа сущности. Сохранённые фильтры многоразовые — они объединяют условия, колонки и (что важно) сортировку. Позволяет узнать, какие запросы уже настроены, перед созданием разового filter_* вызова.

Выводит этапы проектов. Без аргументов возвращает все этапы со всех досок (каждая запись содержит ссылку .board, чтобы их можно было различить). Передайте boardId, чтобы ограничить результат этапами одной конкретной доски. Используйте это, чтобы узнать числовой stage.id, который принимают create_project / update_project — одних названий этапов недостаточно, Capsule работает по идентификатору. Для этапов сделок (opportunities) используйте list_pipelines — у сделок нет этапов в смысле проектов.

Выводит список всех тегов, доступных для заданного типа сущности (parties, opportunities или projects). Возвращает id, имя и схему полей data-tag для каждого тега. Теги привязаны к типу сущности — тег для party нельзя использовать вместо тега для opportunity. Используйте эту команду, чтобы узнать корректные id тегов перед вызовом add_tag, или чтобы показать каталог тегов пользователю, когда он спрашивает «какие теги у нас есть?»

Выводит список задач в Capsule CRM. По умолчанию показывает OPEN-задачи; передайте статус, чтобы расширить выборку. Опционально можно отфильтровать по конкретному владельцу через ownerId. Capsule не предоставляет фильтр по сроку на этой точке входа: для этого используйте filter_*-инструменты в других местах или пройдитесь по списку.

Выводит список всех команд, настроенных в аккаунте Capsule. Полезно как входные данные для filter_*-запросов, фильтрующих по команде, а также для отчётов. ОГРАНИЧЕНИЕ: возвращает только идентификатор команды (id, name, description, timestamps). API Capsule v2 не раскрывает членство команда↔пользователь ни через одну конечную точку — GET /teams/{id}/users возвращает 404, embed=users игнорируется без уведомления, а GET /users/{id} не содержит поля teams. Чтобы определить, принадлежит ли пользователь к команде, либо проверьте страницу Team Membership в веб-интерфейсе Capsule, либо выполните пробу через update_project { ownerId: U, teamId: T } / batch_update_opportunity { items: [{ id: <любой opp>, ownerId: U, teamId: T }] } и прочитайте ответ — 422 'owner is not a member of the team' означает U ∉ T. Оба пути пробы применяют одно и то же ограничение членства на стороне сервера.

Перечисляет определения треков рабочего процесса: многократно используемые шаблоны, которые автоматически создают задачи через настроенные интервалы при применении к сделке или проекту. Каждый трек включает вложенные taskDefinitions, указывающие, что и когда создавать. Используйте это, чтобы понять, какие автоматизации существуют.

Выводит список всех пользователей в аккаунте Capsule. Возвращает id, username, опциональные имя/фамилию, роль и ссылку на party каждого пользователя. У некоторых пользователей поля имени/фамилии могут быть null (установлен только username) — тогда для отображения используйте username. Применяйте этот вызов, чтобы узнать id пользователей для запросов с фильтрацией по владельцу по сделкам, проектам и задачам, или чтобы сопоставить пользователя с его записью party через user.party.id.

Выполняет сохранённый фильтр по его идентификатору и возвращает результаты с пагинацией. В отличие от filter_parties / filter_opportunities / filter_projects (которые используют конечную точку для ad-hoc фильтров и НЕ МОГУТ сортировать), сохранённые фильтры ДЕЙСТВИТЕЛЬНО поддерживают сортировку — orderBy настраивается в веб-интерфейсе Capsule при создании фильтра. Поэтому вопросы вида 'самые последние X по Y' решаются одним вызовом, ЕСЛИ существует сохранённый фильтр; сначала используйте list_saved_filters, чтобы найти подходящий.

Поиск по свободному тексту или список возможностей в Capsule CRM. Возвращает результаты в порядке по умолчанию Capsule (параметр сортировки здесь не поддерживается). Для структурированных запросов — «самые свежие», «выигранные в этом квартале», «в воронке X на этапе Y» — используйте filter_opportunities.

Полнотекстовый поиск или вывод списка людей и организаций в Capsule CRM. Результаты возвращаются в порядке по умолчанию Capsule (сортировка не поддерживается). Для структурированных запросов — «последние», «помеченные X», «добавленные в этом месяце» — используйте filter_parties.

Поиск проектов в Capsule CRM по произвольному тексту (ищет по названию и описанию). Возвращает результаты в порядке по умолчанию Capsule (параметр сортировки здесь не поддерживается). Не указывайте q, чтобы вывести все проекты. Для структурированных запросов - 'самый недавний проект', 'проекты, открытые в этом месяце', 'проекты с тегом X' - используйте filter_projects.