Изменения в версии 1.2015-11-10

Методы API Сайта

Все запросы в ходе интеграции осуществляются методом POST в кодировке UTF-8 и Content-Type: application/json. Все значения параметров интерпретируются как строки, если это не оговорено дополнительно.

POST https://litera5.ru/api/pub/setup/

Настройки API Партнёра

Запрос SetupRequest (JSON)

	Параметр	Пример значения	Обязательный	Описание
новый параметр	onInitialStats	http://cms.company.ru/initial\_stats.php	нет	URL в CMS Партнёра, на который будет отправлен запрос со статистикой по окончании первичной проверки документа пользователя. Так как ответ будет передан запросом POST, то `onInitialStats` не должен содержать параметров в формате “?param=value&param1=value”.
изменён алгоритм	signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму `md5(time + company + onSaveCorrected + onIFrameFailure + onInitialStats + returnIcon + returnCaption + cancelIcon + cancelCaption + allowResizeImages + showCancelButton + editorCss + getStats + API\_SECRET\_KEY )`. Если какие-то поля отсутствуют в запросе, то при вычислении подписи они заменяются пустой строкой.

POST https://litera5.ru/api/pub/user/

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

Запрос UserRequest (JSON)

	Параметр	Пример значения	Обязательный	Описание
новый параметр	permissions	[“USE_DICTIONARY”]	нет	Список разрешений для пользователя. Для вычисления signature все значения собираются в строчку без каких либо разделителей. Если при создании пользователя никаких разрешений не указано, то считается, что пользователь создаётся с разрешениями по умолчанию, а именно: [“USE_DICTIONARY ”]. Если необходимо создать пользователя, которому не разрешено работать со словарём, то необходимо передать пустой список разрешений: []. Допустимые разрешения: • USE_DICTIONARY – Работа с корпоративным словарём (добавлять, редактировать)
новый параметр	orthoKinds	[“mkSpelling”, “mkGrammar”]	нет	Список типов аннотаций правописания, которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка: • mkSpelling – орфография • mkGrammar - грамматика • mkPunctuation - пунктуация • mkStyle - стилистика • mkSemantic - семантика • mkTypography - типографика • mkOrthoepy - орфоэпия • mkYo - буква ё • mkPaperStructure - оформление
новый параметр	ciceroKinds	[“mkSynonym”]	нет	Список типов аннотаций алгоритма “Цицерон”, которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка: • mkSynonym - синонимы • mkEpithet - эпитеты
изменён алгоритм	signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму `md5(time + company + login + name + password + permissions + orthoKinds + ciceroKinds + API\_SECRET\_KEY )`.

POST https://litera5.ru/api/pub/check/

Инициирует процедуру проверки документа.

Запрос на проверку документа CheckRequest (JSON)

Параметр Пример значения Обязательный Описание

новый параметр

custom

	Параметр	Пример значения	Обязательный	Описание
новый параметр	custom	[{“name”: “description”, “value”: “ Дополнительное описание документа ”}]	нет	Список дополнительных произвольных полей для проверки. Каждый элемент списка – это объект с атрибутами: name, value. name – это название произвольного поля, value – это html для проверки. Важно! На проверку нужно передавать именно html, а не простой текст. Простой текст лучше обернуть тэгом . Это связано с особенностями реализации дополнительных полей в редакторе. На деле – это обычные визуально оформленные специальным образом. Если внутри такого будет находиться элемент , то при нажатии клавиши Enter редактор создаст новый параграф в элементе внутри элемента . Если же разместить текст непосредственно внутри без дополнительного элемента , то при нажатии клавиши Enter, редактор сдублирует элемент в котором располагался текст. Поэтому, если текст для проверки в дополнительных полях будет передан без обёртки в html тэги, то он будет обёрнут в тэг принудительно. Необходимо иметь это ввиду. Для того, чтобы пользователь видел какое именно дополнительное поле он редактирует можно добавить текстовую метку с описанием поля. Текстовая метка располагается над выделенным блоком дополнительного поля. Текстовые метки реализованы при помощи CSS. Поэтому если вам нужно подписать свои произвольные дополнительные поля, то нужно выполнить следующие процедуры: • скачать архив с материалами PHP API • из каталога examples взять файл примера custom.css • для каждого вашего дополнительного поля добавить в него следующий блок: • `.litera5-meta .meta-custom-<NAME>:before {<br>content: 'Ваша метка для поля:'<br>}` • вместо необходимо использовать название вашего дополнительного поля, совпадающее со значением атрибута name соответствующего объекта в списке custom • разместить полученный CSS файл в своей CMS • настроить API Литеры методом setup, чтобы она использовала этот файл для работы с документом (параметр editorCss метода setup) При формировании подписи запроса нужно собрать в строчку последовательно все элементы списка custom без разделителей, сначала name, а затем value. Например: список [{name: “n1”, value: “v1”}, {name: “n2”, value: “v2”}] станет строчкой “n1v1n2v2”
добавлены новые возможности	html	Загаловак текст с ашипками	нет	Собственно текст для проверки в формате html. Если указан `document`, и не указан `html`, тогда откроется редактор с последней версией документа сохранённого на Сайте. Если текст указан, то он заместит собой текст выбранного `document` или инициирует процесс создания нового документа. Либо `documentId` либо `html` должно быть обязательно указано. Для того, чтобы в редакторе показывались иллюстрации к тексту, нужно в поле `src` тэга `img` указывать абсолютный путь к файлу иллюстрации. Если вам необходимо сохранить какие-то дополнительные атрибуты тэгов, то их можно сохранить в атрибутах с префиксом `data-litera5-api-`. Например, в вашей базе данных хранятся относительные пути к иллюстрациям, или пути с переменными чтобы редактор смог корректно отобразить иллюстрации в атрибут `src` нужно поместить абсолютную ссылку, но хочется сохранить и внутреннюю ссылку, её можно поместить в атрибут `data-litera5-api-src` при отправке на проверку и восстановить из этой ссылки при получении результатов. Если возникает необходимость исключить из проверки какие-то части текста, например, примеры кода программ, сложные таблицы, галереи изображений и тому подобное, то для этого нужно поместить соответствующие блоки html в с одним из следующих атрибутов: • data-litera5-nocheck – когда нужно исключить содержимое элемента из проверки. • data-litera5-hidden – когда нужно исключить содержимое элемента из проверки и вообще не показывать его пользователю
изменён алгоритм	signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму `md5(time + company + login + token + document + name + title + description + keywords + custom.map(name + value) + html + API\_SECRET\_KEY)`.

[{“name”: “description”, “value”: “

Дополнительное описание документа

”}]

нет

Список дополнительных произвольных полей для проверки. Каждый элемент списка – это объект с атрибутами: name, value. name – это название произвольного поля, value – это html для проверки.
Важно! На проверку нужно передавать именно html, а не простой текст. Простой текст лучше обернуть тэгом
. Это связано с особенностями реализации дополнительных полей в редакторе. На деле – это обычные
визуально оформленные специальным образом. Если внутри такого

будет находиться элемент

, то при нажатии клавиши Enter редактор создаст новый параграф в элементе

внутри элемента

. Если же разместить текст непосредственно внутри

без дополнительного элемента

, то при нажатии клавиши Enter, редактор сдублирует элемент

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

принудительно. Необходимо иметь это ввиду.
Для того, чтобы пользователь видел какое именно дополнительное поле он редактирует можно добавить текстовую метку с описанием поля. Текстовая метка располагается над выделенным блоком дополнительного поля. Текстовые метки реализованы при помощи CSS. Поэтому если вам нужно подписать свои произвольные дополнительные поля, то нужно выполнить следующие процедуры:
• скачать архив с материалами PHP API
• из каталога examples взять файл примера custom.css
• для каждого вашего дополнительного поля добавить в него следующий блок:
• .litera5-meta .meta-custom-<NAME>:before {<br>content: 'Ваша метка для поля:'<br>}
• вместо необходимо использовать название вашего дополнительного поля, совпадающее со значением атрибута name соответствующего объекта в списке custom
• разместить полученный CSS файл в своей CMS
• настроить API Литеры методом setup, чтобы она использовала этот файл для работы с документом (параметр editorCss метода setup)
При формировании подписи запроса нужно собрать в строчку последовательно все элементы списка custom без разделителей, сначала name, а затем value. Например: список [{name: “n1”, value: “v1”}, {name: “n2”, value: “v2”}] станет строчкой “n1v1n2v2”

добавлены новые возможности

html

Загаловак

текст с ашипками

нет

Собственно текст для проверки в формате html. Если указан *document*, и не указан *html*, тогда откроется редактор с последней версией документа сохранённого на Сайте. Если текст указан, то он заместит собой текст выбранного *document* или инициирует процесс создания нового документа. Либо documentId либо *html* должно быть обязательно указано.
Для того, чтобы в редакторе показывались иллюстрации к тексту, нужно в поле src тэга img указывать абсолютный путь к файлу иллюстрации. Если вам необходимо сохранить какие-то дополнительные атрибуты тэгов, то их можно сохранить в атрибутах с префиксом data-litera5-api-. Например, в вашей базе данных хранятся относительные пути к иллюстрациям, или пути с переменными чтобы редактор смог корректно отобразить иллюстрации в атрибут src нужно поместить абсолютную ссылку, но хочется сохранить и внутреннюю ссылку, её можно поместить в атрибут data-litera5-api-src при отправке на проверку и восстановить из этой ссылки при получении результатов.
Если возникает необходимость исключить из проверки какие-то части текста, например, примеры кода программ, сложные таблицы, галереи изображений и тому подобное, то для этого нужно поместить соответствующие блоки html в
с одним из следующих атрибутов:
• data-litera5-nocheck – когда нужно исключить содержимое элемента из проверки.
• data-litera5-hidden – когда нужно исключить содержимое элемента из проверки и вообще не показывать его пользователю

изменён алгоритм signature 5eb63bbbe01eeed093cb22bb8f5acdc3 да Электронная подпись запроса, формируется по алгоритму md5(*time* + *company* + *login* + *token* + *document* + *name* + *title* + *description* + *keywords* + *custom.map(name + value)* + *html* + **API\_SECRET\_KEY**).

Методы API Партнёра

Все запросы в ходе интеграции осуществляются методом POST в кодировке UTF-8 и Content-Type: application/json. Все значения параметров интерпретируются как строки, если это не оговорено дополнительно.

POST on-save-corrected (SetupRequest.onSaveCorrected)

Партнёру необходимо реализовать этот метод в своей CMS для того, чтобы сохранять документы откорректированные в системе Сайта.

Запрос SaveCorrectedRequest (JSON)

	Параметр	Пример значения	Обязательный	Описание
новый параметр	custom	[{“name”: “description”, “value”: “ Дополнительное описание документа ”}]	нет	Отредактированные произвольные дополнительные поля
изменён алгоритм	signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму `md5(time + token + title + description + keywords + custom.map(name + value) + html + API\_SECRET\_KEY)`

Новый метод: POST on-initial-stats (SetupRequest.onInitialStats)

Партнёру необходимо реализовать этот метод в своей CMS для того, чтобы иметь возможность получать статистический отчёт полученный в результате первой проверки документа. Это может понадобиться, например, в случае, если Партнёр желает отправлять документ на доработку только в случае наличия “критического” количества ошибок. На этот случай предполагается следующий алгоритм действий:

После запроса CheckRequest создаётся iframe по соответствующей одноразовой ссылке, но не показывается пользователю, а запускается и прячется.
Одновременно с этим запускается периодический опрос сервера CMS с ожиданием результатов проверки.
Когда приходит этот запрос

Запрос InitialStatsRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
token	любаяСтрока	да	Идентификатор переданный в ходе запроса CheckRequest.token.
error	Сообщение об ошибке	нет	Сообщение о произошедшей ошибке. Одно из полей error или stats будет заполнено обязательно. И они не могут быть заполнены одновременно. Наличие сообщения об ошибке означает, что документ не смог провериться из-за проблем в Литере.
stats	{“annotations”: [], “words”: []}	нет	JSON модель статистического отчёта (описание формата модели).
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму `md5(time + token + cancelId + error + API\_SECRET\_KEY )`

Ответ InitialStatsResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
cancel	false	да	Значение true означает, что работа с документом завершена и не будет продолжена пользователем.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму `md5(time + cancel + API\_SECRET\_KEY)`