Oncores

Документация по подключению внешних информационных систем

Версия для разработчиков подключаемых сервисов

Документ описывает порядок подключения внешней информационной системы к Oncores, правила передачи текстового пакета данных, использование API-ключа клиента, требования безопасности и примеры запросов. Обработка пакетов выполняется закрытой специализированной AI-моделью Oncores; подключаемый сервис не взаимодействует с моделью напрямую.

1. Назначение документа

Настоящий документ предназначен для разработчиков и технических специалистов внешней информационной системы, которая подключается к Oncores через API.

Документ описывает правила подключения, формат запросов, правила передачи API-ключа, требования к текстовому файлу, структуру ответов, возможные ошибки и требования безопасности.

2. Назначение Oncores

Oncores — закрытая серверная система обработки текстовых пакетов данных, получаемых от внешних информационных систем через API.

После получения запроса Oncores определяет подключенный сервис по API-ключу, добавляет к полученному пакету данных заранее закрепленный за этим клиентом prompt-документ и передает объединенный запрос в закрытую специализированную AI-модель Oncores для обработки.

Ответ модели возвращается обратно во внешний клиентский сервис через API-ответ Oncores.

Для подключаемого сервиса Oncores является единой точкой интеграции. Внешняя информационная система не получает прямого доступа к внутренним настройкам модели, prompt-документам других клиентов, инфраструктуре обработки или административной панели Oncores.

3. Общая схема взаимодействия

Администратор Oncores создает профиль внешнего клиента в админке.

Для клиента генерируется индивидуальный API-ключ.

Администратор загружает prompt-документ, который будет использоваться только для этого клиента.

Клиентский профиль активируется.

Внешняя информационная система отправляет текстовый файл через API Oncores.

Oncores определяет клиента по API-ключу.

Oncores проверяет статус клиента и наличие prompt-документа.

Oncores передает prompt клиента и текстовый файл в закрытую AI-модель Oncores.

Oncores получает результат обработки и возвращает его внешней информационной системе.

В системе фиксируется только техническая статистика обращения.

4. Что получает разработчик внешней системы

Endpoint для отправки пакета данных.

Индивидуальный API-ключ клиента.

Правила передачи API-ключа.

Требования к формату файла.

Описание структуры успешного ответа.

Описание возможных ошибок.

Рекомендации по безопасному хранению API-ключа.

5. Основной endpoint

POST https://api.oncores.ru/api/v1/client/process

Endpoint предназначен для отправки текстового пакета данных во внешнюю систему Oncores.

5.1. Метод и формат запроса

6. API-ключ клиента

Каждый внешний клиентский сервис получает индивидуальный API-ключ. API-ключ используется для идентификации сервиса и выбора prompt-документа, закрепленного за этим клиентом.

6.1. Передача API-ключа

X-API-Key: <client_api_key>

6.2. Правила безопасности API-ключа

API-ключ является секретом внешнего клиентского сервиса.

API-ключ нельзя размещать в публичном frontend-коде.

API-ключ нельзя передавать в URL-параметрах.

API-ключ нельзя публиковать в открытых репозиториях.

API-ключ должен храниться только на серверной стороне подключаемой информационной системы.

При компрометации ключа необходимо запросить его замену у администратора Oncores.

После регенерации новый API-ключ должен заменить старый во внешней информационной системе.

7. Требования к текстовому файлу

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

8. Пример запроса через curl

curl -X POST "https://api.oncores.ru/api/v1/client/process" \
  -H "X-API-Key: <client_api_key>" \
  -F "payload_file=@payload.txt;type=text/plain"

В примерах используется placeholder <client_api_key>. Его необходимо заменить на реальный API-ключ, выданный администратором Oncores.

9. Пример подключения на Node.js

import fs from "fs";
import FormData from "form-data";
import fetch from "node-fetch";

const apiKey = process.env.ONCORES_CLIENT_API_KEY;

const form = new FormData();
form.append("payload_file", fs.createReadStream("./payload.txt"), {
  filename: "payload.txt",
  contentType: "text/plain",
});

const response = await fetch("https://api.oncores.ru/api/v1/client/process", {
  method: "POST",
  headers: {
    "X-API-Key": apiKey,
    ...form.getHeaders(),
  },
  body: form,
});

const result = await response.json();
console.log(result);

10. Пример подключения на Python

import os
import requests

api_key = os.environ["ONCORES_CLIENT_API_KEY"]

with open("payload.txt", "rb") as file:
    response = requests.post(
        "https://api.oncores.ru/api/v1/client/process",
        headers={"X-API-Key": api_key},
        files={"payload_file": ("payload.txt", file, "text/plain")},
        timeout=180,
    )

print(response.status_code)
print(response.json())

11. Пример подключения на PHP

<?php
$apiKey = getenv('ONCORES_CLIENT_API_KEY');

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.oncores.ru/api/v1/client/process',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => [
        'payload_file' => new CURLFile('payload.txt', 'text/plain', 'payload.txt'),
    ],
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $status . PHP_EOL;
echo $response . PHP_EOL;
?>

12. Успешный ответ

После успешной обработки Oncores возвращает результат внешней информационной системе.

{
  "status": "completed",
  "client_id": 1,
  "client_name": "Client name",
  "model": "oncores-model",
  "result": "Результат обработки пакета данных",
  "usage": {
    "request_id": "technical-id",
    "processing_stage": "oncores_model_completed"
  }
}

Содержимое prompt-документа и входящего payload-файла обратно не возвращается.

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

14. Правила обработки данных

Oncores обрабатывает входящий файл только в рамках конкретного запроса.

Prompt-документ хранится в системе как настройка конкретного клиента.

Входящий payload-файл после обработки не сохраняется.

Объединенный пакет prompt + payload не сохраняется.

Полный ответ AI-модели не сохраняется как история запроса.

В статистике фиксируются только технические параметры обращения.

Внешний клиентский сервис получает ответ обработки в рамках API-ответа.

15. Техническая статистика обращения

В Oncores может фиксироваться техническая статистика, необходимая для учета обращений и контроля работы подключения.

Техническая статистика не должна содержать текст клиентского файла, prompt-документ, объединенный пакет prompt + payload или полный ответ модели.

16. Правила безопасности подключения

Все обращения должны выполняться только по HTTPS.

API-ключ должен передаваться только в HTTP-заголовке X-API-Key.

Запрещено передавать API-ключ в URL.

Запрещено размещать API-ключ в frontend-коде, мобильном приложении или публичном JavaScript.

Рекомендуется хранить API-ключ во внутреннем защищенном хранилище секретов подключаемой системы.

Запрещено логировать API-ключ в открытом виде.

Рекомендуется ограничить доступ к endpoint Oncores только серверной частью клиентской системы.

При подозрении на компрометацию ключа необходимо запросить регенерацию ключа у администратора Oncores.

17. Правила формирования payload.txt

Файл payload.txt должен быть сформирован внешней информационной системой до отправки в Oncores. Внутренний формат файла согласуется отдельно с владельцем Oncores и зависит от сценария обработки.

Базовый пример структуры текстового файла:

Название системы: <название внешней системы>
Тип пакета данных: <тип пакета>
Дата формирования: <дата>

Раздел 1. Исходные данные
<текстовые данные>

Раздел 2. Дополнительные сведения
<текстовые данные>

Раздел 3. Требуемый результат обработки
<описание ожидаемого результата>

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

18. Порядок подключения новой внешней системы

Владелец Oncores создает профиль внешнего клиента в админке.

Владелец Oncores генерирует API-ключ клиента.

Владелец Oncores загружает prompt-документ для этого клиента.

Владелец Oncores активирует профиль клиента.

Разработчикам внешней системы передаются endpoint, API-ключ и правила подключения.

Разработчики реализуют серверную отправку текстового файла через multipart/form-data.

Выполняется технический тест отправки payload_file.

После успешного теста подключение может использоваться в рабочем режиме.

19. Минимальный чек-лист для разработчика внешней системы

API-ключ получен от администратора Oncores.

API-ключ хранится на серверной стороне внешней системы.

Endpoint указан как https://api.oncores.ru/api/v1/client/process.

Запрос выполняется методом POST.

Content-Type запроса — multipart/form-data.

Файл передается в поле payload_file.

Файл является plain text и имеет кодировку UTF-8.

API-ключ передается в заголовке X-API-Key.

Ответ API корректно обрабатывается внешней системой.

Ошибки 400 / 401 / 403 / 409 / 502 / 504 / 500 обрабатываются явно.

Содержимое API-ключа не попадает в логи, frontend или публичные репозитории.

20. Что не требуется от внешней системы

Не требуется доступ к админке Oncores.

Не требуется прямое подключение к AI-модели Oncores.

Не требуется передавать prompt-документ в каждом запросе.

Не требуется знать внутреннюю инфраструктуру обработки Oncores.

Не требуется хранить технические настройки модели на стороне внешней системы.

21. Контрольная схема запроса

Внешняя информационная система
  → POST https://api.oncores.ru/api/v1/client/process
  → Header: X-API-Key
  → multipart/form-data
  → payload_file=@payload.txt

Oncores
  → определяет клиента
  → берет prompt-документ клиента
  → передает prompt + payload в закрытую AI-модель Oncores
  → получает результат
  → возвращает результат внешней системе
  → сохраняет только техническую статистику

22. Финальные правила интеграции

Один внешний клиентский сервис использует один выданный ему API-ключ.

Один клиентский сервис связан со своим prompt-документом.

Prompt-документ загружается и изменяется только администратором Oncores.

Клиентский сервис передает только текстовый payload-файл.

Клиентский сервис не передает prompt в запросе.

Клиентский сервис не имеет доступа к prompt-документам других клиентов.

Обработка выполняется закрытой специализированной AI-моделью Oncores.

Ответ модели возвращается клиентскому сервису как результат API-запроса.

23. Безопасность, правовой контур и работа с регулируемыми данными

Oncores предназначен для подключения внешних информационных систем, включая системы профильных медицинских организаций, научных центров, биотехнологических проектов, государственных структур и организаций, работающих с регулируемыми данными.

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

Oncores может использоваться как закрытый серверный слой между внешней информационной системой и обученной моделью Oncores. Внешняя система не получает прямого доступа к модели и взаимодействует только через утвержденный API Oncores.

24. Нормативный контур Российской Федерации

При подключении внешних информационных систем, работающих с персональными, медицинскими, научными или иными регулируемыми данными, применимость требований законодательства Российской Федерации определяется по фактическому составу данных, роли сторон, цели обработки, способу передачи и месту размещения информационных систем.

В качестве базового нормативного ориентира при проектировании подключения учитываются:

Федеральный закон № 152-ФЗ «О персональных данных» — при обработке персональных данных и специальных категорий персональных данных.

Федеральный закон № 323-ФЗ «Об основах охраны здоровья граждан в Российской Федерации» — при работе со сведениями о состоянии здоровья, диагнозе, факте обращения за медицинской помощью и иной информацией, составляющей врачебную тайну.

Федеральный закон № 149-ФЗ «Об информации, информационных технологиях и о защите информации» — при организации информационного обмена и защиты информации.

Постановление Правительства РФ № 1119 — при определении уровня защищенности персональных данных в информационной системе персональных данных.

Приказ ФСТЭК России № 21 — при определении состава и содержания организационных и технических мер по обеспечению безопасности персональных данных.

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

Фактический перечень применимых нормативных требований определяется для каждого подключения отдельно. Oncores предусматривает возможность работы в регулируемом контуре, но конкретный режим подключения должен фиксироваться в проектной, договорной и технической документации сторон.

25. Персональные данные и специальные категории данных

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

Сведения о состоянии здоровья, диагнозе, результатах обследований, медицинских вмешательствах, назначениях, лабораторных показателях и иных медицинских характеристиках могут относиться к специальным категориям персональных данных и требовать повышенного режима защиты.

При подключении внешней информационной системы необходимо заранее определить:

какие категории данных передаются в Oncores;

содержит ли пакет персональные данные;

содержит ли пакет специальные категории персональных данных;

нужно ли обезличивание или псевдонимизация до передачи;

какое правовое основание используется для передачи и обработки;

какая сторона является оператором персональных данных;

какая сторона действует как обработчик или технический исполнитель;

какие ограничения по хранению и логированию должны быть применены.

Базовый принцип Oncores: клиентский payload-файл используется только для обработки текущего запроса и не сохраняется как история обращения. Prompt хранится только как настройка конкретного клиента. Ответ обученной модели Oncores не сохраняется как постоянная история обработки, если иное не предусмотрено отдельной согласованной архитектурой.

26. Медицинские данные и врачебная тайна

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

Внешняя медицинская организация, передающая пакет данных в Oncores, должна самостоятельно обеспечить правомерность формирования и передачи такого пакета, включая наличие законного основания, внутреннего регламента, согласия или иного допустимого режима обработки, если он требуется.

Со стороны Oncores при работе с медицинскими данными должны соблюдаться следующие принципы:

принимать только те данные, которые необходимы для выполнения конкретного запроса;

не требовать избыточных персональных или медицинских сведений;

не сохранять клиентский payload после завершения обработки;

не раскрывать prompt клиента другим подключенным сервисам;

не предоставлять внешним клиентам прямой доступ к обученной модели Oncores;

возвращать результат обработки только тому клиентскому сервису, который направил запрос и был идентифицирован по API-ключу;

вести только техническую статистику обращения без сохранения содержимого медицинского пакета.

27. Работа с государственными структурами и профильными медицинскими организациями

Oncores предусматривает подключение внешних информационных систем государственных структур, профильных медицинских организаций, научных центров и иных организаций, которым требуется обработка сложных медицинских, научных, лабораторных или регуляторных данных.

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

Подключение государственных и медицинских организаций рекомендуется оформлять через отдельный технический профиль подключения, в котором фиксируются:

наименование подключаемой организации и информационной системы;

ответственные технические и организационные контакты;

назначение подключения;

тип передаваемых пакетов данных;

наличие или отсутствие персональных и медицинских данных;

требования к защищенному каналу связи;

требования к журналированию без хранения содержимого пакета;

режим тестового и промышленного доступа;

порядок блокировки, приостановки или удаления подключения.

28. Подключение через защищенные сети и ViPNet при необходимости

Базовый способ подключения внешней информационной системы к Oncores — защищенный API-доступ по HTTPS с использованием индивидуального API-ключа клиента.

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

Необходимость использования ViPNet или иного защищенного канала определяется не автоматически, а по результатам анализа конкретного подключения. Для такого подключения отдельно согласуются:

сетевой контур и схема маршрутизации;

точки взаимодействия внешней информационной системы и Oncores;

IP-адреса, сетевые правила и разрешенные направления обмена;

требования к криптографической защите канала;

порядок тестирования канала до промышленного запуска;

ответственные стороны за сопровождение защищенного канала;

регламент действий при сбоях, блокировке или компрометации доступа.

Если ViPNet или иной защищенный контур не требуется, подключение выполняется через стандартный защищенный API-доступ Oncores с использованием HTTPS, индивидуального API-ключа клиента и ограничений доступа, согласованных в правилах подключения.

29. Требования ФСТЭК и сертифицированные средства защиты

Если подключение Oncores используется в составе информационной системы персональных данных, государственной информационной системы или иного регулируемого контура, вопрос применения требований ФСТЭК, уровня защищенности, модели угроз и сертифицированных средств защиты должен рассматриваться в рамках конкретного проекта подключения.

Oncores может быть встроен в контур, в котором используются организационные и технические меры защиты информации, включая:

идентификацию и аутентификацию администраторов и подключаемых систем;

разграничение доступа;

защиту API-ключей и секретов;

защищенный сетевой обмен;

журналирование технических событий без сохранения содержимого клиентских пакетов;

контроль конфигурации и изменений;

резервное копирование критичных технических настроек;

использование сертифицированных средств защиты информации, если это требуется конкретным контуром;

подготовку материалов для оценки соответствия или аттестации, если она требуется для конкретной системы.

Oncores не должен позиционироваться как автоматически сертифицированная система для любого контура. Вопрос сертификации, аттестации, выбора сертифицированных средств защиты и уровня защищенности решается для конкретного внедрения и конкретной информационной системы.

30. Правила безопасности API-подключения

Каждая внешняя информационная система получает индивидуальный API-ключ клиента. Этот ключ используется для идентификации клиента, выбора его prompt-документа и допуска к обработке пакета данных.

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

Минимальные правила безопасности при подключении:

использовать только HTTPS-доступ к API Oncores;

передавать API-ключ только в HTTP-заголовке X-API-Key;

хранить API-ключ только на серверной стороне внешней информационной системы;

не передавать API-ключ в URL, query-параметрах или публичных формах;

не логировать полный API-ключ;

при подозрении на компрометацию немедленно запросить регенерацию ключа;

использовать отдельные ключи для разных внешних клиентских сервисов;

не передавать в payload избыточные персональные или медицинские данные;

передавать только текстовые файлы в кодировке UTF-8;

проверять ответ API и явно обрабатывать ошибки доступа, валидации и недоступности модели.

31. Разграничение ответственности сторон

Для подключений, связанных с персональными, медицинскими или государственными данными, ответственность сторон должна быть разграничена до промышленного запуска.

Внешняя информационная система отвечает за:

правомерность сбора и формирования передаваемого пакета данных;

наличие правового основания для передачи данных в Oncores;

корректность и полноту передаваемого текстового файла;

сохранность выданного API-ключа клиента;

защиту собственной инфраструктуры;

обезличивание или минимизацию данных, если это требуется применимым режимом обработки.

Oncores отвечает за:

идентификацию клиента по API-ключу;

использование prompt-документа только того клиента, которому он принадлежит;

обработку пакета через обученную модель Oncores;

возврат результата обработки в тот внешний клиентский сервис, который направил запрос;

нехранение payload-файла после обработки;

нехранение полного ответа модели как истории обращения;

ведение только технической статистики обращения;

защиту административного доступа и технических секретов системы.

32. Дополнительный чек-лист перед подключением регулируемой информационной системы

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

тип подключаемой организации: медицинская, научная, государственная, ведомственная, коммерческая;

название внешней информационной системы;

цель подключения к Oncores;

тип передаваемых текстовых пакетов;

наличие персональных данных;

наличие медицинских данных или сведений, составляющих врачебную тайну;

необходимость обезличивания или псевдонимизации до передачи;

необходимость подключения через ViPNet или иной защищенный канал;

необходимость применения требований ФСТЭК или сертифицированных средств защиты;

порядок выдачи и хранения API-ключа клиента;

порядок регенерации API-ключа при компрометации;

ответственных лиц со стороны подключаемой организации;

сценарий тестового запроса и критерии успешного подключения.

33. Формулировка для регулируемых подключений

Для внешних информационных систем, работающих с медицинскими, научными или государственными данными, может использоваться следующая формулировка в технических и организационных материалах:

Oncores обеспечивает закрытое API-подключение внешней информационной системы к обученной модели Oncores для обработки текстовых пакетов данных. Подключение выполняется через индивидуальный API-ключ клиента и отдельный prompt-документ, закрепленный за конкретным клиентом. При работе с персональными, медицинскими или государственными данными режим подключения определяется с учетом требований законодательства Российской Федерации, требований к защите персональных данных, режима врачебной тайны, необходимости защищенного сетевого контура, применения ViPNet и требований ФСТЭК, если такие требования применимы к конкретному проекту.