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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

delivery_method

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

delivery_address

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

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

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

customer

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

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

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

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

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 нового статуса заказа.