litera5.api.v1

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

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

ДатаЧто изменилось
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 Сайта

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

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

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

Запрос SetupRequest (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
companyhitsoftдаИдентификатор Партнёра, указанный при регистрации на Сайте.
onSaveCorrectedhttp://cms.company.ru/save_corrected.phpнетURL в CMS Партнёра , на который будет отправлен запрос по окончании работы Пользователя с документом. Так как ответ будет передан запросом POST, то ` onSaveCorrected ` не должен содержать параметров в формате "?param=value&param1=value".
onIFrameFailurehttp://cms.company.ru/iframe_failure.phpнетURL в CMS Партнёра, на который будет отправлен запрос в случае критической ошибки. Так как ответ будет передан запросом POST, то `onIFrameFailure` не должен содержать параметров в формате "?param=value&param1=value".
onInitialStatshttp://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".
cancelIconhttp://cms.company.ru/cancel-logo.pngнетURL картинки размером 32х32, которая будет размещена на кнопке "Отменить правки и вернуться в CMS".
cancelCaptionОтменить и вернуться в CMSнетПодпись для кнопки "Отменить правки и вернуться в CMS".
allowResizeImagesfalseнетТип логический (boolean), true или false, по умолчанию настройка включена. Если настройка включена, то в редакторе можно изменять размер встроенных картинок.
showCancelButtontrueнетТип логический (boolean), true или false, по умолчанию выключена. Если настройка включена, то в редакторе появляется кнопка " Отменить правки и вернуться в CMS ", при нажатии на которую в CMS будет отправлен пустой запрос `on-save-corrected` (без указания параметра html). Это означает, что пользователь не хочет сохранять сделанные изменения.
editorCsshttp://cms.company.ru/editor.cssнетПолный путь до файла стилей для редактора. (исходники SCSS тем стилей, которые можно взять за основу можно найти на Githab)
getStatstrueнетТип логический (boolean), true или false, по умолчанию настройка выключена. Если настройка включена, то в модели результата для onSaveCorrected вместе с обработанным текстом будет модель статистического отчёта в формате JSON.

hideEditorToolbar

falseнетТип логический (boolean), true или false, по умолчанию выключена. Если настройка включена, то в редакторе при работе через API тулбар будет пустым.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + company + onSaveCorrected + onIFrameFailure + onInitialStats + returnIcon + returnCaption + cancelIcon + cancelCaption + allowResizeImages + showCancelButton + editorCss + getStats + hideEditorToolbar + API_SECRET_KEY )`. Если какие-то поля отсутствуют в запросе, то при вычислении подписи они заменяются пустой строкой.

Ответ SetupResponse (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + API_SECRET_KEY)`.

 

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

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

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

Запрос UserRequest (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
companyhitsoftдаИдентификатор Партнёра, указанный при регистрации на Сайте .
loginuserдаИдентификатор пользователя на Сайте. Логин пользователя на Сайте формируется из полей `login` и `company` по формуле "login@company". Идентификатор пользователя не может быть пустым и должен состоять из строчных (маленьких) букв английского алфавита, цифр или знака точки.
nameВасилий ИвановичнетИмя которое будет выводиться в кабинете пользователя и в отчётах. Если не указано для нового пользователя, то будет использован `login`.
passwordlthgfhjkmнетПароль для нового пользователя, или при необходимости его сменить. Если пароль для нового пользователя не указан, он будет сгенерирован автоматически.
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 (сколько угодно проверок).
checksCicero0нетМаксимальное количество проверок красоты. -1 означает, что можно делать сколько угодно проверок. 0 означает, что вкладки "Красота" не будет вовсе. По умолчанию -1 (сколько угодно проверок).
checksQuality2нетМаксимальное количество проверок качества. -1 означает, что можно делать сколько угодно проверок. 0 означает, что вкладки "Качество" не будет вовсе. По умолчанию -1 (сколько угодно проверок).
checksTotal3нетМаксимальное количество проверок суммарно для всех вкладок. -1 означает, что можно делать сколько угодно проверок. По умолчанию -1 (сколько угодно проверок). Если задано ограничение checksTotal, например: 10, то когда пользователь выполнит десятую проверку, во всех вкладках у него исчезнут кнопки "Проверить...", и одиннадцатую проверку он выполнить не сможет ни в одной из вкладок, даже если для каждой конкретной вкладки вы не задавали ограничений.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + company + login + name + password + permissions + orthoKinds + ciceroKinds + qualityKinds + checksOrtho + checksCicero + checksQuality + checksTotal + API_SECRET_KEY )`.

Ответ UserResponse (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
passwordlthgfhjkmнетСгенерированный пароль для нового пользователя, если он был создан в ходе запроса.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + password   + API_SECRET_KEY )`.

 

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

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

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

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
companyhitsoftдаИдентификатор Партнёра, указанный при регистрации на Сайте .
loginuserдаЛогин пользователя на Сайте, который работает с документом.
tokenлюбаяСтрокадаПараметр содержащий закодированную информацию о том, какой именно документ и для какого пользователя возвращается в запросе по `SetupRequest.onSaveCorrected`. Это может быть информация закодированная в строку, например "${userId}-${documentId}" или же можно в базе данных создать запись с детальными параметрами, а сюда передать только номер записи. В любом случае по этому параметру должно быть возможно определить куда девать результирующий текст.
document539557f78dfdedee48e136f8нетИдентификатор документа в системе Сайта. Если указан, то будет продолжена работа над тем же самым документом, если нет, то будет создан новый документ. Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в Литере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. Поэтому если вам нужно подписать свои произвольные дополнительные поля, то нужно выполнить следующие процедуры:

  • скачать архив с материалами PHP API
  • из каталога examples взять файл примера custom.css
  • для каждого вашего дополнительного поля добавить в него следующий блок:
    • .litera5-meta .meta-custom-<NAME>:before {
      content: 'Ваша метка для поля:'
      }
    • вместо <NAME> необходимо использовать название вашего дополнительного поля, совпадающее со значением атрибута name соответствующего объекта в списке custom
  • разместить полученный CSS файл в своей CMS
  • настроить API Литеры методом setup, чтобы она использовала этот файл для работы с документом (параметр editorCss метода setup)
При формировании подписи запроса нужно собрать в строчку последовательно все элементы списка 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> с одним из следующих атрибутов:

  • data-litera5-nocheck – когда нужно исключить содержимое элемента из проверки.
  • data-litera5-hidden – когда нужно исключить содержимое элемента из проверки и вообще не показывать его пользователю
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + company + login + token + document + name + title + description + keywords + custom.map(name + value) + html + API_SECRET_KEY)`.

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
document539557f78dfdedee48e136f8даИдентификатор документа в системе Сайта созданный в результате запроса.
url/api/pub/iframe/52fb432f8dfd8b7b0d9a8ff2/

да

Одноразовая ссылка на Сайт редактор документа переданного в запросе, которую можно открывать в новом окне, или в IFRAME в CMS Партнёра. К полученному в этом параметре значению нужно будет добавить "https://litera5.ru", чтобы получить полную ссылку.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `md5(time + document + url + API_SECRET_KEY)`

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

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

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

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
companyhitsoftдаИдентификатор Партнёра, указанный при регистрации на Сайте .
loginuserдаЛогин пользователя на Сайте, который работает с документом.
profileorthoнетТип проверки документа (закладка «правописание» (ortho), «красота» (cicero) или «качество» (quality)). В зависимости от типа проверки подключаются различные наботы правил на которые проверяется текст.
document539557f78dfdedee48e136f8нетИдентификатор документа в системе Сайта. Если указан, то будет продолжена работа над тем же самым документом, если нет, то будет создан новый документ. Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в Литере5 с документом может работать только один пользователь. Поэтому несмотря на то, что в CMS с документом могут работать различные пользователи, при работе с одним и тем же документом в API имеет смысл передавать в `login` не идентификатор текущего пользователя CMS Партнёра, а идентификатор пользователя создавшего данный документ в Литере5 (того пользователя в результате проверки которого был выдан этот `document`). В противном случае API выдаст ошибку о недостатке прав пользователя на работу с документом.
nameНазвание документанетНазвание документа (title, subject). Если не указано, то будет сформировано автоматически из текста.
html<h1>Загаловак</h1><p>текст с ашипками</p>да

Оригинальные текст для проверки в формате html. Если указан `document`, то текст заместит собой текст выбранного `document`. Этот текст используется для отображения проверок в интерфейсе Литеры.

ogxt

Загаловак
текст с ашипками
----------------------------------
[{header: }] 

даТекст для проверки в формате ogxt полученный из текста html, например при помощи утилит ogxt-utils
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + company + login + profile + document + name + html + ogxt + API_SECRET_KEY)`.

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
document539557f78dfdedee48e136f8даИдентификатор документа в системе Сайта созданный в результате запроса.
check539557f78dfdedee48e136f9даИдентификатор проверки инициированной запросом (потребуется для получения результатов проверки и уточнения статуса проверки)
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `md5(time + document + check + API_SECRET_KEY)`

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

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

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

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
companyhitsoftдаИдентификатор Партнёра, указанный при регистрации на Сайте .
check539557f78dfdedee48e136f8даИдентификатор проверки в системе Сайта полученный в CheckOgxtResponse при запросе check-ogxt.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + company + check + API_SECRET_KEY)`.

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

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
stateCHECKED_SUCCESSдаТекущее состояние проверки. Все возможные значения можно разделить на три группы: Проверка благополучно завершена (CHECKED_SUCCESS), проверка не удалась (ESTIMATED_ERROR, ESTIMATED_REJECT, CANCELLED, REJECTED, CHECKED_ERROR) и проверка ещё не закончилась (CREATED, UPLOADED, WAITING_ESTIMATION, ESTIMATING, ESTIMATED_SUCCESS, WAITING_CHECK, CHECKING)
progress100даПрогресс проверки в целых процентах (число)
messageПроверка завершенадаДополнительное текстовое сообщение разъясняющее текущее состояние (в случае ошибочных состояний здесь будет поясняющее объяснение сложившейся ситуации)
html<h1>Загаловак<h1><p>текст с ашипками</p>нетHTML который был подвергнут проверке в который можно встраивать результаты (на случай, если текст уже изменился)
annotations[]нетJSON модель результатов проверки ( описание формата модели ).
stats{"annotations": [], "words": []}нетJSON модель статистического отчёта ( описание формата модели ).
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `md5(time + state + progress + message + html + API_SECRET_KEY)`

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

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

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

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

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

POST on-save-corrected (SetupRequest.onSaveCorrected)

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

Запрос SaveCorrectedRequest (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате 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.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись запроса, формируется по алгоритму `md5(time + token + title + description + keywords + custom.map(name + value) + html + API_SECRET_KEY)`

Ответ SaveCorrectedResponse (JSON)

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

 

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

POST on-iframe-failure (SetupRequest.onIFrameFailure)

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

Запрос IFrameFailureRequest (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
tokenлюбаяСтрокадаИдентификатор переданный в ходе запроса CheckRequest.token .
urlhttps://litera5.ru/api/pub/iframe/52fb432f8dfd8b7b0d9a8ff2/даУрл при обработке которого произошла ошибка
code404даКод ошибки произошедшей при обработке одноразовой ссылки (CheckResponse.url).

message

Не найдена одноразовая ссылка на проверкудаВ случае, если при обработке одноразовой ссылки произошла какая-то ошибка,  Пользователю  будет показано соответствующее сообщение об ошибке с кнопкой-предложением  "Вернуться в CMS" . Это же сообщение передаётся на сервер при помощи этого метода.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `md5(time + token + url + code + message + API_SECRET_KEY )`

Ответ IFrameFailureResponse (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
url http://cms.company.ru/page/iframe_out.php?12345 даСсылка на страницу CMS Партнёра на которую будет перенаправлен ответ при помощи HTTP 302 редиректа.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `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 для того, чтобы иметь возможность получать статистический отчёт полученный в результате первой проверки документа. Это может понадобиться, например, в случае, если Партнёр желает отправлять документ на доработку только в случае наличия "критического" количества ошибок. На этот случай предполагается следующий алгоритм действий:

Запрос InitialStatsRequest (JSON)

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

Ответ InitialStatsResponse (JSON)

ПараметрПример значенияОбязательныйОписание
time1410103972даТекущее время в формате unix timestamp (количество секунд с 1970 года)
cancelfalseдаТип логический (boolean). Значение true означает, что работа с документом завершена и не будет продолжена пользователем.
signature5eb63bbbe01eeed093cb22bb8f5acdc3даЭлектронная подпись ответа, формируется по алгоритму `md5(time + cancel + API_SECRET_KEY)`