Интеграции

Expecto общается с внешними платформами в двух направлениях:

• Context — перед обработкой поставки Expecto читает справочные данные из внешней системы и кладёт их в контекст сессии: сальдо прошлого месяца из хранилища, номер фонда из API мастер-данных, курс валюты из отчётной базы. Бизнес-правила и трансформеры используют эти значения как любой другой контекст.
• Outbound — когда сессия проходит веху (проверки пройдены, стадия упала, пакет экспортирован), Expecto записывает запись во внешнюю платформу: статус в Salesforce, строку в операционную таблицу.

Оба направления собираются из одних и тех же трёх кирпичиков.

Кирпичики

Кирпичик	Где живёт	Что хранит
Connection (подключение)	Организация (Settings → Connections)	Как добраться до одной внешней системы: тип, URL или DSN, учётные данные, настройки провайдера. Учётные данные хранятся зашифрованными и больше не показываются.
Context source (источник контекста)	Проект (Project → Context)	Запрос к подключению с плейсхолдерами {{ … }} и контекстная таблица или скаляр, которые он производит.
Outbound binding (исходящая привязка)	Проект (Project → Context → Outbound Bindings)	Какие события сессии слать в какое подключение и как формировать полезную нагрузку.

Тип подключения определяет, что оно умеет. Каждый тип реализован адаптером, который объявляет свои возможности:

Платформа	Тип	Возможности	Страница
Salesforce	salesforce	outbound	Salesforce
BuiltAPI	builtapi	context	BuiltAPI
PostgreSQL	postgres	context	PostgreSQL

Источник контекста должен ссылаться на подключение с возможностью context, исходящая привязка — на подключение с возможностью outbound; иное отклоняется при сохранении с понятным сообщением. Актуальный каталог с возможностями и полями формы отдаёт GET /api/integration-connections/types (и MCP-инструмент list_connection_types), поэтому клиенты его не захардкоживают.

Кому что можно

Действие	Нужно
Создавать, редактировать, тестировать, удалять подключения; редактировать источники контекста и исходящие привязки	Право integrations:manage — есть у ролей owner и admin
Видеть исходящие привязки и их лог доставок в Settings → Webhooks	webhooks:manage (тоже owner/admin)

Подключения

Откройте Settings → Connections. Каждая строка показывает тип, бейдж возможности (context / outbound), активно ли подключение и заданы ли учётные данные.

Add Connection открывает форму, поля которой берутся из каталога типов — сначала выберите тип, и форма подстроится: My Domain URL плюс Consumer Key / Secret для Salesforce, базовый URL плюс сервисный токен и id workspace для BuiltAPI, DSN плюс пароль для PostgreSQL.

Учётные данные только на запись

Всё, что вы вводите как секрет, шифруется на диске и не возвращается ни одной операцией чтения — API отдаёт только has_credentials: true. Чтобы ротировать секрет, введите новый в Edit; чтобы стереть — используйте clear_credentials. Секреты никогда не попадают в логи, записи доставок и сообщения об ошибках.

Test выполняет самый дешёвый аутентифицированный вызов, который допускает платформа, ничего не меняя на той стороне: запрос токена для Salesforce, запрос списка на одну строку для BuiltAPI, SELECT 1 в read-only-транзакции для PostgreSQL. Результат — одно из:

error_kind	Значение
(ok)	Система доступна, аутентификация прошла.
connection_error	Недоступна, тайм-аут или ответ 5xx.
auth_error	Учётные данные отклонены.
query_error	Конфигурация подключения неполная (например, нет workspace_id для BuiltAPI).

Можно проверить и ещё не сохранённые данные — та же кнопка Test connection в диалоге создания или POST /api/integration-connections/test с type, base_url, config и credentials.

Сетевые правила

HTTP-подключения должны использовать https:// и указывать на публичный хост: URL резолвится при сохранении и отклоняется, если попадает в приватный, loopback- или link-local-диапазон либо содержит user:password@. DSN PostgreSQL несёт пользователя, хост, порт, базу и sslmode; пароль идёт в поле учётных данных, никогда в DSN.

Деактивация и удаление

• Неактивные подключения сохраняют учётные данные, но любой сбор контекста или исходящая доставка, которые на них ссылаются, сразу падают (connection_inactive). Так интеграцию можно поставить на паузу, не теряя конфигурацию.
• Delete отклоняется, пока источники контекста или исходящие привязки какого-либо проекта ссылаются на подключение — сначала уберите ссылки.

Не входит в экспорт организации

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

Где живёт проектная часть

Источники контекста и исходящие привязки настраиваются в каждом проекте на его странице Context. Источники контекста описаны на страницах платформ (BuiltAPI, PostgreSQL), исходящие привязки — на странице Salesforce. Обе используют один язык плейсхолдеров {{ … }} — см. справочник плейсхолдеров и доставок.

API и MCP

Назначение	REST (/api)	MCP-инструмент
Каталог типов	GET /integration-connections/types	list_connection_types
CRUD подключений	POST/GET/PATCH/DELETE /integration-connections[/{id}]	create_/list_/update_/delete_integration_connection
Проверить подключение	POST /integration-connections/test	test_integration_connection
Прогнать источник контекста	POST /integration-connections/test-source	test_context_source
Источники контекста проекта	GET/PUT /projects/{id}/context-sources	get_/set_project_context_sources
Повторить сбор контекста	POST /sessions/{id}/context/fetch	fetch_session_context
Исходящие привязки проекта	GET/PUT /projects/{id}/outbound-bindings	get_/set_project_outbound_bindings
Все привязки организации (только чтение)	GET /outbound-bindings	—
История доставок и replay	GET /webhook-deliveries?connection_id=…, POST /webhook-deliveries/{id}/replay	list_webhook_deliveries, replay_webhook_delivery

Полные формы запросов и ответов — в справочнике OpenAPI и каталоге MCP-инструментов.