Внешние интеграции

Руководство для разработчиков и интеграторов: как подключать ERP, 1C, Service Desk, BI и другие системы к Portal.

Старт разработки и карта разделов: Разработчикам. Практические гайды: узлы, списки.

См. также: REST API, кейсы кода, OpenAPI.

Главный вывод

Portal не поддерживает регистрацию произвольных URL вроде /api/v1/my-erp/sync из пакетов или конфигурации. Все маршруты регистрируются централизованно в исходниках Portal.Api при сборке платформы.

Разработчик интеграций работает с фиксированным REST API (/api/v1/*) и расширениями, которые встраиваются в существующие invoke/action-механизмы.

Внешняя система ──JWT + CRUD──► /api/v1 REST API
WebPart UI ──invoke/action──► /api/v1/webparts/invoke/{key}/…
Event Receiver / Timer Job ──HTTP из C#──► внешняя система

Важно: /api/v1/routes — разрешение URL-адресов страниц для браузера, а не API для интеграций.

Путь 1. Внешняя система вызывает Portal (основной сценарий)

Внешняя система — клиент встроенного REST API.

Шаги

Аутентификация — сервисная учётная запись, POST /api/v1/auth/login → JWT (аутентификация)
Обнаружение ресурсов — GET /api/v1/nodes, GET /api/v1/lists/{id}/fields
Чтение/запись данных — GET/POST/PATCH /api/v1/lists/{listId}/items
Права — при необходимости GET/POST /api/v1/permissions (права)

Паттерн записи данных

Фильтрация — по internal_name поля (inn, status, …)
Запись — по UUID полей из GET .../fields (кешировать)

Пример (ERP → Portal, кейс 10):

GET /api/v1/lists/{listId}/fields
Authorization: Bearer …

GET /api/v1/lists/{listId}/items?filter={"logic":"and","conditions":[{"column":"inn","operator":"eq","value":"7707083893"}]}&limit=1

POST /api/v1/lists/{listId}/items
Content-Type: application/json

{
  "fieldValues": {
    "uuid-title": "ООО Ромашка",
    "uuid-inn": "7707083893",
    "uuid-status": "Активен"
  }
}

PATCH /api/v1/lists/{listId}/items/42
Content-Type: application/json

{
  "fieldValues": {
    "uuid-status": "Архив"
  }
}

Справочники

Материал	Описание
REST API	Обзор всех маршрутов
OpenAPI	Полная спецификация
Значения полей	Формат `fieldValues`
PortalApiClient.cs	Пример HTTP-клиента на C#

Путь 2. Portal вызывает внешнюю систему (исходящая интеграция)

Новый HTTP-эндпоинт на Portal не создаётся. Логика исходящих вызовов пишется в C#-расширениях.

Event Receiver (`.portalevent`) — реакция на события

listItem.updated → event_receivers → portal_jobs → IEventReceiver.HandleAsync

Шаг	Действие
1	Скачайте Extension SDK, затем `dotnet new portal-eventreceiver`
2	Реализовать `HandleAsync(...)` — внутри вызвать внешний HTTP API
3	Собрать `.portalevent`, загрузить: Админка → Event Receivers
4	Привязать: `POST /api/v1/event-receivers` с `eventName` + `config.listId`
5	Мониторинг: Админка → Задания

Документация: Event Receivers, привязка к событиям.

Пример привязки:

{
  "eventName": "listItem.updated",
  "jobType": "contoso.list-change-handler",
  "config": { "listId": "uuid-списка" },
  "isEnabled": true
}

Timer Job (`.portaltimer`) — периодическая синхронизация

Для nightly sync (ERP → Portal или Portal → ERP):

Шаг	Действие
1	`dotnet new portal-timerjob`
2	Реализовать `ExecuteAsync` с HTTP-вызовами
3	Загрузить пакет, настроить расписание в Админка → Timer Jobs

Документация: Timer Jobs, интеграция с Worker.

Путь 3. Серверная логика через WebPart (UI + actions)

WebPart не добавляет новые REST-маршруты, но даёт фиксированные invoke-эндпоинты:

Метод	Путь	Назначение
POST	`/api/v1/webparts/invoke/{key}/render`	SSR HTML
POST	`/api/v1/webparts/invoke/{key}/action`	Серверные действия

{key} — из manifest.json пакета .portalpart, не произвольный URL.

Шаг	Действие
1	`dotnet new portal-webpart -n my-widget`
2	`RenderAsync` + `HandleActionAsync` в `IWebPart`
3	Сборка `.portalpart`, загрузка: Админка → WebPart
4	Размещение на странице через `zonesContent`

Документация: сборка WebPart, UI и API, API каталога.

Путь 4. Функциональный модуль (`.portalmod`) — полное решение

Если интеграция — часть готового решения (структура портала + расширения):

Шаг	Действие
1	Описать `module.json` (узлы, списки, страницы, права)
2	Положить `.portalpart`/`.portalevent`/`.portaltimer` в `packages/`
3	Опционально — C# provisioner для начальных данных
4	Установить: Админка → Модули или `POST /api/v1/modules/install`
5	Получить `resource_map`: `GET /api/v1/modules/{key}/resources`

Документация: функциональные модули, API модулей, схема module.json.

Контексты выполнения кода

Контекст	SDK	Ключи при записи	Права
REST (внешняя система)	HTTP	UUID полей	JWT сервисного пользователя
WebPart	`Portal.WebPart.Sdk`	UUID полей	Текущий пользователь страницы
Event Receiver	`Portal.EventReceiver.Sdk`	UUID полей	Пользователь события
Timer Job	`Portal.TimerJob.Sdk`	UUID полей	`runAsUserId` из config
Provisioner	`Portal.Module.Sdk`	`internal_name`	Системные (установка модуля)

Подробнее: кейсы работы с сущностями.

Чего Portal не предоставляет

Нет plugin API для регистрации своих /api/v1/* маршрутов из пакетов
Нет inbound webhook-эндпоинтов — внешняя система не может «стучаться» на произвольный URL Portal; только клиент вызывает фиксированный REST API
Нет API keys — только JWT через логин пользователя (local или LDAP)
Новые HTTP-маршруты — только изменением исходников Portal.Api (работа вендора платформы)