unibpm-integration-feedback

Назначение

unibpm-integration-feedback — это integration-модуль UniBPM, предназначенный для приёма и обработки внешних форм обратной связи (feedback), в первую очередь с лендингов и публичных сайтов.

Основной сценарий использования:

• приём данных формы;
• проверка SmartCaptcha (Yandex);
• валидация входных данных;
• создание заявки в UniBPM через API.

Use cases

• Формы на лендингах UniBPM
• Запросы демо / консультаций
• Генерация лидов
• Публичные формы без аутентификации

API

Endpoint

POST /public/feedback

Endpoint доступен без аутентификации.

Формат запроса

Общая структура (Envelope)

{
  "formId": "landing-demo",
  "smartToken": "string",
  "data": {
    "name": "John",
    "email": "john@example.com",
    "company": "ACME"
  }
}

Поля

Validation

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

• formId должен существовать в конфигурации
• data должна быть JSON-объектом
• Количество и глубина полей ограничены
• Строковые поля имеют максимальную длину

Ограничения

SmartCaptcha

Назначение

Используется Yandex SmartCaptcha для защиты публичных форм от ботов.

Поведение

• При ошибке SmartCaptcha используется fail-open стратегия
• При отсутствии токена запрос отклоняется

Конфигурация

Пример application.yml

unibpm:
  integration:
    feedback:
      enabled: true
      smart-captcha:
        validate-url: "https://smartcaptcha.yandexcloud.net/validate"
        secret-key: "${SMART_CAPTCHA_SECRET}"
        connect-timeout-ms: 3000
        read-timeout-ms: 3000
      unibpm-api:
        base-url: "http://unibpm-app:8080"
        token: "${UNIBPM_TOKEN}"
      forms:
        landing-demo:
          ticket-type-id: "ceedf30e-fdc4-11f0-8f6b-1b80298e4fe7"
          queue-key: "d6318e46-fdc4-11f0-9c1f-d30a1a0f4bd6"
          title-template: "Lead: ${data.name} / ${data.company}"
          description-template: |
            Name: ${data.name}
            Email: ${data.email}
            Company: ${data.company}            
          allowed-fields: [name, email, company]
          max-fields: 30
          max-string-len: 2000
          max-depth: 3

Templates

В title-template и description-template поддерживается подстановка:

• ${data.<field>} — данные формы
• ${meta.clientIp} — IP клиента (если доступен)

Интеграция с UniBPM

Назначение

На текущем этапе модуль создаёт заявку в UniBPM через REST API.

Поведение

• Очередь и тип заявки определяются конфигурацией формы
• Ошибки UniBPM логируются и возвращаются как INTERNAL_ERROR

Error handling

Возможные ошибки

Пример ответа об ошибке

{
  "status": 400,
  "reason": "VALIDATION",
  "message": "Invalid formId"
}

Расширение

Для добавления новой формы:

1. Добавить конфигурацию в application.yml
2. Указать formId
3. Настроить поля и шаблоны

Перезапуск runtime обязателен.

Примечания

• Endpoint /public/feedback предназначен только для публичных форм
• Не рекомендуется использовать модуль для внутренних интеграций