API. Работа с электронной копией обязательного экземпляра

RSL OEK API
Версия 1.0.0, редакция 1

Протокол	JSON-RPC 2.0
Схема авторизации	BASIC
URL-адрес	https://oek.rsl.ru/api/json-rpc/v1

Работа с электронной копией обязательного экземпляра

1. Создание заявки на предоставление ЭКОЭ

1.1. Примеры запросов

Добавить экземпляр книги:

{

"jsonrpc": "2.0",

"method": "oee.add",

"params": {

"type": 0,

"title": "Война и мир",

"author": "Лев Николаевич Толстой",

"isbn": "5-05-002808-6",

"pubYear": 1970,

"pubPlace": "Москва",

"textBlock": "https://mycompany.com/secret/folder/war-and-peace.pdf",

"textBlockSecret": "myVerySecretPassword"

"id": 1

}

Добавить экземпляр диссертации:

{

"jsonrpc": "2.0",

"method": "oee.add",

"params": {

"type": 3,

"title": "Дидактические условия организации самостоятельной работы на уроках в V-IX классах сельской школы с малой наполняемостью учащихся",

"author": "Щербакова, Елена Викторовна",

"pubYear": 1996,

"pubPlace": "Саранск",

"dissDefenseOrganization": "Мордовский Государственный Педагогический Институт имени М.Е.Евсевьева",

"vakCodes": [

{

"code": "13.00.01",

"title": "Общая педагогика, история педагогики и образования"

}

"dissPageCount": 188,

"dissPictureCount": 0,

"textBlock": "https://mycompany.com/secret/folder/dissertation.pdf",

"textBlockSecret": "myVerySecretPassword"

"id": 1

}

type – тип издания (обязательное поле с целочисленным значением):

0 = книга
1 = журнал
2 = газета
3 = диссертация

ВНИМАНИЕ: по URL-адресу, указанному в поле textBlock, должна быть настроена BASIC-авторизация:

логин: email-адрес аккаунта, с которого производится запрос
пароль: значение поля textBlockSecret

Не рекомендуется использовать в качестве textBlockSecret пароль от вашего аккаунта.

Скачивание PDF-файла, находящегося по URL-адресу, указанному в поле textBlock, будет произведено в фоновом режиме. Это может произойти не сразу, а в течение нескольких часов после создания заявки.

После скачивания PDF-файла он будет отправлен на автоматическую проверку соответствия требованиям, предъявляемым Российской Государственной Библиотекой (РГБ) к электронной копии обязательного экземпляра (в том числе, ошибки несоответствия файла формату PDF/A).

1.2. Список возможных полей в запросе в зависимости от типа документа

Перечень передаваемых полей зависит от типа документа (полужирным помечены поля, обязательные для заполнения):

Книга	Новый экземпляр журнала/газеты	Приложение к журналу/газете	Диссертация
type = 0	type = 1 или type = 2 materialType = 0	type = 1 или type = 2 materialType = 1	type = 3
isbn author title pubYear pubPlace	imprintId currentNumber grossNumber releaseDate	imprintId author title currentNumber releaseDate	author title pubYear pubPlace dissDefenseOrganization vakCodes dissPageCount dissPictureCount
textBlock textBlockSecret

Расшифровка:

Ключ	Тип значения	Расшифровка
isbn	строка	ISBN-номер
author	строка	Автор
title	строка	Заглавие
pubYear	число (не превышает значение следующего года)	Год издания
pubPlace	строка	Место издания
materialType	число из списка	Тип периодического издания: 0 = "новый экземпляр" 1 = "приложение к экземпляру"
imprintId	число из списка	Идентификатор выходных сведений (см. соответствующий раздел)
currentNumber	строка	Текущий номер газеты/журнала
grossNumber	строка	Валовый номер газеты/журнала
releaseDate	строка в формате YYYY-MM-DD	Дата выхода газеты/журнала
dissDefenseOrganization	строка	Полное наименование организации, где защищалась диссертация
vakCodes	массив структур, содержащих поля code и title	Коды специальностей ВАК
vakCodes → code	строка в формате DD.DD.DD, D – цифра	Код специальности
vakCodes → title	строка	Расшифровка кода специальности
dissPageCount	число	Количество страниц в диссертации
dissPictureCount	число	Количество рисунков в диссертации

1.3. Примеры ответов

Успешный ответ:

{

"jsonrpc": "2.0",

"result": {

"oeeId": 12345

"id": 1

}

Здесь oeeId – идентификатор, присвоенный заявке в системе ОЭК РГБ.

Ответ с описанием возникшей ошибки:

{

"jsonrpc": "2.0",

"error": {

"code": -32602,

"message": "Invalid params",

"data": {

"pubYear": "Значение «Год издания» не должно превышать 2020."

}

"id": 1

}

В поле data содержится структура, в которой ключами являются ключи полей, значениями – текстовые описания возникших ошибок.

Подробнее о возможных ошибках см. https://www.jsonrpc.org/specification#response_object

2. Получение информации о заявке на предоставление электронной копии обязательного экземпляра (ЭКОЭ)

2.1. Пример запроса

{

"jsonrpc": "2.0",

"method": "oee.get",

"params": {

"oeeId": 12345

"id": 1

}

Здесь oeeId – идентификатор, присвоенный заявке в системе ОЭК РГБ, полученный в качестве успешного ответа на запрос создания заявки.

2.2. Примеры ответов

Заявка создана, успешно проверена автоматической системой и готова к ЭЦП:

{

"jsonrpc": "2.0",

"result": {

"oeeId": 12345,

"status": 20,

"type": 0,

"title": "Война и мир",

"author": "Лев Николаевич Толстой",

"isbn": "5-05-002808-6",

"pubYear": 1970,

"pubPlace": "Москва"

"id": 1

}

Обнаружены ошибки соответствия формату PDF/A:

{

"jsonrpc": "2.0",

"result": {

"oeeId": 12345,

"status": 120,

"type": 0,

"pdfFormatErrors": [

"Если ключ SMask появляется в словаре ExtGState или XObject, его значение должно быть None."

"title": "Война и мир",

"author": "Лев Николаевич Толстой",

"isbn": "5-05-002808-6",

"pubYear": 1970,

"pubPlace": "Москва",

"isCreatedViaApi": true

"id": 1

}

isCreatedViaApi – флаг, информирующий о том, каким образом была создана данная заявка: через API (true) или через web-интерфейс (false)

status – данные о статусе заявки (обязательное число с целочисленным значением):

1	заявка создана (ожидается загрузка файла)
4	заявка была отклонена оператором
5	заявка была успешно подана на проверку операторам системы (т.е., автоматическая валидация на соответствие формату PDF/A пройдена, заявка подписана с помощью ЭЦП)
6	файл проверяется автоматической системой на корректность и соответствие формату PDF/A
20	файл был успешно проверен автоматической системой на соответствие формату PDF/A, и ожидает подписи с помощью ЭЦП
30	файл был принят на хранение в Электронную Библиотеку
31	файл был принят на хранение в архив
100	обнаружены ошибки при скачивании или проверке на корректность PDF-файла
120	обнаружены ошибки соответствия файла требованиям, предъявляемым Российской Государственной Библиотекой (РГБ) к электронной копии обязательного экземпляра (в том числе, ошибки несоответствия файла формату PDF/A)

Жизненный цикл для заявки с корректным PDF-файлом:

1 (создана) → 6 (проверяется) → 20 (ожидает ЭЦП) → 5 (успешно подана на ручную проверку) → 30/31 (принята)

Некорректный файл:

1 → 6 → 100/120 (обнаружены ошибки)

Отклонённая заявка оператором:

1 → 6 → 20 → 5 → 4 (заявка отклонена)

2.3. Дополнительные поля, возвращаемые при соответствии заявке определённым статусам

status = 4

failreason

описание причины отклонения заявки

status = 100

download_error

parse_error

описание ошибки при скачивании файла

описание ошибки при разборе файла (например, файл не читается или зашифрован)

status = 120

pdfFormatErrors

массив строк, содержащих описания ошибок несоответствия файла требованиям РГБ, в т.ч. ошибок несоответствия файла формату PDF/A

3. Редактирование заявки на предоставление ЭКОЭ

3.1. Пример запроса

{

"jsonrpc": "2.0",

"method": "oee.edit",

"params": {

"oeeId": 12345,

"pubYear": 1980,

"pubPlace": "Ленинград"

"id": 1

}

Список полей аналогичен описанному в п.1.2. Отличие в обязательном поле oeeId, которое является идентификатором заявки, присвоенном системой ОЭК РГБ.

Изменения будут внесены только в указанные поля. Прочие поля сохранят своё оригинальное значение.

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

3.2. Пример ответа

{

"jsonrpc": "2.0",

"result": true,

"id": 1

}