Работа с заказами
- Аутентификация покупателей
- Авторизация действий
- Создание заказа
- Управление товарами
- Привязки
- Обновление заказа
- Отправка заказа
- Обновление заказов
Этот раздел содержит информацию о работе с заказами в API Zenky.io.
Аутентификация покупателей
В зависимости от настройки магазина в определённый момент работы с заказами покупателю может потребоваться войти в свой аккаунт или подтвердить заказ кодом из SMS.
В случае, если магазин требует аутентификацию покупателя перед отправкой заказа, то отправка заказа без API-токена будет заблокирована (токен заказа в этом случае не является способом аутентификации покупателя).
В случае, если магазин требует подтверждения заказа, сразу же после отправки заказа покупателю будет выслан код в SMS, которым нужно подтвердить заказ.
Пока заказ не будет подтверждён, он не появится в системе заказов и по нему не будут разосланы вебхуки.
Определить какой способ аутентификации используется можно с помощью значения
настройки магазина orders.authentication_method.id
.
Авторизация действий
Операция создания заказа доступна для выполнения всем — как аутентифицированным пользователям, так и гостям. При создании заказа из-под аутентифицированного пользователя, он будет связан с заказом автоматически и никаких дополнительных действий не требуется (кроме передачи токена пользователя во всех запросах).
Если же заказ был создан гостем, то все методы требуют передачи параметра token
, значение которого
можно взять из ответа создания заказа.
Прикрепив покупателя к заказу вы можете передавать только API токен — этого будет достаточно для прохождения авторизации.
Создание заказа
Для того, чтобы создать заказ, вам необходимо выполнить POST
-запрос на
https://api.zenky.io/v2/orders
, передав следующие параметры:
У этого запроса нет обязательных полей (кроме phone_country
— оно обязательно к заполнению, если передаётся phone
).
Все данные можно будет присвоить заказу позднее.
Управление товарами заказа
Добавление товаров
Для добавления товаров в заказ необходимо выполнить POST
-запрос на URL
https://api.zenky.io/v2/orders/{orderId}/products
(где {orderId}
- ID заказа), передав следующие параметры:
Поле modifiers
В поле modifiers
можно перечислить список одиночных и групповых модификаторов,
которые нужно прикрепить к варианту товара. Каждым элементов этого массива должен быть объект со следующей структурой:
Если товар с подобной комбинацией (ID модификатора + количество + ID группы модификаторов; порядок неважен) уже существует в списке товаров заказа, его количество будет увеличено. Иначе будет создана новая позиция заказа.
Удаление товаров
Для удаления товаров из заказа необходимо выполнить POST
-запрос на URL
https://api.zenky.io/v2/orders/{orderId}/products/remove
(где {orderId}
- ID заказа), передав следующие
параметры:
Поле modifiers
В поле modifiers
можно перечислить список одиночных и групповых модификаторов,
которые были прикреплены к варианту товара. Каждым элементов этого массива должен быть объект со следующей структурой:
Если товар с подобной комбинацией (ID модификатора + количество + ID группы модификаторов; порядок неважен) уже существует в списке товаров заказа, его количество будет уменьшено. Иначе будет возвращена ошибка 404.
Получение привязанных модификаторов
Для получения товаров вместе с привязанными к ним модификаторами можно воспользоваться одним из следующих включений:
variants.modifiers
для базовой информации о привязанных модификаторах;variants.modifiers.modifier,variants.modifiers.modifiers_group
для получения в том числе самих модификаторов и групп;variants.modifiers.modifier.external_identifier,variants.modifiers.modifiers_group.external_identifier
для получения модификаторов, групп и их идентификаторов из внешних систем учёта (если имеются).
Привязки
Наряду с товарами у заказов могут быть дополнительные связанные ресурсы.
Привязка покупателя
Для привязки покупателя к заказу необходимо выполнить 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
, передав следующие параметры:
Кроме того, склад можно указать при отправке заказа.
Обновление заказа
Метод обновления заказа используется для сохранения промежуточных данных для последующей отправки заказа.
Для обновления заказа необходимо выполнить PUT
-запрос на URL https://api.zenky.io/v2/orders/{orderId}
,
передав следующие параметры:
Описание полей
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
) должно иметь одно из следующих значений:
payments
Каждый элемент поля payments
должен иметь следующий формат:
Поле method
должно иметь одно из указанных значений:
Поле amount
заполняется в том случае, если производится частичная оплата заказа.
После отправки заказа можно будет создать дополнительные платёжные транзакции,
покрывающие оставшуюся сумму.
Поле bill
указывается для расчёта сдачи покупателю. Это поле учитывается только в том случае,
если значением поля method
является cash
(оплата наличными).
deliver_at
Если покупатель выбрал конкретное время доставки, это значение можно передать в поле deliver_at
.
Дата должна быть отправлена в формате YYYY-MM-DD HH:MM
(например, 2019-09-20 20:00
) и в часовом
поясе города, в котором оформляется заказ.
После отправки заказа вы сможете прочитать время доставки из поля deliver_at
. Обратите внимание,
что значение этого поля может отличаться от отправленного пользователем, т.к. перед сохранением
в базу дата доставки конвертируется из локального времени города в UTC. Используйте поле datetime_utc
для перевода его значения в локальное время города (вручную).
Отправка заказа
Метод отправки заказа используется для уведомления сотрудников магазина, что покупатель завершил добавление товаров и указал все необходимые данные.
Отправка заказа может проходить в 2 этапа (зависит от настроек магазина):
- Отправка заказа и передача всех необходимых данных;
- Подтверждение номера телефона кодом из SMS (опционально).
Для отправки заказа необходимо выполнить POST
-запрос на URL
https://api.zenky.io/v2/orders/{orderId}/submit
, передав точно такие же параметры, как и в методе
обновления заказа.
Ответ
После успешной отправки запроса вы получите следующий ответ:
{
"data":{
"result":{
"phone_confirmation_required":true,
"confirmation_code_sent":true,
"user_signed_up":false
},
"order": {
"id": "8ffe2a55-1af7-47d4-9d2c-edd40b2b06b5",
"order_status_id": "8ffdea87-775f-47e9-89f0-bbb974dae43f",
"number": "0303-1",
"token": "secret",
"source": "",
"api_client": "web",
"status": {
"id": "submitted",
"name": "Новый"
},
"confirmation_status": {
"id": "confirmed",
"name": "Подтверждён"
},
"delivery_method": {
"id": "delivery",
"name": "Курьер"
},
"payment_method": {
"id": "credit-card",
"name": "Банковская карта"
},
"total_price": {
"value": 10399000,
"short": "103 990",
"trimmed": "103990",
"full": "103 990 руб.",
"currency": {
"name": "Российский рубль",
"thousands_separator": " ",
"decimals_separator": ".",
"prefix": "",
"suffix": " руб.",
"symbol": "₽"
}
},
"expected_payment_amount": {
"value": 10399000,
"short": "103 990",
"trimmed": "103990",
"full": "103 990 руб.",
"currency": {
"name": "Российский рубль",
"thousands_separator": " ",
"decimals_separator": ".",
"prefix": "",
"suffix": " руб.",
"symbol": "₽"
}
},
"amount_paid": {
"value": 0,
"short": "0",
"trimmed": "0",
"full": "0 руб.",
"currency": {
"name": "Российский рубль",
"thousands_separator": " ",
"decimals_separator": ".",
"prefix": "",
"suffix": " руб.",
"symbol": "₽"
}
},
"bonuses_amount_paid": {
"value": 0,
"short": "0",
"trimmed": "0",
"full": "0 руб.",
"currency": {
"name": "Российский рубль",
"thousands_separator": " ",
"decimals_separator": ".",
"prefix": "",
"suffix": " руб.",
"symbol": "₽"
}
},
"bonuses_transaction_id": "",
"bonuses_transaction_confirmed": false,
"notes": "Персон: 1",
"created_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 06:45:47",
"datetime": "2020-03-03 14:45:47",
"datetime_at": "03.03.2020 в 14:45",
"diff": "1 час назад"
},
"updated_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 06:47:33",
"datetime": "2020-03-03 14:47:33",
"datetime_at": "03.03.2020 в 14:47",
"diff": "1 час назад"
},
"submitted_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 06:47:32",
"datetime": "2020-03-03 14:47:32",
"datetime_at": "03.03.2020 в 14:47",
"diff": "1 час назад"
},
"deliver_at": null,
"archived_at": null,
"current_status": {
"id": "8ffe2af7-0ca2-403d-a3ad-08c467065f15",
"order_status_id": "8ffdea87-775f-47e9-89f0-bbb974dae43f",
"created_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 06:47:32",
"datetime": "2020-03-03 14:47:32",
"datetime_at": "03.03.2020 в 14:47",
"diff": "1 час назад"
},
"status": {
"id": "8ffdea87-775f-47e9-89f0-bbb974dae43f",
"name": "Новый",
"kind": {
"id": "submitted",
"name": "Новый"
},
"background_color": "#d78ca4",
"sorting": 1,
"visible": true,
"created_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 03:47:22",
"datetime": "2020-03-03 11:47:22",
"datetime_at": "03.03.2020 в 11:47",
"diff": "4 часа назад"
},
"updated_at": {
"timezone": "Asia\/Irkutsk",
"datetime_utc": "2020-03-03 03:47:22",
"datetime": "2020-03-03 11:47:22",
"datetime_at": "03.03.2020 в 11:47",
"diff": "4 часа назад"
}
}
}
}
}
}
Поле data.result.phone_confirmation_required
указывает на то, требуется ли выполнять
подтверждение заказа. Поле data.result.user_signed_up
указывает на то, был ли пользователь
только что зарегистрирован или уже существовал в базе.
Проверка возможности отправки заказа
Магазин может отключить принятие как всех заказов, так и тех заказов, которые отправляются в нерабочее время (проверка выполняется на уровне города).
Для того, чтобы проверить, можно ли в текущий момент отправить заказ, нужно отправить
GET
-запрос на https://api.zenky.io/v2/orders/{orderId}/submit/status
.
В ответе будет содержаться следующая структура (поле data
опущено):
Подтверждение заказа
При отправке заказа в магазины, у которых включено подтверждение заказов по 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
можно посмотреть в документации
отправки заказа.