- Терминология
- История изменений
- Скачать API и примеры использования
- Диаграмма взаимодействия
- Методы API Сайта
- POST https://litera5.ru/api/pub/setup/
- POST https://litera5.ru/api/pub/user/
- 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 Партнёра
Терминология
- Сайт – веб-сайт системы Литера5.
- Партнёр – веб-сайт интегрирующийся с Сайтом.
- Пользователь – Пользователь веб-сайта Партнера, которому нужно выполнить проверку документа.
- API_SECRET_KEY – секретный ключ Партнёра, выдаётся Администрацией Сайта по запросу Партнёра. Этот ключ желательно держать втайне, поскольку именно он будет использоваться для подтверждения полномочий Пользователей при работе с Сайтом.
История изменений
Дата | Что изменилось |
---|---|
18 марта 2015 года |
|
15 мая 2015 года |
|
15 сентября 2015 года |
|
30 октября 2015 года |
|
10 ноября 2015 года |
|
1 февраля 2016 года |
|
9 мая 2016 года |
|
12 апреля 2017 года |
|
10 июля 2017 года |
|
16 октября 2017 года |
|
13 ноября 2017 года |
|
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¶m1=value". |
onIFrameFailure | http://cms.company.ru/iframe_failure.php | нет | URL в CMS Партнёра, на который будет отправлен запрос в случае критической ошибки. Так как ответ будет передан запросом POST, то `onIFrameFailure` не должен содержать параметров в формате "?param=value¶m1=value". |
onInitialStats | http://cms.company.ru/initial_stats.php | нет | URL в CMS Партнёра , на который будет отправлен запрос со статистикой по окончании первичной проверки документа пользователя. Так как ответ будет передан запросом POST, то ` onInitialStats ` не должен содержать параметров в формате "?param=value¶m1=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 "]. Если необходимо создать пользователя, которому не разрешено работать со словарём, то необходимо передать пустой список разрешений: []. Допустимые разрешения:
|
orthoKinds | ["mkSpelling", "mkGrammar"] | нет | Список типов аннотаций правописания, которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка:
|
ciceroKinds | ["mkSynonym"] | нет | Список типов аннотаций алгоритма «Цицерон», которые нужно показывать пользователю после проверки. Пустой список означает, что пользователю нужно будет выбирать их каждый раз после проверки документа. Возможные значения списка:
|
qualityKinds | ["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": "<p>Дополнительное описание документа</p>"}] | нет | Список дополнительных произвольных полей для проверки. Каждый элемент списка – это объект с атрибутами: name, value. name – это название произвольного поля, value – это html для проверки. Важно! На проверку нужно передавать именно html, а не простой текст. Простой текст лучше обернуть тэгом <p></p>. Это связано с особенностями реализации дополнительных полей в редакторе. На деле – это обычные <div></div> визуально оформленные специальным образом. Если внутри такого <div> будет находиться элемент <p>, то при нажатии клавиши Enter редактор создаст новый параграф в элементе <p> внутри элемента <div>. Если же разместить текст непосредственно внутри <div> без дополнительного элемента <p>, то при нажатии клавиши Enter, редактор сдублирует элемент <div> в котором располагался текст. Поэтому, если текст для проверки в дополнительных полях будет передан без обёртки в html тэги, то он будет обёрнут в тэг <p> принудительно. Необходимо иметь это ввиду. Для того, чтобы пользователь видел какое именно дополнительное поле он редактирует можно добавить текстовую метку с описанием поля. Текстовая метка располагается над выделенным блоком дополнительного поля. Текстовые метки реализованы при помощи CSS. Поэтому если вам нужно подписать свои произвольные дополнительные поля, то нужно выполнить следующие процедуры:
При формировании подписи запроса нужно собрать в строчку последовательно все элементы списка custom без разделителей, сначала name, а затем value. Например: список [{name: "n1", value: "v1"}, {name: "n2", value: "v2"}] станет строчкой "n1v1n2v2" |
html | <h1>Загаловак</h1><p>текст с ашипками</p> | нет | Собственно текст для проверки в формате html. Если указан `document`, и не указан `html`, тогда откроется редактор с последней версией документа сохранённого на Сайте. Если текст указан, то он заместит собой текст выбранного `document` или инициирует процесс создания нового документа. Либо `documentId` либо `html` должно быть обязательно указано. Для того, чтобы в редакторе показывались иллюстрации к тексту, нужно в поле `src` тэга `img` указывать абсолютный путь к файлу иллюстрации. Если вам необходимо сохранить какие-то дополнительные атрибуты тэгов, то их можно сохранить в атрибутах с префиксом `data-litera5-api-`. Например, в вашей базе данных хранятся относительные пути к иллюстрациям, или пути с переменными чтобы редактор смог корректно отобразить иллюстрации в атрибут `src` нужно поместить абсолютную ссылку, но хочется сохранить и внутреннюю ссылку, её можно поместить в атрибут `data-litera5- api- src` при отправке на проверку и восстановить из этой ссылки при получении результатов. Если возникает необходимость исключить из проверки какие-то части текста, например, примеры кода программ, сложные таблицы, галереи изображений и тому подобное, то для этого нужно поместить соответствующие блоки html в <div></div> с одним из следующих атрибутов:
|
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 | <h1>Загаловак</h1><p>текст с ашипками</p> | да | Оригинальные текст для проверки в формате html. Если указан `document`, то текст заместит собой текст выбранного `document`. Этот текст используется для отображения проверок в интерфейсе Литеры. |
ogxt | Загаловак | да | Текст для проверки в формате 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 | <h1>Загаловак<h1><p>текст с ашипками</p> | нет | 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": "<p>Дополнительное описание документа</p>"}] | нет | Отредактированные произвольные дополнительные поля |
html | <h1>Заголовок</h1><p>текст без ошибок</p> | нет | Отредактированный текст документа. Если не указан, то это означает, что пользователь нажал кнопку "Отменить правки и вернуться в 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)` |