Commerce-потоки

Commerce-потоки — отдельная стейт-машина рядом с гидами проектного подбора. Определения — Studio-готовые YAML/JSON (скомпилированные техкарты и кастомные фикстуры). Сессия хранит ledger и курсор шага. Все методы требуют scope search:read.

Потоки выключены, пока у индекса не задано settings.flows.enabled (консоль Flows Studio по пути /flows или соответствующие oRPC-настройки). Список и чтение определений работают при выключенном флаге; создание или продвижение сессии без флага возвращает 403 FLOW_DISABLED.

Список или одно определение:

GET /api/v1/indexes/{slug}/flows
GET /api/v1/indexes/{slug}/flows/{flowId}

Старт сессии (flow_id, опционально client_id, либо свободный text для триггера / default flow):

POST /api/v1/indexes/{slug}/flows/sessions
{"client_id":"visitor-42","flow_id":"commerce.simple-product-pick"}

Продвижение с оптимистичной конкуренцией. Передайте последний data.revision как expected_revision:

POST /api/v1/indexes/{slug}/flows/sessions/{sessionId}/advance
{"expected_revision":1,"answer":{"value":"acme"}}

Шаг search может вернуть proof поиска (хиты через тот же searchForIndex). catalog_match и quote переиспользуют shopping-guide product helpers при вложенном guide-состоянии: pendingActions становятся resolved или incomplete, в ответе могут быть catalog / quote. Если биндинги или стадия не готовы — остаётся needs_guide_session с endpoint на POST .../guide/sessions/{id}/recommendations или .../quotes (см. гиды проектного подбора). Кастомные потоки без guide получают unsupported — без тихого no-op.

Поток ассистента при включённых flows стартует сценарий по триггеру (он важнее defaultFlowId). Техкарты могут открыть ту же seeded-сессию, что и Studio. Передайте id сессии как conversation_id для продолжения; «отмена»/cancel или «уточните»/clarify уходят как command, а не как ответ на слот. Каталог/quote и варианты ask — в SSE ui (product_cards / guide_actions).

Устаревшая ревизия: 409 FLOW_REVISION_CONFLICT. Неизвестный поток или сессия: 404 FLOW_NOT_FOUND. Неполный ответ: 422 FLOW_INCOMPLETE.

Полные схемы запросов и ответов — в сгенерированном OpenAPI для операций listFlowDefinitions, getFlowDefinition, createFlowSession, getFlowSession, advanceFlowSession.