⚙️ Сценарии в API

Что это. Раздел публичного API для работы со сценариями проекта: чтение сценариев и их версий, публикация и снятие с публикации, запуск сценария из вашей системы и наблюдение за запусками.

Когда нужно.

• Ваша система должна запустить сценарий в ответ на своё событие: оплата прошла, заказ отгружен, заявка создана в CRM.
• Нужно следить за запусками снаружи: выгружать их статус и трассировку в свой мониторинг, отменять зависшие.
• Публикация сценариев встроена в ваш процесс выкладки.

Где находится

Публичные пути раздела начинаются с /v1/flows/… (сценарии и версии), /v1/flow/executions/… (запуски) и /v1/flow/triggers/… (вебхук-триггер). В Swagger UI они собраны в разделах Flow, Execution и Trigger.

Все методы вызываются по API-ключу проекта — см. REST API.

Создавать и редактировать сценарии через API нельзя

Схему сценария — блоки, связи, настройки — собирают только в редакторе. Через API сценарий можно прочитать, опубликовать, снять с публикации, архивировать, удалить и запустить.

---

📋 Методы

Сценарии и версии

Метод	Что делает	Право
GET /v1/flows	Список сценариев проекта	FLOWS_READ
GET /v1/flows/{flowId}	Сценарий по идентификатору	FLOWS_READ
GET /v1/flows/{flowId}/versions	Список версий сценария	FLOWS_READ
GET /v1/flows/{flowId}/versions/{version}	Конкретная версия	FLOWS_READ
POST /v1/flows/{flowId}/versions/draft/publish	Опубликовать текущий черновик	FLOWS_WRITE
POST /v1/flows/{flowId}/unpublish	Снять сценарий с публикации	FLOWS_WRITE
POST /v1/flows/{flowId}/archive	Отправить сценарий в архив	FLOWS_WRITE
DELETE /v1/flows/{flowId}	Удалить сценарий	FLOWS_DELETE

Как устроены версии и публикация — на странице Версии и запуски.

Запуски

Метод	Что делает	Право
GET /v1/flow/executions	Список запусков	FLOWS_READ
GET /v1/flow/executions/{runId}	Запуск по идентификатору	FLOWS_READ
GET /v1/flow/executions/{runId}/trace	Трассировка запуска: какие блоки прошли и с каким результатом	FLOWS_READ
POST /v1/flow/executions/{runId}/cancel	Отменить запуск	FLOWS_WRITE
POST /v1/flow/executions/start	Запустить сценарий с триггером «Ручной запуск»	FLOWS_MANAGE

Список запусков постраничных параметров page/size не принимает:

Параметр	Что делает
scopeId	Только запуски, привязанные к этому объекту (обращению, тикету)
state	Только запуски в этом состоянии: RUNNING, WAITING_EVENT, WAITING_DELAY, COMPLETED, FAILED, INTERRUPTED
limit	Сколько записей вернуть. Не передан или 0 — 200, максимум — 1000

Вебхук-триггер

Метод	Что делает	Право
POST /v1/flow/triggers/{flowId}/webhook	Запустить сценарий с триггером «Webhook»	FLOWS_WRITE

---

🪝 Запуск по вебхуку

Сценарий должен быть опубликован, а в блоке «Старт» у него должен стоять тип триггера «Webhook» — см. Триггеры.

curl -X POST \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
        "payload": { "orderId": "A-1024", "amount": 4990 },
        "headers": { "x-source": "crm" }
      }' \
  https://api.fixorix.ru/v1/flow/triggers/<flowId>/webhook

Тело запроса — все поля необязательны:

Поле	Описание
payload	Произвольный JSON, до 64 КиБ. В сценарии доступен как {{trigger.payload.<ключ>}}
headers	Заголовки, которые нужно передать в сценарий, объектом «имя → значение». Берутся из тела, а не из HTTP-заголовков запроса. Имена приводятся к нижнему регистру, в сценарии доступны как {{trigger.headers.<имя>}}. Заголовки авторизации и cookie (authorization, cookie, set-cookie, proxy-authorization, x-api-key) отбрасываются
userId	Клиент, для которого идёт запуск. У одного клиента в рамках одного scopeId одновременно идёт один запуск: новый вызов заменяет активный
scopeId	Объект (обращение, тикет), к которому относится запуск

Если у сценария заданы входные переменные, payload проверяется по ним ещё до запуска.

Ответ — 202 Accepted с объектом запуска (id, flowId, state, startedAt и др.). По id запуск можно отследить методами GET /v1/flow/executions/{runId} и …/trace.

▶️ Прямой запуск

Сценарий с триггером «Ручной запуск» запускается методом POST /v1/flow/executions/start:

{
  "flowId": "3f1c…",
  "userId": "9a7e…",
  "triggerData": { "reason": "повторная проверка" }
}

Поле	Обязательно	Описание
flowId	да	Сценарий. Он должен быть опубликован и иметь триггер «Ручной запуск»
userId	нет	Клиент, для которого идёт запуск
triggerData	нет	Данные запуска, до 64 КиБ

Ответ — 201 Created с объектом запуска.

---

⏱ Ограничения

Ограничение	Значение
Вызовы вебхук-триггера	Не больше 600 в минуту на проект
Прямые запуски	Не больше 60 в минуту на клиента (userId), без userId — на проект
payload вебхука и triggerData	До 64 КиБ
Общий лимит API-ключа	1000 запросов в минуту — см. REST API

❗ Ошибки вебхук-триггера

Статус	Когда возникает
400 INPUT_VALIDATION_FAILED	payload не прошёл проверку по входным переменным сценария; в ответе — список нарушений violations
400 TRIGGER_TYPE_MISMATCH	У сценария другой тип триггера, не «Webhook»
404	Сценарий не найден в проекте ключа
409	Сценарий не опубликован
422	payload больше 64 КиБ
429	Превышен лимит вызовов вебхук-триггера на проект

---

Кто что может

Действие	Что нужно
Выпустить ключ с правами FLOWS_*	Роль «Администратор» или «Владелец» в проекте
Вызывать методы по ключу	Только права самого ключа — роль участника не проверяется

REST API · Scopes · Триггеры · Сценарии