Alitos API v1 для ГЦК - Alitos Документация

Alitos External API позволяет серверной интеграции работать с кабинетами ГЦК от имени пользователя Alitos: получать аналитику проектов и источников B4, читать и экспортировать сделки, импортировать телефоны как новые сделки, создавать проекты и менять поддерживаемые настройки.

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

Контракт: 2026-10-22.1. API предназначен для серверных приложений.

Выберите сценарий

Быстрый старт — получите JWT и найдите первый кабинет.
Ключи доступа и авторизация — создайте ключ, выберите права и кабинеты, замените или отзовите доступ.
Аналитика проектов и источников B4 — получите показатели за период и полный результат по источникам B4.
Чтение и экспорт сделок — найдите сделки или выгрузите их JSON-строками.
Импорт сделок в Архив — создайте новые сделки из списка телефонов и проверьте итог импорта.
Фоновые операции и ошибки — дождитесь результата и обработайте сбои без повторного создания работы.

Импорт новых сделок и изменение статусов существующих — разные действия. Изменение статусов не входит в REST v1; в Alitos MCP для него есть отдельные инструменты. REST и MCP используют разные токены доступа.

Адреса и контракт

Назначение	Адрес
Управление ключами и обмен на JWT	`https://api.alitos.io`
Запросы к кабинетам	`https://api.alitos.io/v1/external`
Поля, типы и ограничения	OpenAPI v1

OpenAPI определяет точный контракт запросов и ответов. Руководства объясняют порядок действий. Внутри /v1 возможны совместимые добавления: игнорируйте неизвестные поля ответа и не полагайтесь на порядок полей JSON.

Права и основные методы

Доступ требует одновременно четырёх условий:

У пользователя есть право external_api_access.
JWT содержит scope нужной операции, разрешённый ключом доступа.
Кабинет входит в cabinetAllowlist ключа либо доступен владельцу в режиме all_current.
Пользователь по-прежнему может выполнить это действие в выбранном кабинете.

Scope — ограничение набора действий, а не выдача прав на кабинет. Проверка доступа повторяется перед выполнением фоновой операции и при чтении её результата.

Пути ниже указаны относительно https://api.alitos.io/v1/external.

Задача	Метод	Scope
Проверить доступность API и лимиты	`GET /capabilities`	Любой выданный scope
Найти кабинеты	`GET /cabinets`, `POST /cabinets/search`	`cabinet:read`
Прочитать контекст кабинета	`GET /cabinets/{cabinetId}/context`	`cabinet:read`
Прочитать настройки	`GET /cabinets/{cabinetId}/settings`	`cabinet:read`
Получить аналитику проектов	`POST /analytics/projects/query`	`cabinet:read`
Получить аналитику источников B4	`POST /analytics/sources/jobs`	`cabinet:exports:run`
Найти сделки и контактные данные	`POST /cabinets/{cabinetId}/deals/search`	`cabinet:deals:read`
Экспортировать сделки	`POST /cabinets/{cabinetId}/deals/export-jobs`	`cabinet:exports:run`
Импортировать новые сделки	`POST /gck/cabinets/{cabinetId}/deals/import-jobs`	`cabinet:deals:write`
Создать проекты, изменить источники или состояния	Методы создания и изменения проектов в OpenAPI	`cabinet:projects:write`
Изменить настройки или конфигурацию аналитики	Методы `settings/updates` и `analytics-config/updates` кабинета	`cabinet:settings:write`
Прочитать состояние или результат операции	`GET /operations/{operationId}`, `GET /operations/{operationId}/result`	Scope исходной операции

Общие правила

Передавайте cabinetId и другие 64-битные идентификаторы ГЦК JSON-строками: JavaScript number может потерять точность.
Для запуска фоновой операции обязательны причина в reason и постоянный Idempotency-Key. Повтор того же запроса использует тот же ключ.
Полный результат B4 читается одним ответом через result?view=all, без пагинации. Экспорт сделок читается по страницам; передавайте nextCursor без разбора и изменения фильтров.
Для защищённых изменений сначала получите сильный ETag, затем передайте его в If-Match. Порядок действий и точные условия описаны в условных запросах.
Для чтения источников используйте view=read; для подготовки изменения — view=edit. Различия и ограничения — в справочнике источников.

Если кабинет найден в нескольких контекстах, используйте полученные при поиске namespaceId и placementId в методах, которые их принимают. Сохраняйте выбранный контекст на протяжении пагинации и повторов одной операции.

При запуске интеграции прочитайте /capabilities: он сообщает выданные scopes, доступные группы операций и текущие лимиты. Доступность группы API не заменяет проверку прав на конкретный кабинет.

Храните ключ доступа в хранилище секретов, JWT — в памяти процесса. JWT действует 60 минут; refresh token не выдаётся. Не включайте ключи и JWT в клиентские приложения или репозиторий, не записывайте их и контактные данные в логи. Произвольные запросы к ГЦК и доступ к его сессиям через этот API не предоставляются.