principles

Общие положения

Транспортный протокол

API Литеры выполнено в виде веб-приложения работающего по протоколу HTTP(s). Все служебные запросы (не требующие взаимодействия с пользователем) выполняются методом POST, и одна функция (GET iframe - вызов интерфейса Литеры с выполненной проверкой) использует HTTP метод GET. URL запросов к API Литеры имеют вид ${base-url}/api/pub/${method}/, где base-url - это базовый URL, который зависит от того используется ли облачный сервер Литеры (тогда этот базовый URL будет https://litera5.ru), или же это автономный сервер Литеры установленный где-то в локальной сети партнёра (в этом случае вы лучше нас знаете этот адрес). А method - это название метода API, например, setup или check.

Формат данных обмена

Все запросы ожидаются в кодировке UTF-8 с телом запроса в виде объекта JSON (Content-type: application/json). Все значения параметров запроса (полей объекта JSON) интерпретируются как строки, если это не оговорено отдельно.

Обработка ответа

В случае успешного выполнения запроса ответное сообщение будет содержать HTTP код 200 и JSON объект в качестве текста сообщения для запросов методом POST и привычный html/js/css в случае запросов GET iframe.

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

Авторизация (подпись запросов/ответов)

Для авторизации партнёра используется электронная подпись как запросов, так и ответов. Все запросы к серверу API Литеры имеют вид:

{
    /**
     * Время запроса в формате unix timestamp 
     * (количество секунд с начала 1970 года).
     */
    time: string
    
    /**
     * Идентификатор партнёра, указанный в договоре
     * и выданный при регистрации на сервере Литеры.
     */
    company: string
    
    ...
    
    /**
     * Электронная подпись запроса, формируется по алгоритму 
     * =md5(time + company + ... + API_SECRET_KEY)=,
     * где =API_SECRET_KEY= - это секретный ключ партнёра выданный 
     * при подключении API.
     */
    signature: string
}

Ответы сервера Литеры отличаются от запросов отсутствием поля company.