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.
null. Не передавайте в запросе пустые необязательные поля.Облако Эвотор аутентифицирует и авторизует запросы одним из следующих способов:
С помощью Bearer-токена, передаваемого в заголовке Authorization.
Подробную информацию о получении токена вы найдёте в разделе “Авторизация запросов к Облаку Эвотор”
С помощью OAuth авторизации.
В таблице приведены коды состояния, которые может вернуть Облако.
| Код | Сообщение | Описание |
|---|---|---|
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 если приложение не установленно на один или несколько смарт-терминалов, участвующих в обмене данными в рамках магазина.
Тело ошибки выглядит следующим образом:
[
{
"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
paging будет пустым.Следующие запросы возвращают массив items и поддерживают пагинацию:
Облако Эвотор ограничивает количество запросов, которые может сделать сторонний сервис в течение определённого периода времени. Информация о максимальном и оставшемся количестве запросов, а также о времени, оставшемся до начала нового периода, содержится в заголовках ответов Облака.
| Заголовок | Описание |
|---|---|
X-RateLimit-Limit |
Максимальное количество запросов, которые можно сделать за определённый период времени. Облако рассчитывает максимальное количество запросов в рамках пользователя Эвотор. Для некоторых ресурсов, количество запросов так же рассчитывается в рамках магазина. Например, если у одного пользователя несколько магазинов, максимальное количество запросов на работу с товарами будет рассчитываться отдельно для каждого магазина. |
X-RateLimit-Remaining |
Количество запросов, оставшихся в текущем периоде времени. Количество оставшихся запросов уменьшается с каждым запросом. |
X-RateLimit-Reset |
Время, в секундах, оставшееся до начала нового периода. Время определяется Облаком Эвотор индивидуально для каждого ресурса. |
Некоторые ресурсы API Облака поддерживают массовые операции с данными и позволяют создавать или изменять до 1000 элементов в рамках одного запроса.
Заголовок Content-Type запроса на массовую операцию должен содержать модификатор +bulk:
Content-Type: application/vnd.evotor.v2+bulk+json
API Облака позволяет отслеживать состояние массовых операций.
Облако фильтрует данные ответа в соответствии параметрами доступа стороннего сервиса.
Ряд параметров доступа вы можете указать на портале разработчиков, в то время как другие определяются в Личном кабинете пользователя Эвотор.
Например, при запросе документов продажи из определенного магазина за определённое время, ответ будет содержать данные только для тех смарт-терминалов, на которые в момент выполнения запроса установлено приложение стороннего сервиса.