Введение в API

Всем клиентам коробочной версии Эсборд начиная с версии 2024.5 доступен публичный API, с помощью которого можно настроить необходимые интеграции Эсборд с другими сервисами.

Публичный API Эсборд представлен набором методов. Вызов методов выполняется посредством HTTP-запроса на адрес метода с указанием параметров. Параметры для GET-запросов указываются в адресе запроса (query params), для POST-запросов - в теле запроса (body params).

Адрес любого метода начинается с https://<ваш_домен>/api/public/v1.

Каждый ответ от API Эсборд представляет собой JSON, который содержит следующие поля:

Название	Описание	Обязательный
status	Статус ответа. 0 - успех, 1 - ошибка.	Да
data	Объект, содержащий результат запроса или подробности об ошибке.	Нет
error	Сообщение об ошибке.	Нет

Все методы защищены секретным ключом, который необходимо передать в заголовке Public-Api-Key (header) при запросе. Ключ API можно получить в личном кабинете администратора на странице "Интеграции". При использовании невалидного ключа сервер ответит ошибкой.

Пример запроса с помощью cURL

curl --request GET \
  --url 'https://<ваш_домен>/api/public/v1/boards/getDrawings?boardId=<ИД_доски>&withFrameId=1' \
  --header 'Public-Api-Key: <ваш_ключ_API>'

Пример ответа 403 - Invalid token

Передан невалидный ключ API в заголовке Public-Api-Key.

{
  "status": 1,
  "error": "Invalid token"
}

Пример ответа 403 - Token is required

Не передан ключ API в заголовке Public-Api-Key.

{
  "status": 1,
  "error": "Token is required"
}

Поскольку некоторые параметры методов являются обязательными, при отсутствии их в запросе сервер ответит соответствующей ошибкой.

Пример ответа 400 - Validation error

Запрос не прошёл валидацию.

{
  "status": 1,
  "error": "Validation error",
  "data": [
    {
      "isNotEmpty": "boardId should not be empty",
      "isUuid": "boardId must be a UUID"
    }
  ]
}