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

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

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

`customer`

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

`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 можно посмотреть в документации отправки заказа.

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

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

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

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

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

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

Поле modifiers

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

Поле modifiers

Получение привязанных модификаторов

Привязки

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

Поле customer

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

Поле delivery_address

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

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

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

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

delivery_method

delivery_address

customer

gender

payments

deliver_at

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

Ответ

Проверка возможности отправки заказа

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

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

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

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

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

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

delivery_method

delivery_address

stock_id

deliver_at

Поле `modifiers`

Поле `modifiers`

Поле `customer`

Поле `delivery_address`

`delivery_method`

`delivery_address`

`customer`

`gender`

`payments`

`deliver_at`

`delivery_method`

`delivery_address`

`stock_id`

`deliver_at`