Начало работы
API Zenky.io предоставляет обширный набор методов для работы практически со всеми сущностями системы. Большинство операций, которые могут быть выполнены в панели управления магазином, можно реализовать с помощью API, в том числе наполнение каталога (создание, редактирование, удаление категорий, товаров, характеристик и т.д.).
Выполнение запросов
Базовый адрес для выполнения запросов к API - https://api.zenky.io/v2
. Формат возвращаемых данных - JSON.
HTTP-методы
Каждый метод API может поддерживать один или несколько из перечисленных HTTP-методов:
GET
для чтения информации;POST
для создания нового объекта или для выполнения команд (таких как отправка заказа);PUT
для изменения существующего объекта;DELETE
для удаления существующего объекта.
Авторизация
Практически все методы работают без API-токенов в режиме чтения информации (запросы методом GET
).
Если же вам необходимо создавать, редактировать или удалять какую-либо информацию, вы должны предоставлять
API-токен пользователя, имеющего доступ к указанному магазину.
Получение API-токена
Прежде чем вы сможете выполнять запросы к закрытым методам, необходимо авторизоваться в панели управления магазином, перейти в раздел API и создать новый персональный API-токен.
После того, как токен будет создан, сразу же сохраните его значение в надёжном месте - после закрытия окна токен больше не будет отображаться.
ПИН-код сотрудника
Некоторые методы API могут требовать ПИН-код сотрудника, выполняющего запрос. Для доступа к таким
методам необходимо передавать заголовок X-User-Pin
со значением ПИН-кода сотрудника.
Заголовки
Все запросы к API должны выполняться с заголовком Accept: application/json
. В некоторых случаях, если заголовок
Accept
не был передан или его значением не является строка application/json
, вы можете получить в ответ
HTML-код или перенаправление на внутренние страницы панели управления магазином.
ID магазина
Кроме того, все методы, которые так или иначе связаны с магазином, требуют передачи обязательного
HTTP-заголовка X-Store-Id
, значением которого должен быть указан идентификатор магазина, с которым в данный
момент выполняется работа.
Отправка API-токена осуществляется с помощью заголовка Authorization: Bearer TOKEN
.
Ответы API
Любой успешный ответ обязательно содержит в себе корневое поле data
, в котором, в зависимости от запроса,
располагается тело ответа.
Если был выполнен запрос на получение списка объектов, то в поле data
будет находиться массив объектов.
Если же был выполнен запрос на получение одного объекта, то в поля data
будет находиться объект.
Кроме того, на одном уровне с полем data
может присутствовать поле meta
- в основном оно используется для
передачи информации о количестве страниц списка объектов.
Включения ответов
Кроме основной информации об объекте методы могут отдавать расширенную информацию о вложенных сущностях
(т.н. включения ответов или includes
). У каждого метода, который поддерживает такие включения, имеется свой
список возможных включений, которые необходимо передавать с помощью параметра with
. Если требуется вернуть
несколько включений, их необходимо разделять запятыми.
Мета-данные
Пагинация
В ответах всех методов API, которым может быть передан порядковый номер страницы, присутствует мета-поле
pagination
, из которого можно получить информацию об общем количестве записей и страниц.
{
"meta": {
"pagination": {
"total": 240,
"count": 20,
"per_page": 20,
"current_page": 2,
"total_pages": 12,
"links": {
"previous": "https://api.zenky.io/v2/products?page=1",
"next": "https://api.zenky.io/v2/products?page=3"
}
}
}
}
Устаревшие поля
В течение жизненного цикла API мы можем отмечать те или иные поля в различных ответах как устаревшие. Чаще всего это происходит из-за выноса функциональности поля в отдельные методы API, переименование поля или в том случае, если поле дублирует существующую функциональность.
Устаревшие поля всегда будут доступны в текущей версии API, но будут удалены в следующей. Если вы заметите, что какое-либо поле, которое вы используете, отмечено устаревшим, постарайтесь перейти к использованию нового поля как можно быстрее.
{
"meta": {
"deprecations": {
"body": {
"message": "The \"body\" field will be removed soon. Use \"description\" field instead.",
"deprecated": "body",
"suggested": "description"
}
}
}
}
Обработка ошибок
Запросы, выполнение которых завершилось с ошибкой, содержат в себе поле error
, в котором дано подробное
описание произошедшей ошибки. В случае, если вы не можете исправить ошибку самостоятельно или не знаете
что именно пошло не так, всегда предоставляйте полное тело ответа при обращении в техподдержку.
Подробная информация об ошибках API указана здесь.
Кроме того, такие ответы возвращаются с кодом состояния 4XX/5XX
(см. ниже).
Коды состояния
API использует различные коды состояния HTTP для передачи тех или иных ответов.
- Успешные запросы на отображение информации возвращаются с кодом
200 OK
; - Успешные запросы на создание новой информации возвращаются с кодом
201 Created
; - Успешные запросы на редактирование информации возвращаются с кодом
200 OK
; - Успешные запросы на удаление информации возвращаются с кодом
204 No Content
; - Ответы на запросы, не прошедшие валидацию данных, возвращаются с кодом
422 Unprocessable Entity
; - Ответы на запросы после превышения лимита возвращаются с кодом
429 Too Many Requests
; - Ошибочные запросы возвращаются с кодами
401 Unauthorized
,403 Forbidden
или404 Not Found
; - Ответы на запросы, во время выполнения которых произошла ошибка на стороне сервера, возвращаются с кодом
500 Internal Server Error
.