API

📋 API

Основные коды состояния ответа HTTP

Код	Описание
`200`	`Операция успешно завершена`
`400`	`Плохой запрос`
`401`	`Не авторизован`
`500`	`Другие ошибки`

🌍 Локализация

Параметр {culture} отвечает за локализацию API, которая представляет собой код языка в соответствии со стандартом ISO 639-1.

💬 Информационное сообщение

Вызовы некоторых методов возвращают только информационные сообщения. В этом случае код состояния ответа HTTP всегда будет 200, а возвращаемое сообщение будет выглядеть следующим образом:

{
  "message": "Операция успешно завершена"
}

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

⛔ Сообщение об ошибке

Если что-то пойдет не так во время вызова метода или выполнения, код состояния ответа HTTP всегда будет отличаться от 200. В этом случае возвращаемое сообщение будет выглядеть следующим образом:

{
  "error": "Операция завершилась неудачей",
  "errorCode": 1234
}

где error — это сообщение от системы, содержащее причину ошибки, а errorCode — числовой код, позволяющий клиенту программно различать ошибки. Поле errorCode равно -1 для неклассифицированных ошибок и совпадает с номером ошибки БД для SQL-исключений.

⚡ Для всех следующих методов этого API, если код состояния ответа HTTP не равен 200, будет возвращено сообщение об ошибке.

👮 Аутентификация/Авторизация

Получение токена

/{culture}/api/issue-access-token - метод позволяет получить токен для последующей аутентификации и авторизации в системе.

POST, Content-Type: application/json

Запрос:

{
  "username": "user@example.com",
  "password": "64e09891d828"
}

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

{
  "expiration": "2077-01-01T00:00:00Z",
  "token": "..."
}

где expiration — срок действия токена, а token — сам токен.

Заголовок HTTP-аутентификации/авторизации

Токен, полученный на первом шаге, должен использоваться во всех перечисленных ниже методах API путем добавления заголовка Authorization со значением Bearer <Token>.

Пример заголовка в HTTP-запросе:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

где eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 это полученный токен.

Перевыпуск токена

/{culture}/api/refresh-access-token - метод позволяет обновить токен аутентификации и авторизации в системе.

GET, Authorization: Bearer <Token>

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

{
  "expiration": "2077-01-01T00:00:00Z",
  "token": "..."
}

где expiration — срок действия токена, а token — сам токен.

⚡ Для продолжения работы с API необходимо предыдущий токен заменить на новый.

📇 Основная информация

Получение оргструктур

/{culture}/api/user-structures - метод получает полную иерархию организационных структур.

GET, Authorization: Bearer <Token>

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

{
    "name": null,
    "id": 0,
    "childNodes": [
        {
            "name": "...",
            "id": 1,
            "childNodes": []
        }
    ]
}

Получение папок пользователя

/{culture}/api/user-folders - метод получает полную иерархию папок пользователя.

GET, Authorization: Bearer <Token>

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

{
    "name": null,
    "id": 0,
    "childNodes": [
        {
            "name": "...",
            "id": 1,
            "childNodes": []
        }
    ]
}

👥 B2B-пользователи

Создание B2B-пользователя

/{culture}/api/create-b2b-user - метод позволяет аутентифицированному B2B-менеджеру или модератору программно создать и привязать нового пользователя к своей организации. Email пользователя всегда подтверждается автоматически. Если пароль указан, он устанавливается при создании; иначе на email пользователя отправляется ссылка на установку пароля.

POST, Authorization: Bearer <Token>, Content-Type: application/json

⚡ Этот метод доступен только для пользователей с ролью Manager или Moderator. Если у вызывающего нет одной из этих ролей, метод возвращает HTTP 401.

Запрос:

{
  "username": "user@example.com",
  "firstName": "Ivan",
  "lastName": "Ivanov",
  "description": "...",
  "role": 3,
  "nodeId": 1234,
  "password": "P@ssw0rd!",
  "dailyLimit": 10,
  "subscriptionLimit": 100
}

Поле	Описание	Обязательно
`username`	`Email пользователя, который создаётся или привязывается к организации`	`✔️`
`role`	`Идентификатор роли в организации. Передаётся как целочисленное значение enum. Допустимые значения: 3 (Преподаватель), 4 (Студент), 6 (Модератор), 7 (Супервизор), 8 (Эксперт)`	`✔️`
`firstName`	`Имя пользователя`	`❌`
`lastName`	`Фамилия пользователя`	`❌`
`description`	`Произвольное описание пользователя`	`❌`
`nodeId`	`Идентификатор узла организационной структуры. Должен принадлежать дереву структуры менеджера`	`❌`
`password`	`Пароль пользователя. Должен содержать не менее 8 символов и проходит проверку серверной политики паролей. Если указан — ссылка на установку пароля не отправляется. Если не указан — ссылка отправляется. Email подтверждается всегда автоматически`	`❌`
`dailyLimit`	`Дневной лимит проверок на плагиат`	`❌`
`subscriptionLimit`	`Общий лимит проверок на плагиат за период подписки`	`❌`

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

{
  "userId": 1234,
  "username": "user@example.com",
  "subscriberId": 42,
  "isNewUser": true,
  "passwordSet": true,
  "passwordResetEmailSent": false,
  "message": "Пользователь создан и привязан к B2B-организации"
}

Поле	Описание
`userId`	`Идентификатор пользователя в системе`
`username`	`Email пользователя`
`subscriberId`	`Идентификатор организации, к которой привязан пользователь`
`isNewUser`	`true — пользователь создан в этом вызове. false — пользователь уже существовал и был привязан к организации`
`passwordSet`	`true — пароль был передан в запросе и установлен пользователю`
`passwordResetEmailSent`	`true — пользователю отправлено письмо со ссылкой на установку пароля`
`message`	`Информационное сообщение о результате`

При ошибке ответ возвращается в стандартном формате API { "error": ..., "errorCode": ... }. Значения errorCode, специфичные для этого метода:

Код ошибки	HTTP-статус	Сообщение об ошибке
`4000`	`400`	`Некорректные входные данные`
`4001`	`400`	`Выбранная роль недопустима`
`4002`	`400`	`Выбранный узел оргструктуры недопустим`
`4003`	`400`	`Пароль не соответствует политике безопасности`
`5001`	`401`	`Доступ запрещён`

🔎 Поисковый индекс

Добавление документа в поисковый индекс

/{culture}/api/add-to-search-index - метод позволяет добавить документ в поисковый индекс, который закреплен за пользователем или его организацией.

PUT, Authorization: Bearer <Token>, Content-Type: application/json

Запрос:

{
  "filename": "example.txt",
  "title": "Pacifica`s Braindances",
  "author": "Victor Vector, Dakota Smith",
  "year": 2024,
  "url": "https://example.com/doc/9fe76511d0ee",
  "body": "0YHRitC10YjRjCDQttC1INC10YnRkSDRjdGC0LjRhSDQvNGP
  0LPQutC40YUg0YTRgNCw0L3RhtGD0LfRgdC60LjRhSDQsdGD0
  LvQvtC6LCDQtNCwINCy0YvQv9C10Lkg0YfQsNGO"
}

Поле	Описание	Обязательно
`filename`	`Имя файла, обязательно с расширением`	`✔️`
`url`	`URL-адрес документа может быть виртуальным, но уникальным`	`✔️`
`body`	`Тело файла в формате Base64`	`✔️`
`title`	`Название документа`	`❌`
`author`	`Авторы документа через запятую`	`❌`
`year`	`Год создания документа`	`❌`

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

{
  "message": "Документ добавлен в поисковый индекс"
}

Удаление документа из поискового индекса

/{culture}/api/remove-from-search-index - метод позволяет удалить документ из поискового индекса, закрепленного за пользователем или его организацией.

DELETE, Authorization: Bearer <Token>, Content-Type: application/json

Запрос:

{
  "url": "https://example.com/doc/9fe76511d0ee"
}

где url - это URL документа в поисковом индексе.

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

{
  "message": "Документ удален из поискового индекса"
}

Массовые операции с поисковым индексом

/{culture}/api/remove-from-search-index?refresh=false

/{culture}/api/add-to-search-index?refresh=false

Для массового добавления или удаления документов необходимо использовать вышеперечисленные методы с параметром refresh и установленным значением в false. Чтобы применить изменения после массовых операций, нужно вызвать метод обновления индекса /{culture}/api/refresh-search-index.

Обновление поискового индекса

/{culture}/api/refresh-search-index - метод позволяет обновить поисковый индекс, закрепленный за пользователем или его организацией.

GET, Authorization: Bearer <Token>

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

{
  "message": "Поисковый индекс обновлен"
}

Очистка поискового индекса

/{culture}/api/clear-search-index - метод позволяет удалить все документы из поискового индекса, закрепленного за пользователем или его организацией.

GET, Authorization: Bearer <Token>

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

{
  "message": "Поисковый индекс очищен"
}

🕵🏿‍♀️ Проверка на плагиат

Отправка документа на проверку

/{culture}/api/plagiarism-check - метод позволяет отправить документ на проверку в систему обнаружения заимствований.

POST, Authorization: Bearer <Token>, Content-Type: application/json

Запрос:

{
  "structureId": 1000,
  "folderId": 1,
  "filename": "example.txt",
  "author": "Anders Helman, Brandon Frost",
  "year": 2024,
  "body": "0YHRitC10YjRjCDQttC1INC10YnRkSDRjdGC0LjRhSDQvNGP
  0LPQutC40YUg0YTRgNCw0L3RhtGD0LfRgdC60LjRhSDQsdGD0
  LvQvtC6LCDQtNCwINCy0YvQv9C10Lkg0YfQsNGO",
  "disableDuplicateChecking": false
}

Поле	Описание	Обязательно
`structureId`	`Идентификатор организационной структуры`	`✔️`
`folderId`	`Идентификатор пользовательской папки`	`❌`
`filename`	`Имя файла, обязательно с расширением`	`✔️`
`author`	`Авторы документа через запятую`	`❌`
`year`	`Год создания документа`	`❌`
`body`	`Тело файла в формате Base64`	`✔️`
`disableDuplicateChecking`	`Отключение проверки на дублирование`	`❌`

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

{
  "id": 1000,
  "state": 2
}

где id - это идентификатор проверки, а state - текущее состояние проверки.

При обнаружении дубликата (state = 1) ответ также будет содержать идентификатор исходной проверки:

{
  "id": 1001,
  "state": 1,
  "duplicateOf": 1000
}

где duplicateOf — идентификатор исходной проверки, результаты которой можно получить. Поле duplicateOf присутствует только при state = 1 и отсутствует в остальных случаях.

Получение состояния проверки

/{culture}/api/plagiarism-check-se/{id} - метод позволяет получить текущее состояние проверки.

GET, Authorization: Bearer <Token>

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

{
  "id": 1000,
  "state": 2
}

где id - это идентификатор проверки, а state - текущее состояние проверки.

Код состояния	Описание
`1`	`Дубликат`
`2`	`В очереди на проверку`
`3`	`Отменено`
`4`	`В процессе`
`5`	`Выполнено`
`6`	`Ошибка`

Управление результатом проверки

/{culture}/api/plagiarism-check-rs/{id} - метод позволяет получить или удалить результат проверки.

Authorization: Bearer <Token>

Способ	Описание
`DELETE`	`Удалить результат проверки`
`GET`	`Получить результат проверки`

Если операция успешно выполнена при вызове метода GET, ответное сообщение будет выглядеть следующим образом:

{
    "isContainsDeception": false,
    "metrics": {
      "originality": 0.0,
      "citation": 0.0,
      "match": 1.0
    },
    "sources": [
        {
          "metrics": {
             "citation": 0.0,
             "match": 1.0
          },
          "url": "https://www.example.org/abcd/1970.00001",
          "title": null,
          "author": null,
          "year": null
        },
        ...
    ]
}

Поле	Описание
`isContainsDeception`	`Указывает на то, что используются технические средства повышения оригинальности`
`metrics`	`Показатели для документа или отдельного источника`
`sources`	`Источники, из которых были обнаружены заимствования`

Поле	Описание
`originality`	`Доля оригинальности`
`citation`	`Доля цитирования`
`match`	`Доля заимствований`

Поле	Описание
`url`	`Адрес ресурса, на котором находится документ или страница`
`title`	`Название`
`author`	`Авторы`
`year`	`Год создания`

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

Подробный отчет в формате PDF

/{culture}/api/plagiarism-check-rp/{id}/extended - метод позволяет получить расширенный отчет о проверке в формате PDF.

GET, Authorization: Bearer <Token>

Параметр	Описание	Обязательно
`utc`	`Смещение UTC в минутах (например, 180 для UTC+3, -300 для UTC-5). Корректирует дату и время в отчете.`	`❌`

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/extended?utc=300
/{culture}/api/plagiarism-check-rp/{id}/extended?utc=-600

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

Краткий отчет в формате PDF

/{culture}/api/plagiarism-check-rp/{id}/summary - метод позволяет получить краткий отчет о проверке в формате PDF. Если вы хотите включить в отчет оригинальный документ, просто добавьте ?withOriginal=true.

GET, Authorization: Bearer <Token>

Параметр	Описание	Обязательно
`withOriginal`	`Включить оригинальный документ в отчет`	`❌`
`utc`	`Смещение UTC в минутах (например, 180 для UTC+3, -300 для UTC-5). Корректирует дату и время в отчете.`	`❌`

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/summary?utc=300
/{culture}/api/plagiarism-check-rp/{id}/summary?utc=-600&withOriginal=true

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

Справка в формате PDF

/{culture}/api/plagiarism-check-rp/{id}/reference - метод позволяет получить справку в формате PDF.

GET, Authorization: Bearer <Token>

Параметр	Описание	Обязательно
`utc`	`Смещение UTC в минутах (например, 180 для UTC+3, -300 для UTC-5). Корректирует дату и время в отчете.`	`❌`

Примеры:

/{culture}/api/plagiarism-check-rp/{id}/reference?utc=300
/{culture}/api/plagiarism-check-rp/{id}/reference?utc=-600

Возвращает файл формата PDF с заголовком HTTP content-type: application/pdf.

📝 Интерактивный просмотр отчета

Постоянная ссылка на средство просмотра отчета `[editable]`

/{culture}/api/permanent-viewer/{id} - метод возвращает постоянную ссылку для открытия средства просмотра отчета.

GET, Authorization: Bearer <Token>

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

{
  "permanent-link": "https://example.com/document/[\d]"
}

где permanent-link - это бессрочная ссылка на средство просмотра отчетов.

Одноразовая ссылка на средство просмотра отчета `[readonly]`

/{culture}/api/one-time-viewer/{id} - метод возвращает одноразовую ссылку для открытия средства просмотра отчета.

GET, Authorization: Bearer <Token>

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

{
  "one-time-link": "https://example.com/document/[\d]",
  "expires": "2024-03-21T20:17:00.0903957Z"    
}

где one-time-link - это одноразовая ссылка на средство просмотра отчета, а expires - дата и время истечения срока действия ссылки

📋 API

Основные коды состояния ответа HTTP

🌍 Локализация

💬 Информационное сообщение

⛔ Сообщение об ошибке

👮 Аутентификация/Авторизация

Получение токена

Заголовок HTTP-аутентификации/авторизации

Перевыпуск токена

📇 Основная информация

Получение оргструктур

Получение папок пользователя

👥 B2B-пользователи

Создание B2B-пользователя

🔎 Поисковый индекс

Добавление документа в поисковый индекс

Удаление документа из поискового индекса

Массовые операции с поисковым индексом

Обновление поискового индекса

Очистка поискового индекса

🕵🏿‍♀️ Проверка на плагиат

Отправка документа на проверку

Получение состояния проверки

Управление результатом проверки

Подробный отчет в формате PDF

Краткий отчет в формате PDF

Справка в формате PDF

📝 Интерактивный просмотр отчета

Постоянная ссылка на средство просмотра отчета [editable]

Одноразовая ссылка на средство просмотра отчета [readonly]

Постоянная ссылка на средство просмотра отчета `[editable]`

Одноразовая ссылка на средство просмотра отчета `[readonly]`