• Справочник по API Облака

    • Общая информация об API Облака Эвотор

    API Облака Эвотор предоставляет доступ к данным пользователей платформы Эвотор. Используйте эти данные чтобы создавать товароучётные или аналитические сервисы, приложения для кафе и ресторанов, поддерживать различные системы лояльности и многое другое.

    С помощью методов API вы сможете:

    Раздел содержит общую информацию о работе API Облака Эвотор.

    Версия API, адрес и содержимое запросов

    Запросы к API Облака выполняются по адресу:

    https://api.evotor.ru/

    По умолчанию, все запросы выполняются ко второй версии API Облака. Несмотря на это, заголовки должны явно указывать версию API и тип содержимого запроса:

    Accept: application/vnd.evotor.v2+json
Content-Type: application/vnd.evotor.v2+json

    При выполнении массовых операций дополняйте заголовок Content-Type модификатором +bulk.

    Авторизация и аутентификация запросов в Облако

    Облако Эвотор аутентифицирует и авторизует запросы одним из следующих способов:

    Коды состояния

    В таблице приведены коды состояния, которые может вернуть Облако.

    Код Сообщение Описание
    200 OK Возвращается при успешном выполнении запроса.
    201 Created Возвращается при PUT-запросе на создание одного нового объекта (товара, модификации, группы товаров или группы модификаций).
    202 Accepted Возвращается при запросе на создание или изменение нескольких объектов (товаров, модификаций, групп товаров или групп модификаций). Ответ содержит идентификатор задачи, необходимый для проверки хода выполнения задачи.
    204 No Content Возвращается при успешном удалении ресурса. Тело ответа пустое.
    401 Unauthorized Возвращается при ошибке авторизации приложения.
    402 Not Installed Возвращается если приложение не установленно на всех смарт-терминалах, привязанных к данному магазину. Сообщение содержит идентификатор магазина, в котором возникла ошибка.
    403 Forbidden Нет доступа. Возвращается если у приложения нет разрешения на запрашиваемое действие или пользователь не установил приложение в Личном кабинете.
    404 Not Found Возвращается если запрашиваемый ресурс не найден.
    413 Payload Too Large Возвращается при превышении максимального объёма запроса. Максимальный объём запроса — 5 Мб.
    429 Rate Limit Exceeded Возвращается при превышении максимального количества запросов в текущем периоде.

    Ошибка 402

    Облако передаёт ошибку с кодом 402 если приложение не установленно на один или несколько смарт-терминалов, участвующих в обмене данными в рамках магазина.

    Тело ошибки выглядит следующим образом:

    [
   {
      "code":"not_installed",
      "message":"application is not paid/installed on all devices in store {store_id}",
      "violations":[
         {
            "reason":"app is not paid/installed on device",
            "subject":"{device_uuid}"
         }
      ]
   }
]

    Пагинация и ограничение данных в ответе

    Ответы на некоторые запросы содержат массив items, который может включать до 1000 элементов. Если количество элементов в ответе превышает данное ограничение, ответ будет содержать объект paging, в котором передаётся поле next_cursor, указывающее на следующую страницу с данными:

    {
  "items": [{}],
  "paging": {
    "next_cursor": "string"
  }
}

    Вы можете получить следующую страницу с данными если передадите значение поля next_cursor в query-параметре cursor:

    GET https://api.evotor.ru/stores/{store-id}/documents?cursor=string

    Следующие запросы возвращают массив items и поддерживают пагинацию:

    Ограничение количества запросов

    Облако Эвотор ограничивает количество запросов, которые может сделать сторонний сервис в течение определённого периода времени. Информация о максимальном и оставшемся количестве запросов, а также о времени, оставшемся до начала нового периода, содержится в заголовках ответов Облака.

    Заголовок Описание
    X-RateLimit-Limit

    Максимальное количество запросов, которые можно сделать за определённый период времени. Облако рассчитывает максимальное количество запросов в рамках пользователя Эвотор. Для некоторых ресурсов, количество запросов так же рассчитывается в рамках магазина.

    Например, если у одного пользователя несколько магазинов, максимальное количество запросов на работу с товарами будет рассчитываться отдельно для каждого магазина.
    X-RateLimit-Remaining Количество запросов, оставшихся в текущем периоде времени. Количество оставшихся запросов уменьшается с каждым запросом.
    X-RateLimit-Reset Время, в секундах, оставшееся до начала нового периода. Время определяется Облаком Эвотор индивидуально для каждого ресурса.

    Массовые операции

    Некоторые ресурсы API Облака поддерживают массовые операции с данными и позволяют создавать или изменять до 1000 элементов в рамках одного запроса.

    Заголовок Content-Type запроса на массовую операцию должен содержать модификатор +bulk:

    Content-Type: application/vnd.evotor.v2+bulk+json

    API Облака позволяет отслеживать состояние массовых операций.

    Фильтрация доступных данных

    Облако фильтрует данные ответа в соответствии параметрами доступа стороннего сервиса.

    Ряд параметров доступа вы можете указать на портале разработчиков, в то время как другие определяются в Личном кабинете пользователя Эвотор.

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