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

External API дает серверным интеграциям контролируемый доступ к ГЦК-кабинетам пользователя Alitos.

Через API можно находить кабинеты, читать данные, менять разрешенные настройки и запускать асинхронные операции. Произвольный прокси к ГЦК и доступ к сессиям не предоставляются.

Контракт: 2026-08-09.5. API предназначен только для server-to-server интеграций.

Начните с нужного сценария

Быстрый старт - первый успешный запрос

с минимальными правами.

Ключи доступа и авторизация - credentials, JWT, scopes, ограничения по кабинетам и отзыв доступа.

Импорт сделок в ГЦК - запрос, нормализация телефонов, polling и результат операции.

Асинхронные операции и ошибки - idempotency, ETag, повторные запросы и RFC 7807.

OpenAPI v1 - полный wire-контракт.

Адреса

Назначение	URL
Управление ключами и обмен на JWT	`https://api.alitos.io`
External API	`https://api.alitos.io/v1/external`
OpenAPI	`https://api.alitos.io/v1/external/openapi.yaml`

OpenAPI является источником истины для полей, типов, ограничений и кодов ответа. Руководства объясняют порядок вызовов, но не расширяют контракт.

Модель доступа

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

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

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

Scope	Назначение
`cabinet:read`	Кабинеты, контекст, настройки, проекты и аналитика
`cabinet:projects:write`	Создание проектов, источники и состояния
`cabinet:settings:write`	Разрешенные настройки и analytics config
`cabinet:deals:read`	Сделки и чувствительные контактные данные
`cabinet:deals:write`	Импорт номеров как новых сделок ГЦК
`cabinet:exports:run`	Экспорт сделок и аналитика источников

Карта API

Все пути в таблице относятся к https://api.alitos.io/v1/external.

Сценарий	Основные endpoints	Scope
Возможности	`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`
Сделки	`POST /cabinets/{cabinetId}/deals/search`	`cabinet:deals:read`
Импорт сделок в ГЦК	`POST /gck/cabinets/{cabinetId}/deals/import-jobs`	`cabinet:deals:write`
Экспорт	`POST /cabinets/{cabinetId}/deals/export-jobs`	`cabinet:exports:run`
Проекты	`/project-creation/`, `/projects/-updates`	`cabinet:projects:write`
Изменение настроек	`/settings/updates`, `/analytics-config/updates`	`cabinet:settings:write`
Операции	`GET /operations/{operationId}`	Scope исходной операции

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

cabinetId и другие 64-битные идентификаторы ГЦК передаются JSON-строками.
Cursor непрозрачен. Передавайте его без разбора с теми же фильтрами.
Для создания фоновой операции обязательны reason и Idempotency-Key.
Для защищенных изменений используйте сильный ETag и If-Match.
JWT действует 60 минут. Refresh token не выдается.
Ключи, JWT, телефоны и другие чувствительные данные нельзя записывать в логи.

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

Доступность и совместимость

GET /capabilities возвращает выданные scopes, доступные группы операций и текущие лимиты. Проверяйте этот ответ при запуске интеграции, а не храните rollout-флаги в клиентском коде.

Внутри /v1 разрешены только совместимые добавления. Клиент должен игнорировать неизвестные поля ответа и не полагаться на порядок JSON properties.

Полный контракт: OpenAPI v1.