api l5 check

POST check

• Метод: POST
• URL: https://litera5.ru/api/pub/check/
• Content-type: application/json

Метод для запуска проверки текста в редакторе Литеры.

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

Запрос

interface CheckRequest {
    /**
     * Текущее время в формате unix timestamp (количество секунд с 1970 года)
     * 
     * @пример: "1410103972"
     * @обязательный: да
     */
    time: string;
    
    /**
     * Идентификатор Партнёра, указанный при регистрации в Литере.
     * 
     * @пример: "my-company"
     * @обязательный: да
     */
    company: string;
    
    /**
     * Логин пользователя Литеры, который работает с документом.
     * 
     * @пример: "user"
     * @обязательный: да 
     */
    login: string;
    
    /**
     * Параметр содержащий закодированную информацию о том, какой именно документ
     * и для какого пользователя возвращается в запросе по 
     * `SetupRequest.onSaveCorrected`. Это может быть информация закодированная в 
     * строку, например "${userId}-${documentId}" или же можно в базе данных создать 
     * запись с детальными параметрами, а сюда передать только номер записи. В 
     * любом случае по этому параметру должно быть возможно определить куда девать 
     * результирующий текст.
     * 
     * @пример: "любаяСтрока"
     * @обязательный: да
     */
    token: string;
    
    /**
     * Идентификатор документа в Литере. Если указан, то будет продолжена 
     * работа над тем же самым документом, если нет, то будет создан новый документ. 
     * Пожалуйста, обратите внимание на то обстоятельство, что в данный момент в 
     * Литере5 с документом может работать только один пользователь. Поэтому 
     * несмотря на то, что в CMS с документом могут работать различные 
     * пользователи, при работе с одним и тем же документом в API имеет смысл 
     * передавать в `login` не идентификатор текущего пользователя CMS Партнёра, а 
     * идентификатор пользователя создавшего данный документ в Литере5 (того 
     * пользователя в результате проверки которого был выдан этот `document`). В 
     * противном случае API выдаст ошибку о недостатке прав пользователя на работу 
     * с документом.
     * 
     * @пример: "539557f78dfdedee48e136f8"
     * @обязательный: нет 
     */
    document: string;
    
    /**
     * Название документа (title, subject). Если не указано, то будет сформировано 
     * автоматически из текста.
     * 
     * @пример: "Название документа"
     * @обязательный: нет 
     */
    name: string;
    
    /**
     * Дополнительное поле. Заголовок документа для проверки. Дополнительные поля 
     * будут добавлены в специальную форму для дополнительной проверки.
     * 
     * @пример: "Заголовок документа"
     * @обязательный: нет 
     */
    title: string;
    
    /**
     * Дополнительное поле. Краткое описание страницы для проверки.
     * 
     * @пример: "Краткое содержание текста"
     * @обязательный: нет 
     */
    description: string;
    
    /**
     * Дополнительное поле. Ключевые слова страницы для проверки.
     * 
     * @пример: "ключевые слова"
     * @обязательный: нет 
     */
    keywords: string;
    
    /**
     * Список дополнительных произвольных полей для проверки. Каждый элемент 
     * списка – это объект с атрибутами: 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".
     * 
     * @пример: [{
     *            "name": "description", 
     *            "value": "<p>Дополнительное описание документа</p>"
     *          }]
     * @обязательный: нет 
     */
    custom: object[];
    
    /**
     * Собственно текст для проверки в формате 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 – когда нужно исключить содержимое элемента из 
     *   проверки и вообще не показывать его пользователю
     * 
     * @пример: "<h1>Загаловак</h1><p>текст с ашипками</p>"
     * @обязательный: нет 
     */
    html: string;
     
    /**
     * Электронная подпись запроса, формируется по алгоритму `md5(time + company 
     * + login + token + document + name + title + description + keywords + 
     * custom.map(name + value) + html + API_SECRET_KEY)`.
     * 
     * @пример: "5eb63bbbe01eeed093cb22bb8f5acdc3"
     * @обязательный: да
     */
    signature: string;
}

Ответ

interface CheckResponse {
    /**
     * Текущее время в формате unix timestamp (количество секунд с 1970 года)
     * 
     * @пример: "1410103972"
     * @обязательный: да
     */
    time: string;
    
    /**
     * Идентификатор документа в Литере созданный в результате запроса.
     * 
     * @пример: "539557f78dfdedee48e136f8"
     * @обязательный: да
     */
    document: string;
    
    /**
     * Одноразовая ссылка на Сайт редактор документа переданного в запросе, 
     * которую можно открывать в новом окне, или в IFRAME в CMS Партнёра. 
     * К полученному в этом параметре значению нужно будет добавить 
     * "https://litera5.ru", чтобы получить полную ссылку.
     * 
     * @пример: "/api/pub/iframe/52fb432f8dfd8b7b0d9a8ff2/"
     * @обязательный: да
     */
    url: string;
    
    /**
     * Электронная подпись запроса, формируется по алгоритму `md5(time + 
     * document + url + API_SECRET_KEY)`.
     * 
     * @пример: "5eb63bbbe01eeed093cb22bb8f5acdc3"
     * @обязательный: да
     */
    signature: string;
}