Начало работы

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-код или перенаправление на внутренние страницы панели управления магазином.

Кроме того, все методы, которые так или иначе связаны с магазином, требуют передачи обязательного 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.