Запросить демо
Запросить демо
Документерра: руководство пользователя

API Документерры

Каждый портал Документерры оснащен интерфейсом REST API, позволяющим автоматизировать задачи и интегрировать документооборот в существующие бизнес-процессы.


Базовый URL-адрес REST API

Все URL-адреса в справочной документации используют следующий базовый URL-адрес:

https://{your-portal-URL}/api/v1/

По умолчанию URL-адрес вашего портала выглядит как hedronlabs.documenterra.net, где hedronlabs — имя вашего портала. Если вы используете собственный домен, например, docs.hedronlabs.org, он используется вместо адреса по умолчанию.

Все запросы к REST API Документерры обслуживаются по протоколу HTTPS.   Незашифрованный HTTP не поддерживается. Кроме того, система Документерра использует протокол TLS 1.2; любая более ранняя версия не поддерживается.

Авторизация

Большинство запросов к REST API Документерры используют базовую авторизацию, хотя некоторые запросы можно делать анонимно.   Проще говоря, вы будете использовать логин своей учетной записи в системе Документерра в  качестве имени пользователя, а ключ API — в  качестве пароля для базовой авторизации HTTP. Поэтому обязательно используйте флаг -u (--user):

Bash (Unix Shell)
    --basic ^
--user "login:api-key"

При авторизации вам необходимо указать свой логин и ключ  API, а не пароль.

Вы можете взять свой логин и сгенерировать ключ API в своем профиле. Инструкции смотри в разделе «Получение ключа  API». Обратите внимание, что только Авторы могут генерировать ключи API.

Коды статуса ответа

Все запросы API будут возвращать определенные коды — это может быть код успеха или код ошибки. Ниже приведен список всех кодов состояния, которые может возвращать API Документерры.

Коды успеха

200 OK (хорошо) Запрос выполнен успешно.   Значение «успеха» зависит от метода HTTP.
201 Created (создано)
Запрос выполнен успешно, и в результате был создан новый ресурс.
204 No Content (нет содержимого)
Запрос выполнен успешно.

Коды ошибок

API должен выдать сообщение с кодом ошибки, который подскажет, что пошло не так. Кроме того, вы можете ознакомиться с инструкциями по устранению ошибок в разделе Устранение неполадок API. Если это не помогло или система выдает непонятное сообщение об ошибке, обратитесь по адресу support@documenterra.ru и  предоставьте подробную информацию о ситуации. 

400 Bad Request (некорректный запрос)
Данные в вашем запросе неверны, и сервер не может или отказывается их обрабатывать, например, неправильный синтаксис запроса, неправильный фрейм сообщения запроса и т.д.
401 Unauthorized (не авторизован)
Логин или ключ API недействительны, информация для входа не указана, ваша учетная запись отключена или HTTP-заголовок авторизации вашего запроса поврежден — подробности смотри в тексте ответа. Убедитесь, что вместо ключа API не указан пароль.
403 Forbidden (запрещено)
У вас нет разрешения работать с API или выполнять запрошенное действие. Подробности смотри в ответе на запрос.
404 Not Found (не найдено)
Ресурс, который вы ищете, не найден. Это может произойти, если указанный вами URL-адрес недействителен или ресурс, на который вы ссылаетесь, не существует.
409 Conflict (конфликт)
Действие, которое вы попытались выполнить, привело к конфликту данных, что обычно означает дублирование идентификаторов (например, создание пользователя с уже существующим именем). Подробности смотри в ответе на запрос.
500 Internal Server Error (внутренняя ошибка сервера)
При обработке запроса что-то пошло не так. Подробности смотри в ответе на запрос.
501 Not Implemented (не реализовано)
Вы попытались выполнить какое-либо действие, которое в настоящее время не поддерживается API. Если вы получили данный код ответа, свяжитесь с нами и сообщите, что вы пытаетесь сделать.

Тело сообщения об ошибке

В случае ошибок тело ответа HTTP всегда содержит объект JSON со следующими полями:

Поле Описание
Message (сообщение) Cообщение об исключении с подробностями.
ExceptionType (тип исключения) Тип исключения.
ExceptionDetail (Сведения об исключении) Предназначено для использования в будущем. 
StackTrace (стек-трейс) Предназначено для использования в будущем. 

Примечание к ответам

Все ответы имеют несколько общих черт.

  • Все методы POST выдают местоположение соответствующего ресурса (страницы, элемента Дерева страниц и т.д.) в заголовке Location (местоположение).
  • Все методы PATCH выдают полный обновленный ресурс, как если бы вы впоследствии запустили запрос GET.

Примечание к справочнику по API

Ниже приведена информация, которую вам следует знать, прежде чем обращаться к справочнику API Документерры.

  • Все примеры из справочника включают только специальные флаги/параметры для cURL и не включают общие флаги, определяющие файл CA bundle и данные аутентификации. Убедитесь, что вы включили их во все запросы:
    Bash (Unix Shell)
        --user "login:api-key" ^
    --cacert comodo.ca-bundle ^
  • В справочнике приведены примеры запросов API с использованием утилиты cURL.   Важно отметить, что в примерах используется параметр командной строки --cacert. В нем указано имя файла CA Bundle — файла с корневыми и промежуточными сертификатами центра сертификации, выдавшего SSL-сертификат целевой конечной точки. cURL использует данный файл для проверки SSL-сертификата конечной точки. Данный тип файла обычно доступен на веб-сайте сертификационного центра, и его можно скачать.
    Если вы используете доменное имя по умолчанию {portal-name}.documenterra.net, вы можете использовать этот файл CA Bundle. Если вы используете собственное доменное имя с собственным сертификатом SSL, запросите файл CA Bundle в своем центре сертификации.
  • По умолчанию параметры считаются обязательными. Все необязательные параметры помечены как [optional] (опционально) или [deprecated] (исключено).