• Терминология
• История изменений
• Скачать API и примеры использования
• Диаграмма взаимодействия
• Методы API Сайта
  • POST https://litera5.ru/api/pub/setup/
    • Запрос SetupRequest (JSON)
    • Ответ SetupResponse (JSON)
  • POST https://litera5.ru/api/pub/user/
    • Запрос UserRequest (JSON)
    • Ответ UserResponse (JSON)
  • POST https://litera5.ru/api/pub/check/
    • Запрос на проверку документа CheckRequest (JSON)
    • Ответ на запрос на проверку документа CheckResponse (JSON)
  • POST https://litera5.ru/api/pub/check-ogxt/
    • Запрос на проверку документа CheckOgxtRequest (JSON)
    • Ответ на запрос на проверку документа CheckOgxtResponse (JSON)
  • POST https://litera5.ru/api/pub/check-ogxt-results/
    • Запрос на результаты проверки документа CheckOgxtResultsRequest (JSON)
    • Ответ на запрос на результаты проверки документа CheckOgxtResultsResponse (JSON)
  • GET https://litera5.ru/api/pub/iframe/${one-off-link}/
• Методы API Партнёра
  • POST on-save-corrected (SetupRequest.onSaveCorrected)
    • Запрос SaveCorrectedRequest (JSON)
    • Ответ SaveCorrectedResponse (JSON)
  • POST on-iframe-failure (SetupRequest.onIFrameFailure)
    • Запрос IFrameFailureRequest (JSON)
    • Ответ IFrameFailureResponse (JSON)
  • GET return-to-cms (SaveCorrectedResponse.url, IFrameFailureResponse.url)
  • POST on-initial-stats (SetupRequest.onInitialStats)
    • Запрос InitialStatsRequest (JSON)
    • Ответ InitialStatsResponse (JSON)

Терминология

• Сайт – веб-сайт системы Литера5.
• Партнёр – веб-сайт интегрирующийся с Сайтом.
• Пользователь – Пользователь веб-сайта Партнера, которому нужно выполнить проверку документа.
• API_SECRET_KEY – секретный ключ Партнёра, выдаётся Администрацией Сайта по запросу Партнёра. Этот ключ желательно держать втайне, поскольку именно он будет использоваться для подтверждения полномочий Пользователей при работе с Сайтом.

История изменений

Дата	Что изменилось
18 марта 2015 года	• Добавлена возможность использовать новую кнопку “Отменить правки и вернуться в CMS” • Добавлена возможность запрещать изменение размеров изображений в проверяемом тексте • Стандартизована процедура использования дополнительных атрибутов для тэгов html Подробнее
15 мая 2015 года	• Добавлена возможность использовать собственные стили в редакторе • Добавлена возможность передавать на проверку не только текст, но и заголовок, описание и ключевые слова Подробнее
15 сентября 2015 года	• Добавлена возможность получать последний статистический отчёт после проверки Подробнее
30 октября 2015 года	• Изменена версия SSL в PHP API. SSL v.3 -> TLS v.1
10 ноября 2015 года	• Добавлена возможность задавать права доступа для пользователя (работа со словарём) • Добавлена возможность передавать на проверку любые произвольные дополнительные текстовые блоки (по аналогии с заголовоком, описанием и т.д.) • Добавлена возможность прятать некоторые части страницы от проверки на ошибки • Добавлена возможность прятать некоторые части страницы от взора пользователя и от проверки на ошибки • Добавлена возможность задавать типы аннотаций по умолчанию для пользователя • Добавлена возможность уведомления об окончании первичной проверки документа • Добавлено описание варианта интеграции с “автоматической” проверкой • Добавлен пример реализации этой проверки на PHP (новый каталог в архиве) Подробнее
1 февраля 2016 года	• В запрос IFrameFailureRequest добавлен параметр token Подробнее
9 мая 2016 года	• Добавлены дополнительные права пользователя (DISABLE_CICERO, DISABLE_API_SECONDARY_ORFO_CHECKS) Подробнее
12 апреля 2017 года	• Добавлена возможность проверки текста в формате OGXT без участия в этом процессе пользователя • Добавлена реализация API на JavaScript • Материалы API опубликованы на Github Подробнее
10 июля 2017 года	• Добавлена возможность скрывать тулбар редактора при работе через API Подробнее
16 октября 2017 года	• Добавлена новая проверка водности на вкладке «Качество» Подробнее
13 ноября 2017 года	• Добавлена возможность ограничивать максимальное количество проверок через API Подробнее
3 октября 2020 года	• Добавлен новый метод диагностики Подробнее

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

• Реализация API для PHP
• Реализация API для JavaScript
• Вариант интеграции через iframe с “автоматической” проверкой
• Темы оформления текста в редакторе Литеры
• Если что-то не получается. Инструкция

Диаграмма взаимодействия

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

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

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

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

Запрос SetupRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
company	hitsoft	да	Идентификатор Партнёра, указанный при регистрации на Сайте.
onSaveCorrected	http://cms.company.ru/save_corrected.php	нет	URL в CMS Партнёра , на который будет отправлен запрос по окончании работы Пользователя с документом. Так как ответ будет передан запросом POST, то *onSaveCorrected* не должен содержать параметров в формате “?param=value&param1=value”.
onIFrameFailure	http://cms.company.ru/iframe_failure.php	нет	URL в CMS Партнёра, на который будет отправлен запрос в случае критической ошибки. Так как ответ будет передан запросом POST, то *onIFrameFailure* не должен содержать параметров в формате “?param=value&param1=value”.
onInitialStats	http://cms.company.ru/initial_stats.php	нет	URL в CMS Партнёра , на который будет отправлен запрос со статистикой по окончании первичной проверки документа пользователя. Так как ответ будет передан запросом POST, то *onInitialStats* не должен содержать параметров в формате “?param=value&param1=value”.
returnIcon	http://cms.company.ru/logo.png	нет	URL картинки размером 32х32, которая будет размещена на кнопке “Сохранить правки и вернуться в CMS”. Например логотип компании Партнёра.
returnCaption	Записать и вернуться в CMS	нет	Подпись для кнопки “Сохранить правки и вернуться в CMS”.
cancelIcon	http://cms.company.ru/cancel-logo.png	нет	URL картинки размером 32х32, которая будет размещена на кнопке “Отменить правки и вернуться в CMS”.
cancelCaption	Отменить и вернуться в CMS	нет	Подпись для кнопки “Отменить правки и вернуться в CMS”.
allowResizeImages	false	нет	Тип логический (boolean), true или false, по умолчанию настройка включена. Если настройка включена, то в редакторе можно изменять размер встроенных картинок.
showCancelButton	true	нет	Тип логический (boolean), true или false, по умолчанию выключена. Если настройка включена, то в редакторе появляется кнопка ” Отменить правки и вернуться в CMS ”, при нажатии на которую в CMS будет отправлен пустой запрос on-save-corrected (без указания параметра html). Это означает, что пользователь не хочет сохранять сделанные изменения.
editorCss	http://cms.company.ru/editor.css	нет	Полный путь до файла стилей для редактора. (исходники SCSS тем стилей, которые можно взять за основу можно найти на Githab)
getStats	true	нет	Тип логический (boolean), true или false, по умолчанию настройка выключена. Если настройка включена, то в модели результата для onSaveCorrected вместе с обработанным текстом будет модель статистического отчёта в формате JSON.
hideEditorToolbar	false	нет	Тип логический (boolean), true или false, по умолчанию выключена. Если настройка включена, то в редакторе при работе через API тулбар будет пустым.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *company* + *onSaveCorrected* + *onIFrameFailure + onInitialStats + returnIcon + returnCaption + cancelIcon + cancelCaption* + *allowResizeImages* + *showCancelButton + editorCss + getStats + hideEditorToolbar* + **API\_SECRET\_KEY** ). Если какие-то поля отсутствуют в запросе, то при вычислении подписи они заменяются пустой строкой.

Ответ SetupResponse (JSON)

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

Возвращает HTTP код 200 в случае успеха, или в случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа будет получен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа будет utf8 текст с детальным описанием ошибки.

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

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

Запрос UserRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
company	hitsoft	да	Идентификатор Партнёра, указанный при регистрации на Сайте .
login	user	да	Идентификатор пользователя на Сайте. Логин пользователя на Сайте формируется из полей *login* и *company* по формуле “login@company”. Идентификатор пользователя не может быть пустым и должен состоять из строчных (маленьких) букв английского алфавита, цифр или знака точки.
name	Василий Иванович	нет	Имя которое будет выводиться в кабинете пользователя и в отчётах. Если не указано для нового пользователя, то будет использован *login*.
password	lthgfhjkm	нет	Пароль для нового пользователя, или при необходимости его сменить. Если пароль для нового пользователя не указан, он будет сгенерирован автоматически.
permissions	[USE_DICTIONARY]	нет	Список разрешений для пользователя. Для вычисления signature все значения собираются в строчку без каких либо разделителей. Если при создании пользователя никаких разрешений не указано, то считается, что пользователь создаётся с разрешениями по умолчанию, а именно: [“USE_DICTIONARY ”]. Если необходимо создать пользователя, которому не разрешено работать со словарём, то необходимо передать пустой список разрешений: []. Допустимые разрешения: • USE_DICTIONARY — Работа с корпоративным словарём (добавлять, редактировать) • DISABLE_CICERO — Работа с инструментами вкладки Красота ЗАПРЕЩЕНА! (Этот разрешение устаревшие, советуем пользоваться параметром checksCicero для настройки возможности работы с вкладкой) • DISABLE_QUALITY — Работа с инструментами вкладки Качество ЗАПРЕЩЕНА ! (Этот разрешение устаревшие, советуем пользоваться параметром checksQuality для настройки возможности работы с вкладкой) • DISABLE_API_SECONDARY_ORFO_CHECKS — Повторная проверка через API ЗАПРЕЩЕНА! (Этот разрешение устаревшие, советуем пользоваться параметром checksOrtho для настройки возможности работы с вкладкой) • DISABLE_WEB_INTERFACE — Работа пользователя через стандартный веб-интерфейс сервиса Литера5 ЗАПРЕЩЕНА! Можно работать только через стороннее веб-приложение, использующее API Литера5. Это разрешение также можно задавать через административную консоль Литера5 на странице управления пользователями. • Если у пользователя уже заданы параметры запретов-разрешений, а вы хотите перейти на работу с новыми параметрами: checksCicero, checksQuality , checksOrtho — вам нужно выполнить запрос со списком разрешений из одного элемента [“USE_DICTIONARY ”] либо с пустым: [] — если вы хотите также и работу со словарём запретить.
orthoKinds	[“mkSpelling”, “mkGrammar”]	нет	Список типов аннотаций правописания, которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка: • mkSpelling — орфография • mkGrammar — грамматика • mkPunctuation — пунктуация • mkStyle — стилистика • mkSemantic — семантика • mkTypography — типографика • mkYo — буква ё • mkPaperStructure — оформление
ciceroKinds	[“mkSynonym”]	нет	Список типов аннотаций алгоритма «Цицерон», которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка: • mkTautology — тавтологии • mkPhonics — неблагозвучия • mkOrthoepy — орфоэпия • mkSynonym — синонимы • mkEpithet — эпитеты
qualityKinds	[“mkWater”]	нет	Список типов аннотаций вкладки «Качество», которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка: • mkWater — водность текста
checksOrtho	-1	нет	Максимальное количество проверок грамотности (не может быть 0, минимальное значение 1, первая проверка запускается автоматически). -1 означает, что можно делать сколько угодно проверок. По умолчанию -1 (сколько угодно проверок).
checksCicero	0	нет	Максимальное количество проверок красоты. -1 означает, что можно делать сколько угодно проверок. 0 означает, что вкладки “Красота” не будет вовсе. По умолчанию -1 (сколько угодно проверок).
checksQuality	2	нет	Максимальное количество проверок качества. -1 означает, что можно делать сколько угодно проверок. 0 означает, что вкладки “Качество” не будет вовсе. По умолчанию -1 (сколько угодно проверок).
checksTotal	3	нет	Максимальное количество проверок суммарно для всех вкладок. -1 означает, что можно делать сколько угодно проверок. По умолчанию -1 (сколько угодно проверок). Если задано ограничение checksTotal, например: 10, то когда пользователь выполнит десятую проверку, во всех вкладках у него исчезнут кнопки “Проверить…”, и одиннадцатую проверку он выполнить не сможет ни в одной из вкладок, даже если для каждой конкретной вкладки вы не задавали ограничений.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *company* + *login* + *name* + *password* + *permissions* + *orthoKinds* + *ciceroKinds* + *qualityKinds + checksOrtho + checksCicero + checksQuality + checksTotal* + **API\_SECRET\_KEY** ).

Ответ UserResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
password	lthgfhjkm	нет	Сгенерированный пароль для нового пользователя, если он был создан в ходе запроса.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *password* + **API\_SECRET\_KEY** ).

В случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа будет получен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа будет utf8 текст с детальным описанием ошибки.

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

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

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

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
company	hitsoft	да	Идентификатор Партнёра, указанный при регистрации на Сайте .
login	user	да	Логин пользователя на Сайте, который работает с документом.
token	любаяСтрока	да	Параметр содержащий закодированную информацию о том, какой именно документ и для какого пользователя возвращается в запросе по *SetupRequest.onSaveCorrected*. Это может быть информация закодированная в строку, например ”${userId}-${documentId}” или же можно в базе данных создать запись с детальными параметрами, а сюда передать только номер записи. В любом случае по этому параметру должно быть возможно определить куда девать результирующий текст.
document	539557f78dfdedee48e136f8	нет	Идентификатор документа в системе Сайта. Если указан, то будет продолжена работа над тем же самым документом, если нет, то будет создан новый документ. Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в Литере5 с документом может работать только один пользователь. Поэтому несмотря на то, что в CMS с документом могут работать различные пользователи, при работе с одним и тем же документом в API имеет смысл передавать в *login* не идентификатор текущего пользователя CMS Партнёра, а идентификатор пользователя создавшего данный документ в Литере5 (того пользователя в результате проверки которого был выдан этот *document*). В противном случае API выдаст ошибку о недостатке прав пользователя на работу с документом.
name	Название документа	нет	Название документа (title, subject). Если не указано, то будет сформировано автоматически из текста.
title	Заголовок документа	нет	Дополнительное поле. Заголовок документа для проверки. Дополнительные поля будут добавлены в специальную форму для дополнительной проверки.
description	Краткое описание	нет	Дополнительное поле. Краткое описание страницы для проверки.
keywords	Ключевые слова	нет	Дополнительное поле. Ключевые слова страницы для проверки.
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**).

Ответ на запрос на проверку документа CheckResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
document	539557f78dfdedee48e136f8	да	Идентификатор документа в системе Сайта созданный в результате запроса.
url	/api/pub/iframe/52fb432f8dfd8b7b0d9a8ff2/	да	Одноразовая ссылка на Сайт редактор документа переданного в запросе, которую можно открывать в новом окне, или в IFRAME в CMS Партнёра. К полученному в этом параметре значению нужно будет добавить “https://litera5.ru”, чтобы получить полную ссылку.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *document* + *url* + **API\_SECRET\_KEY**)

В случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа будет получен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа будет utf8 текст с детальным описанием ошибки.

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

Запускает проверку документа в формате ogxt без участия пользователя.

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

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
company	hitsoft	да	Идентификатор Партнёра, указанный при регистрации на Сайте .
login	user	да	Логин пользователя на Сайте, который работает с документом.
profile	ortho	нет	Тип проверки документа (закладка «правописание» (ortho), «красота» (cicero) или «качество» (quality)). В зависимости от типа проверки подключаются различные наботы правил на которые проверяется текст.
document	539557f78dfdedee48e136f8	нет	Идентификатор документа в системе Сайта. Если указан, то будет продолжена работа над тем же самым документом, если нет, то будет создан новый документ. Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в Литере5 с документом может работать только один пользователь. Поэтому несмотря на то, что в CMS с документом могут работать различные пользователи, при работе с одним и тем же документом в API имеет смысл передавать в *login* не идентификатор текущего пользователя CMS Партнёра, а идентификатор пользователя создавшего данный документ в Литере5 (того пользователя в результате проверки которого был выдан этот *document*). В противном случае API выдаст ошибку о недостатке прав пользователя на работу с документом.
name	Название документа	нет	Название документа (title, subject). Если не указано, то будет сформировано автоматически из текста.
html	Загаловак текст с ашипками	да	Оригинальные текст для проверки в формате html. Если указан *document*, то текст заместит собой текст выбранного *document*. Этот текст используется для отображения проверок в интерфейсе Литеры.
ogxt	Загаловак текст с ашипками ---------------------------------- [{header: }]	да	Текст для проверки в формате ogxt полученный из текста html, например при помощи утилит ogxt-utils
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *company* + *login* + *profile* + *document* + *name* + *html + ogxt* + **API\_SECRET\_KEY**).

Ответ на запрос на проверку документа CheckOgxtResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
document	539557f78dfdedee48e136f8	да	Идентификатор документа в системе Сайта созданный в результате запроса.
check	539557f78dfdedee48e136f9	да	Идентификатор проверки инициированной запросом (потребуется для получения результатов проверки и уточнения статуса проверки)
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *document* + *check* + **API\_SECRET\_KEY**)

В случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа будет получен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа будет utf8 текст с детальным описанием ошибки.

POST https://litera5.ru/api/pub/check-ogxt-results/

Проверяет текущее состояние проверки и получает результаты в случае её окончания

Запрос на результаты проверки документа CheckOgxtResultsRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
company	hitsoft	да	Идентификатор Партнёра, указанный при регистрации на Сайте .
check	539557f78dfdedee48e136f8	да	Идентификатор проверки в системе Сайта полученный в CheckOgxtResponse при запросе check-ogxt.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *company* + *check* + **API\_SECRET\_KEY**).

Ответ на запрос на результаты проверки документа CheckOgxtResultsResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
state	CHECKED_SUCCESS	да	Текущее состояние проверки. Все возможные значения можно разделить на три группы: Проверка благополучно завершена (CHECKED_SUCCESS), проверка не удалась (ESTIMATED_ERROR, ESTIMATED_REJECT, CANCELLED, REJECTED, CHECKED_ERROR) и проверка ещё не закончилась (CREATED, UPLOADED, WAITING_ESTIMATION, ESTIMATING, ESTIMATED_SUCCESS, WAITING_CHECK, CHECKING)
progress	100	да	Прогресс проверки в целых процентах (число)
message	Проверка завершена	да	Дополнительное текстовое сообщение разъясняющее текущее состояние (в случае ошибочных состояний здесь будет поясняющее объяснение сложившейся ситуации)
html	Загаловак текст с ашипками	нет	HTML который был подвергнут проверке в который можно встраивать результаты (на случай, если текст уже изменился)
annotations	[]	нет	JSON модель результатов проверки ( описание формата модели ).
stats	{“annotations”: [], “words”: []}	нет	JSON модель статистического отчёта ( описание формата модели ).
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *state + progress + message* + *html* + **API\_SECRET\_KEY**)

В случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа будет получен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа будет utf8 текст с детальным описанием ошибки.

GET https://litera5.ru/api/pub/iframe/${one-off-link}/

Одноразовая ссылка редактора документа с возможностью проверки и корректировки, с которым могут работать Пользователи. Инструмент содержит в себе кнопку “Вернуться в CMS” при нажатии на которую работа с документом на Сайте будет прекращена, а текущая версия документа передана для дальнейшей обработки в CMS Партнёра.

В случае, если при обработке одноразовой ссылки произошла какая-то ошибка, Пользователю будет показано соответствующее сообщение об ошибке с кнопкой-предложением “Вернуться в CMS”.

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

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

POST on-save-corrected (SetupRequest.onSaveCorrected)

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

Запрос SaveCorrectedRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
token	любаяСтрока	да	Идентификатор переданный в ходе запроса CheckRequest.token.
title	Заголовок документа	нет	Отредактированный заголовок документа
description	Краткое описание	нет	Отредактированное краткое описание
keywords	Ключевые слова	нет	Отредактированные ключевые слова
custom	[{“name”: “description”, “value”: “ Дополнительное описание документа ”}]	нет	Отредактированные произвольные дополнительные поля
html	Заголовок текст без ошибок	нет	Отредактированный текст документа. Если не указан, то это означает, что пользователь нажал кнопку “Отменить правки и вернуться в CMS”, то есть решил не сохранять сделанные правки в CMS.
stats	{“annotations”: [], “words”: []}	нет	JSON модель статистического отчёта (описание формата модели). Присутствует только если в методе setup настроен параметр getStats.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись запроса, формируется по алгоритму md5(*time* + *token* + *title* + *description* + *keywords* + *custom.map(name + value)* + *html* + **API\_SECRET\_KEY**)

Ответ SaveCorrectedResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
url	http://cms.company.ru/page/iframe_out.php?12345	да	Ссылка на страницу CMS Партнёра на которую будет перенаправлен ответ при помощи HTTP 302 редиректа.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *url* + **API\_SECRET\_KEY**)

В случае ошибки в запросе, ошибка аутентификации, неверного идентификатора документа и тому подобное, в качестве ответа должен быть отправлен соответствующий HTTP код из серии 4xx (Client Error), а в теле ответа utf8 текст с детальным описанием ошибки.

POST on-iframe-failure (SetupRequest.onIFrameFailure)

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

Запрос IFrameFailureRequest (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
token	любаяСтрока	да	Идентификатор переданный в ходе запроса CheckRequest.token .
url	https://litera5.ru/api/pub/iframe/52fb432f8dfd8b7b0d9a8ff2/	да	Урл при обработке которого произошла ошибка
code	404	да	Код ошибки произошедшей при обработке одноразовой ссылки (CheckResponse.url).
message	Не найдена одноразовая ссылка на проверку	да	В случае, если при обработке одноразовой ссылки произошла какая-то ошибка, Пользователю будет показано соответствующее сообщение об ошибке с кнопкой-предложением “Вернуться в CMS” . Это же сообщение передаётся на сервер при помощи этого метода.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *token* + *url* + *code* + *message* + **API\_SECRET\_KEY** )

Ответ IFrameFailureResponse (JSON)

Параметр	Пример значения	Обязательный	Описание
time	1410103972	да	Текущее время в формате unix timestamp (количество секунд с 1970 года)
url	http://cms.company.ru/page/iframe_out.php?12345	да	Ссылка на страницу CMS Партнёра на которую будет перенаправлен ответ при помощи HTTP 302 редиректа.
signature	5eb63bbbe01eeed093cb22bb8f5acdc3	да	Электронная подпись ответа, формируется по алгоритму md5(*time* + *url* + **API\_SECRET\_KEY**)

GET return-to-cms (SaveCorrectedResponse.url, IFrameFailureResponse.url)

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

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

Если Сайт для корректировки был открыт в новом окне, то результатом этого метода может быть JavaScript, который закроет это новое окно и обновит содержимое окна CMS.

Если Сайт был открыт в IFRAME на странице CMS, то результатом этого метода тоже может быть JavaScript, который обновит содержимое основного “родительского” окна при помощи кода

window.top.location.href = 'new url';

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* + *error* + **API\_SECRET\_KEY** )

Ответ InitialStatsResponse (JSON)

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