Работа с заказами

Авторизация действий
Создание заказа
- Создание заказа с товарами
Управление товарами
- Добавление товаров
- Удаление товаров
Привязки
Отправка заказа
- Описание полей
- Подтверждение

Этот раздел содержит информацию о работе с заказами в API Zenky.io.

Авторизация действий

Операция создания заказа доступна для выполнения всем — как аутентифицированным пользователям, так и гостям. При создании заказа из-под аутентифицированного пользователя, он будет связан с заказом автоматически и никаких дополнительных действий не требуется (кроме передачи токена пользователя во всех запросах).

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

Прикрепив покупателя к заказу вы можете передавать только API токен — этого будет достаточно для прохождения авторизации.

Создание заказа

Для того, чтобы создать заказ, вам необходимо выполнить POST-запрос на https://my.zenky.io/api/orders, передав следующие параметры:

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

Создание заказа с товарами

Для того, чтобы создать заказ с товарами, их необходимо передать в массиве variants. Каждый элемент этого массива должен являться объектом со следующей структурой:

Необязательно создавать заказ с товарами — для их добавления есть отдельный метод API.

Управление товарами заказа

Добавление товаров

Для добавления товаров в заказ необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/products (где {orderId} - ID заказа), передав следующие параметры:

Удаление товаров

Для удаления товаров из заказа необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/products/remove (где {orderId} - ID заказа), передав следующие параметры:

Привязки

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

Привязка покупателя

Для привязки покупателя к заказу необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/customer, передав следующие параметры:

В случае, если указанный номер телефона не существует, покупатель будет создан автоматически.

Привязка города

Изначально город привязывается к заказу на этапе создания заказа. Однако, вам может потребоваться сменить город. Для этого необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/city, передав следующие параметры:

Привязка склада

Склад привязывается к заказу для указания точки, откуда будет выполняться самовывоз.

Кроме того, если у товара из заказа имеется переопределённая для указанного склада цена, в расчетах будет использоваться именно она (если не указан иной склад в самом товаре).

Для привязки склада к заказу необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/stock, передав следующие параметры:

Кроме того, склад можно указать при отправке заказа.

Отправка заказа

Метод отправки заказа используется для уведомления сотрудников магазина, что покупатель завершил добавление товаров и указал все необходимые данные.

Отправка заказа может проходить в 2 этапа (зависит от настроек магазина):

Отправка заказа и передача всех необходимых данных;
Подтверждение номера телефона кодом из SMS (опционально).

Для отправки заказа необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/submit, передав следующие параметры:

Описание полей

`delivery_method`

Поле "Способ доставки" (delivery_method) должно иметь одно из следующих значений:

`payment_method`

Поле "Способ оплаты" (payment_method) должно иметь одно из следующих значений:

`address`

Поле "Адрес доставки" (address) должно иметь следующий формат:

Объект original_address должен иметь поле fias_id, значением которого должен быть идентификатор ФИАС уровня улицы.

`gender`

Поле "Пол покупателя" (gender) должно иметь одно из следующих значений:

`deliver_at`

Если покупатель выбрал конкретное время доставки, это значение можно передать в поле deliver_at. Дата должна быть отправлена в формате YYYY-MM-DD HH:MM (например, 2019-09-20 20:00) и в часовом поясе города, в котором оформляется заказ.

После отправки заказа вы сможете прочитать время доставки из поля deliver_at. Обратите внимание, что значение этого поля может отличаться от отправленного пользователем, т.к. перед сохранением в базу дата доставки конвертируется из локального времени города в UTC. Используйте поле datetime_utc для перевода его значения в локальное время города (вручную).

Ответ

При успешной отправке запроса вы получите следующий ответ:

{
    "data": {
        "result": {
            "phone_confirmation_required": true,
            "confirmation_code_sent": true,
            "user_signed_up": false
        },
        "order": {
            "id": "8aac57c4-58ef-4260-9002-191e3e445078",
            "number": "20180426-QGM9-WKVV",
            "confirmation_status": {
                "id": "unconfirmed",
                "name": "Заказ не подтверждён"
            },
            "delivery_method": {
                "id": "delivery",
                "name": "Доставка"
            },
            "payment_method": {
                "id": "cash",
                "name": "Наличные"
            },
            "total_price": {
                "value": 22500000,
                "short": "225 000",
                "full": "225 000 руб.",
                "currency": {
                    "name": "Российский рубль",
                    "thousands_separator": " ",
                    "decimals_separator": ".",
                    "prefix": "",
                    "suffix": " руб.",
                    "symbol": "₽"
                }
            },
            "created_at": {
                "timezone": "Asia/Irkutsk",
                "datetime_utc": "2019-04-19 04:00:00",
                "datetime": "2019-04-19 12:00:00",
                "datetime_at": "19.04.2019 в 12:00",
                "diff": "2 часа назад"
            },
            "updated_at": {
                "timezone": "Asia/Irkutsk",
                "datetime_utc": "2019-04-19 04:00:00",
                "datetime": "2019-04-19 12:00:00",
                "datetime_at": "19.04.2019 в 12:00",
                "diff": "2 часа назад"
            }
        }
    }
}

Поле data.result.phone_confirmation_required указывает на то, требуется ли выполнять подтверждение заказа. Поле data.result.user_signed_up указывает на то, был ли пользователь только что зарегистрирован или уже существовал в базе.

Подтверждение заказа

При отправке заказа в магазины, у которых включено подтверждение заказов по SMS, заказ не будет до конца оформлен, пока не поступит его подтверждение.

Необходимость подтверждения определяется полем data.result.confirmation_required. SMS покупателю отсылается автоматически, никакие действия для отправки не требуются.

Для подтверждения заказа необходимо выполнить POST-запрос на URL https://my.zenky.io/api/orders/{orderId}/confirm, передав следующие параметры:

В случае, если токен подтверждения не был найден (истек срок кода), будет возвращён ответ со статусом 404. Запрос с некорректным кодом завершится с ответом 403.

При успешном подтверждении заказа в ответ вернётся ответ со статусом 200:

{
  "data": {
    "success": true
  }
}