Портальный API

Порталы — публичные или полупубличные страницы для приёма обращений от внешних пользователей без полной авторизации в Orbita.

Типы авторизации портала

auth_type	Поведение
none	Полностью анонимный. Можно указать email для получения ссылки отслеживания
email	Вход по magic link — пользователь вводит email, получает письмо со ссылкой
login	Требуется полная авторизация через Orbita

---

Публичные эндпоинты (без токена)

Конфигурация портала

GET /api/portal/{slug}

Возвращает метаданные портала и страницы с полями форм. Вызывается при первой загрузке портала.

{
  "data": {
    "id": 1,
    "name": "IT-поддержка",
    "slug": "support",
    "auth_type": "none",
    "pages": [
      {
        "id": 1,
        "name": "Новая заявка",
        "slug": "new-request",
        "table_name": "it_requests",
        "fields": [
          { "name": "name",     "type": "text",     "label": "Тема",    "required": true },
          { "name": "details",  "type": "textarea", "label": "Описание" },
          { "name": "priority", "type": "value_list","label": "Приоритет",
            "options": ["low","medium","high","critical"] }
        ]
      }
    ]
  }
}

Поля фильтруются по config.visible_fields страницы, если заданы.

---

Отправка формы

POST /api/portal/{slug}/submit
Content-Type: application/json

{
  "page_slug":     "new-request",
  "visitor_email": "user@client.com",
  "visitor_name":  "Иван Иванов",
  "data": {
    "name":     "Не работает принтер на 3 этаже",
    "details":  "HP LaserJet, порт USB, ошибка 0x000003e3",
    "priority": "medium"
  }
}

Что происходит (по шагам):

1. Портал и страница ищутся по slug и page_slug
2. Данные из data валидируются против полей таблицы страницы
3. Создаётся запись (DynamicEntity) в таблице it_requests
4. Если у таблицы есть ProcessTemplate с is_auto_start = true — запускается BPMN
5. Если visitor_email передан и auth_type != 'none':
   • Создаётся / находится PortalVisitor
   • Создаётся трекинг-токен: purpose='track', TTL 7 дней, entity_instance_ref = 'it_requests:43'
   • Отправляется письмо с magic link для отслеживания

Ответ:

{
  "success": true,
  "data": {
    "instance_id": 43,
    "track_token": "a1b2c3d4...",
    "email_sent": true
  }
}

---

Отслеживание обращения

GET /api/portal/{slug}/track/{token}

token — из поля track_token в ответе submit или из письма.

{
  "success": true,
  "data": {
    "instance_id": 43,
    "table_name":  "it_requests",
    "instance": {
      "id": 43,
      "name": "Не работает принтер на 3 этаже",
      "status": "in_work",
      "priority": "medium"
    },
    "sys_table": {
      "entity_name": { "ru": "IT-заявки" },
      "table_fields": [ ... ]
    },
    "processes": [
      {
        "id": 12,
        "status": "running",
        "active_nodes": ["t_resolve"],
        "started_at": "2024-02-10T09:01:00Z"
      }
    ],
    "visitor": { "name": "Иван Иванов", "email": "user@client.com" }
  }
}

---

Аутентификация посетителей

Для порталов с auth_type = 'email' реализована magic link авторизация без пароля.

Схема токенов

email посетителя
      ↓
POST /auth/request  → создаётся login-токен (TTL 7 дней, однократный)
                    → отправляется письмо с ссылкой
      ↓
GET  /auth/verify/{login-token}
      → login-токен помечается использованным (used_at = now())
      → создаётся session-токен (TTL 30 дней, многократный)
      → возвращается session-токен
      ↓
Дальнейшие запросы с заголовком:
X-Portal-Token: {session-token}

Шаг 1 — запросить ссылку

POST /api/portal/{slug}/auth/request
Content-Type: application/json

{
  "email": "user@client.com",
  "name":  "Иван Иванов"
}

На указанный email придёт письмо со ссылкой для входа.

Шаг 2 — верифицировать токен

GET /api/portal/{slug}/auth/verify/{login_token}

{
  "success": true,
  "data": {
    "session_token": "xyz987...",
    "visitor": {
      "id": 7,
      "name": "Иван Иванов",
      "email": "user@client.com"
    }
  }
}

Используйте session_token в заголовке X-Portal-Token для последующих запросов.

Мои обращения (для авторизованного посетителя)

GET /api/portal/{slug}/my-submissions
X-Portal-Token: {session_token}

Возвращает все обращения, связанные с этим посетителем. Источники данных:

• Трекинг-токены, выданные при отправке форм
• Записи, где created_by = visitor.user_id (если посетитель связан с Orbita-пользователем)

Текущий посетитель

GET /api/portal/{slug}/me
X-Portal-Token: {session_token}

---

Типы токенов посетителя

Тип	purpose	TTL	Однократный?	Назначение
Login	login	7 дней	Да	Обмен на session-токен
Session	session	30 дней	Нет	Авторизация API-запросов через X-Portal-Token
Track	track	7 дней	Нет	Отслеживание статуса обращения

Admin-сессия

Полноценные Orbita-пользователи (администраторы) могут создать сессию посетителя через:

POST /api/portal/{slug}/auth/admin-session
Authorization: Bearer <orbita-token>

---

Административные эндпоинты

CRUD порталов

Метод	URL	Описание
GET	/api/admin/portals	Список порталов
POST	/api/admin/portals	Создать
GET	/api/admin/portals/{id}	Детали
PATCH	/api/admin/portals/{id}	Обновить
DELETE	/api/admin/portals/{id}	Удалить

Создать портал

POST /api/admin/portals
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name":      "IT-поддержка",
  "slug":      "support",
  "auth_type": "none",
  "is_active": true
}

CRUD страниц

POST   /api/admin/portals/{id}/pages
PATCH  /api/admin/portals/{id}/pages/{pageId}
DELETE /api/admin/portals/{id}/pages/{pageId}

Создать страницу:

POST /api/admin/portals/1/pages
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "name":         "Новая заявка",
  "slug":         "new-request",
  "target_table": "it_requests",
  "config": {
    "visible_fields": ["name", "details", "priority"]
  }
}

config.visible_fields ограничивает, какие поля таблицы отображать в форме. Если не задан — отображаются все поля.

Список посетителей

GET /api/admin/portals/{id}/visitors
Authorization: Bearer <admin-token>