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

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

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

Аутентификация покупателей

В зависимости от настройки магазина в определённый момент работы с заказами покупателю может потребоваться войти в свой аккаунт или подтвердить заказ кодом из SMS.

В случае, если магазин требует аутентификацию покупателя перед отправкой заказа, то отправка заказа без API-токена будет заблокирована (токен заказа в этом случае не является способом аутентификации покупателя).

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

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

Определить какой способ аутентификации используется можно с помощью значения настройки магазина orders.authentication_method.id.

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

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

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

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

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

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

У этого запроса нет обязательных полей. Все данные можно будет присвоить заказу позднее.

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

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

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

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

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

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

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

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

Привязки

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

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

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

Поле `customer`

Поле "Покупатель" должно иметь следующий формат:

В случае, если оформление заказа происходит на существующего покупателя, достаточно передать его ID в поле customer.id. Все остальные поля при этом будут заполнены автоматически.

В ситуациях, когда ID покупателя неизвестен, необходимо передавать номер телефона. Если покупатель с таким номером существует, заказ будет оформлен на него. В ином случае он будет создан автоматически.

При передаче номера телефона так же необходимо заполнять поле customer.phone_country. Значением этого поля должен быть код страны, где зарегистрирован номер телефона (в формате ISO 3166-1 alpha-2).

Привязка адреса доставки

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

Поле `delivery_address`

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

В случае, если пользователь выбрал в качестве адреса доставки ранее сохранённый адрес, достаточно указать поле delivery_address.id — все остальные данные будут взяты из сохранённого адреса.

Если же вводимый адрес указывается впервые, поле delivery_address.address является обязательным. Для присвоения имени новому адресу используйте поле delivery_address.name.

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

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

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

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

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

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

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

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

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

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

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

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

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

`delivery_method`

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

`delivery_address`

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

Если же вводимый адрес указывается впервые, поле delivery_address.street_fias_id является обязательным. Для присвоения имени новому адресу используйте поле delivery_address.name.

`customer`

Поле "Покупатель" должно иметь следующий формат:

`gender`

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

`payment`

Поле "Платёж" должно иметь следующий формат:

Поле payment.method должно иметь одно из указанных значений:

Поле amount заполняется в том случае, если производится частичная оплата заказа. После отправки заказа можно будет создать дополнительные платёжные транзакции, покрывающие оставшуюся сумму.

Поле bill указывается для расчёта сдачи покупателю. Это поле учитывается только в том случае, если значением поля payment.method является cash (оплата наличными).

`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": "Доставка"
            },
            "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://api.zenky.io/v2/orders/{orderId}/confirm, передав следующие параметры:

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

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

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

Обновление заказов

Изменение статуса

Для смены статуса заказа необходимо отправить POST-запрос на https://api.zenky.io/v2/orders/{orderId}/status, передав в запросе поле order_status_id, в котором хранится ID нового статуса заказа.

Изменение заметок

Для изменения заметок к заказу необходимо отправить POST-запрос на https://api.zenky.io/v2/orders/{orderId}/notes, передав в поле notes текст заметок (можно передавать пустое значение или NULL).

Изменение способа доставки

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

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

`delivery_method`

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

`delivery_address`

Структура поля delivery_address аналогична структуре, которая используется при отправке заказа.

`stock_id`

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

`deliver_at`

Описание поля deliver_at можно посмотреть в документации отправки заказа/

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

Аутентификация покупателей

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

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

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

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

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

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

Привязки

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

Поле customer

Привязка адреса доставки

Поле delivery_address

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

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

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

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

delivery_method

delivery_address

customer

gender

payment

deliver_at

Ответ

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

Обновление заказов

Изменение статуса

Изменение заметок

Изменение способа доставки

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

delivery_method

delivery_address

stock_id

deliver_at

Поле `customer`

Поле `delivery_address`

`delivery_method`

`delivery_address`

`customer`

`gender`

`payment`

`deliver_at`

`delivery_method`

`delivery_address`

`stock_id`

`deliver_at`