BPMN-процессы

Если форма работает по BPMN-схеме, задачи по ней движутся не по этапам, а по блокам диаграммы. В API блоки схемы называются узлами (nodes), а стрелки между ними — переходами (flows).

Положение задачи в процессе описывают токены. Токен — это метка, которая стоит на узле схемы и показывает, где сейчас находится задача и чего от неё ждут. У задачи может быть несколько токенов одновременно — например, после шлюза AND на каждую параллельную ветку приходится свой токен. Когда ветки сходятся, их токены завершаются, а дальше идёт новый токен.

Методы API, описанные в этом разделе, позволяют:

• узнать, на каких узлах находится задача и от кого она ждёт действий;
• увидеть, как комментарий продвинул задачу по схеме;
• согласовать задачу на конкретном узле, возобновить остановленный процесс или вручную перенести токен;
• получить описание BPMN-диаграммы формы и список её версий;
• найти в реестре задачи, стоящие на нужных узлах.

• GET/forms/{form-id}/bpmnСписок версий BPMN-диаграммы формы
• GET/forms/{form-id}/bpmn/{bpmn-version}Описание версии BPMN-диаграммы формы

BPMN-поля в описании формы

Методы GET /forms и GET /forms/{form-id} возвращают в описании формы два дополнительных поля:

{
  "id": 1204,
  "name": "Payment request",
  "use_bpmn_for_new_tasks": true,
  "bpmn_version": 3
}

BPMN-поля задачи

Метод GET /tasks/{task-id} возвращает для задач по BPMN-схеме дополнительные поля. У задач, которые идут по обычной маршрутизации, этих полей нет.

Элемент bpmn_tokens

GET https://api.pyrus.com/v4/tasks/91827364

{
  "task": {
    "id": 91827364,
    "text": "Payment request for invoice No. 4417",
    "form_id": 1204,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 12,
        "node_name": "Legal approval",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 4471,
          "first_name": "Mary",
          "last_name": "Smith"
        }
      },
      {
        "token_id": 2,
        "node_id": 18,
        "node_name": "Wait 3 business days",
        "node_type": "Timer",
        "status": "Waiting",
        "event_type": "Timer",
        "event_time": "2026-09-05T09:00:00Z"
      }
    ]
    // ...
  }
}

В этом примере задача находится одновременно в двух параллельных ветках: в одной ждёт согласования юриста, в другой — срабатывания таймера.

BPMN-поля в комментарии задачи

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

Элемент bpmn_transitions

Если в элементе есть только token_id, значит, этот комментарий завершил токен и токена больше не существует. Токены, которые комментарий создал и тут же завершил, в массив не попадают.

{
  "id": 55510293,
  "text": "Approved",
  "approval_choice": "approved",
  "bpmn_transitions": [
    { "token_id": 1 },
    { "token_id": 2 },
    { "token_id": 7, "node_id": 24, "node_name": "Payment" }
  ]
}

В этом примере токены 1 и 2 завершились на шлюзе слияния, а вместо них по схеме пошёл токен 7.

Действия с задачей по BPMN-схеме

Метод POST /tasks/{task-id}/comments принимает дополнительные параметры для задач по BPMN-схеме. Все они необязательные.

Согласование на конкретном узле

Если задача разошлась на параллельные ветки и пользователя ждут сразу на нескольких узлах, укажите в bpmn_node_id, на каком узле вы выполняете действие.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "No objections",
  "approval_choice": "approved",
  "bpmn_node_id": 12
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 20,
        "node_name": "Accounting review",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Johnson"
        }
      },
      {
        "token_id": 2,
        "node_id": 18,
        "node_name": "Wait 3 business days",
        "node_type": "Timer",
        "status": "Waiting",
        "event_type": "Timer",
        "event_time": "2026-09-05T09:00:00Z"
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510294,
        "text": "No objections",
        "approval_choice": "approved",
        "bpmn_transitions": [
          { "token_id": 1, "node_id": 20, "node_name": "Accounting review" }
        ]
      }
    ]
    // ...
  }
}

Возобновление после ошибки

Если токен остановился из-за ошибки ("status": "Suspended", у задачи "bpmn_suspended": true), устраните причину и возобновите обработку. Токен продолжит выполнение с того же узла.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "Bot access granted, resuming",
  "bpmn_resume_processing": true
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 3,
        "node_id": 15,
        "node_name": "Upload invoice",
        "node_type": "Activity",
        "status": "Active"
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510295,
        "text": "Bot access granted, resuming"
      }
    ]
    // ...
  }
}

Ручной перенос токенов

Токен можно перенести на другой узел в обход условий маршрутизации. За один комментарий можно перенести несколько токенов.

POST https://api.pyrus.com/v4/tasks/91827364/comments

{
  "text": "Returning for revision",
  "bpmn_token_moves": [
    { "token_id": 1, "node_id": 8 }
  ]
}

{
  "task": {
    "id": 91827364,
    "bpmn_version": 3,
    "bpmn_suspended": false,
    "bpmn_tokens": [
      {
        "token_id": 1,
        "node_id": 8,
        "node_name": "Prepare request",
        "node_type": "Activity",
        "status": "Active",
        "person": {
          "id": 1731,
          "first_name": "Bob",
          "last_name": "Johnson"
        }
      }
    ],
    "comments": [
      // ...
      {
        "id": 55510296,
        "text": "Returning for revision",
        "bpmn_transitions": [
          { "token_id": 1, "node_id": 8, "node_name": "Prepare request" }
        ]
      }
    ]
    // ...
  }
}

curl -X POST \
  'https://api.pyrus.com/v4/tasks/91827364/comments' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "Returning for revision",
    "bpmn_token_moves": [
      { "token_id": 1, "node_id": 8 }
    ]
}'

Поиск задач в реестре по узлам схемы

Метод GET /forms/{form-id}/register принимает два дополнительных параметра для форм с BPMN-схемой. Их можно сочетать с остальными фильтрами реестра.

Пример GET-запроса:

GET https://api.pyrus.com/v4/forms/1204/register?bpmn_nodes=12,18

То же в POST-запросе — параметры передаются в теле:

{
  "bpmn_nodes": [12, 18],
  "bpmn_suspended": false
}

Узлы из списка объединяются по условию ИЛИ: достаточно, чтобы токен стоял на любом из них. Если указать идентификатор несуществующего узла, ошибки не будет, но результат окажется пустым.

GET /forms/{form-id}/bpmn

Метод возвращает список версий BPMN-диаграммы формы. Доступен всем, у кого есть доступ к форме.

GET https://api.pyrus.com/v4/forms/1204/bpmn

{
  "form_id": 1204,
  "active_bpmn_version": 3,
  "versions": [
    {
      "bpmn_version": 4,
      "description": "Draft with legal review",
      "create_date": "2026-09-20T08:15:00Z",
      "author": {
        "id": 4471,
        "first_name": "Mary",
        "last_name": "Smith",
        "type": "user"
      }
    },
    {
      "bpmn_version": 3,
      "create_date": "2026-08-01T10:00:00Z"
    }
  ]
}

curl -X GET \
  'https://api.pyrus.com/v4/forms/1204/bpmn' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Поля ответа

GET /forms/{form-id}/bpmn/{bpmn-version}

Метод возвращает описание указанной версии BPMN-диаграммы формы: узлы, переходы между ними, условия видимости полей и текстовые рамки. Доступен всем, у кого есть доступ к форме.

Версия 0 есть у формы всегда: пока её не сохранили, она возвращается пустой. Удалённая версия тоже возвращается — с полем delete_date. Пустые массивы в ответ не попадают.

GET https://api.pyrus.com/v4/forms/1204/bpmn/3

{
  "form_id": 1204,
  "bpmn_version": 3,
  "active_bpmn_version": 3,
  "create_date": "2026-08-01T10:00:00Z",
  "active_task_nodes": [12],
  "nodes": [
    {
      "id": 1,
      "node_type": "Start",
      "position": { "x": 40, "y": 200 },
      "flows": [ { "id": 1, "to_node_id": 12 } ]
    },
    {
      "id": 12,
      "node_type": "Activity",
      "description": "Legal approval",
      "participant": {
        "person": {
          "id": 4471,
          "first_name": "Mary",
          "last_name": "Smith",
          "type": "user"
        }
      },
      "actions": ["Approve", "Reject"],
      "position": { "x": 240, "y": 200 },
      "flows": [ { "id": 2, "to_node_id": 2 } ]
    },
    {
      "id": 2,
      "node_type": "Finish",
      "position": { "x": 440, "y": 200 }
    }
  ],
  "field_visibility_conditions": [
    {
      "field_id": 7,
      "condition": { "field_id": 5, "condition_type": 3 }
    }
  ]
}

curl -X GET \
  'https://api.pyrus.com/v4/forms/1204/bpmn/3' \
  -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Поля ответа

Элемент nodes

Формат одинаковый для массивов nodes и deleted_nodes.

Элемент participant

Элемент flows

Формат одинаковый для массивов flows и deleted_flows.

Элемент timer

Элемент subprocess_configuration

Формат такой же, как у настроек подпроцесса в описании формы.

Элемент condition

Формат такой же, как у условий маршрутизации в описании формы.

Значения перечислений

Состояние токена (status)

Тип узла (node_type)

Подробнее о блоках схемы — в статье BPMN-маршрутизация.

Ожидаемое событие (event_type)

Коды ошибок