Подключение и настройка Iiko Transport
Рассказываем, как подключить Iiko Transport (CloudAPI) к вашему магазину Zenky.
Переход с Iiko Biz на Iiko Transport
Если вы переходите с Iiko Biz на Iiko Transport, вам может потребоваться дополнительная настройка на стороне Iiko. Воспользуйтесь этой статьёй из справочного центра Iiko, чтобы подготовиться к переходу с Biz на Transport – https://ru.iiko.help/articles/#!api-documentations/perevod-klienta-s-bizapi-na-cloud-api
Вам может потребоваться помощь ваших специалистов по Iiko.
Подключение интеграции
Для подключения интеграции с Iiko Transport перейдите в раздел "Интеграции" в панели управления Zenky. На этой странице в левом меню выберите раздел «PoS-системы», а затем нажмите на карточку интеграции.
На новой странице вы увидите информацию о подключаемой интеграции. Пожалуйста, прочитайте описание полностью, потому что оно может содержать важную для вас информацию (особенно, если вы переходите с API Iiko Biz).
Так же вы можете просмотреть какие разрешения API-токена Zenky требуются интеграции, а так же какие вебхуки будут отправляться в интеграцию.
После ознакомления нажмите на кнопку «Подключить интеграцию» в правом боковом меню.
На новой странице вам потребуется ввести ваш логин API IIko Transport. В зависимости от того, когда вы настраивали ключи на стороне Iiko, они могут выглядеть по-разному. В большинстве случаев они могут выглядеть так:
fdd1dc29914a43e1a5767b82a88c8c53– 33-значная строка;e22240e8-6fe– 12-значная строка с разделителем;8-значная строка или короче. Такие ключи могут иметь короткий срок жизни, поэтому их использовать не рекомендуется.
Если у вас ещё нет API-логина для Iiko Transport, воспользуйтесь инструкцией в справочном центре Iiko – https://ru.iiko.help/articles/#!api-documentations/podklyuchenie-poluchenie-api-klyucha
Вам может потребоваться помощь ваших специалистов по Iiko.
Статья по срокам действия ключей – https://ru.iiko.help/articles/#!api-documentations/sroki-deystviya-api-klucha
Введите этот ключ в поле на первом этапе настройки, согласитесь с передачей токена и отправкой вебхуков разработчику интеграции, после чего нажмите на «Подключить интеграцию».
На следующем этапе вам нужно будет выбрать основную организацию, с которой будет вестись работа интеграции. В частности, эта организация будет отвечать за:
Импорт каталога. Мы будем синхронизировать каталог только из этой организации (даже если на вашем логине доступны другие организации);
Работу Iiko Card. Бонусы будут синхронизироваться только для покупателей, которые доступны внутри этой организации.
Настройки обмена с Iiko Transport
После успешного подключения вам станут доступны дополнительные настройки обмена. Некоторые из них следует настроить сразу после подключения обмена, чтобы все функции интеграции работали корректно (сопоставление способов оплаты; сопоставление статусов заказов; сопоставление терминалов со складами).
Сопоставление способов оплаты
Для того, чтобы мы могли отправлять заказы в Iiko с правильным указанием способа оплаты, вам необходимо сопоставить типы оплаты из Iiko со способами оплаты Zenky. Сделать это можно в дополнительном действии «Сопоставление способов оплаты», которое доступно в начале страницы.
Найдите в списке настроек блок "Оплата". Вы увидите окно, в левой части которого будут перечислены доступные типы оплаты Iiko, а в правой – выбор способа оплаты Zenky для каждого типа оплаты Iiko. Если у вас несколько способов оплаты - жмите кнопку Добавить значение.
Выберите нужный способ оплаты Zenky для каждого типа оплаты Iiko и сохраните список. Обратите внимание, что каждый способ оплаты Zenky можно выбрать только один раз.
Сопоставление статусов заказов
Если вы хотите, чтобы статусы заказов автоматически изменялись в Zenky после их изменения в Iiko, сначала вам нужно сопоставить статусы из Iiko со статусами из Zenky.
Листаем настройки до блока "Заказы". В этом окне вам нужно будет нажать на кнопку Добавить значение столько раз, сколько статусов вы хотите автоматизировать, а затем выбрать аналогичный статус из Iiko для статуса Zenky (необязательно сопоставлять абсолютно все статусы).
Как минимум один статус должен быть отмечен как «Завершающий». Это означает, что как только заказ в Iiko перейдёт в один из таких статусов, мы перестанем запускать проверку статуса для такого заказа. Обычно завершающими статусами являются «Закрыта» («Выполнен») и «Отменена» («Отменён»).
Обратите внимание, что каждый статус Iiko можно выбрать только один раз.
После того, как вы завершите сопоставление статусов, нажмите на кнопку «Сохранить» (может потребоваться проскроллить всплывающее окно).
Сопоставление терминалов Iiko и складов Zenky
Для отправки заказов напрямую на терминалы, необходимо сопоставить склады Zenky с соответствующими терминалами Iiko.
Обратите внимание
По умолчанию мы будем отправлять заказы напрямую на терминалы. Это значит, что если вы работаете с Колл-центром Iiko, заказы не будут попадать к операторам КЦ, а вместо этого будут падать напрямую на кассы.
Если для вас это неприемлемо, вы можете воспользоваться черновиками заказов (см. ниже).
Для каждого терминала можно выбрать опцию «Отправлять заказы напрямую». Если опция выбрана, то все заказы, которые будут связаны с выбранным складом Zenky, будут отправлены напрямую на сопоставленный терминал. Связь заказа со складом Zenky происходит в одном из двух случаях:
Если покупатель оформил заказ на самовывоз и выбрал склад в качестве точки самовывоза;
Если покупатель оформил заказ на доставку, а зона доставки, в которую входит адрес, привязана к текущему складу.
Кроме этого, для одного терминала можно выбрать опцию «Использовать по умолчанию». На терминал, отмеченный такой опцией, будут отправляться заказы, которые не связаны ни с одним складом Zenky.
После завершения сопоставления нажмите на кнопку «Сохранить».
Настройки номенклатуры
В настройках номенклатуры вы можете отключить автоматическую синхронизацию каталога (из вашего Iiko в ваш магазин Zenky), выбрать режим обмена фотографиями и уточнить, что именно использовать в качестве категорий товаров – группы товаров или категории товаров.
Если вы отключите синхронизацию каталога, вам по-прежнему будет доступна ручная синхронизация (см. ниже).
По умолчанию для товаров используются только фотографии из Iiko, но если вы хотите дополнительно загрузить фотографии в панели управления Zenky, измените настройку «Режим обмена фотографиями товаров» на «Использовать фотографии из Iiko и загруженные вручную». Режим «Использовать только фотографии, загруженные вручную» полностью отключает импорт фотографий товаров из Iiko.
Если во время подключения интеграции вы выбрали неправильное значение настройки «В качестве категорий использовать», после её изменения вам потребуется очистить обменник Iiko и выполнить ручную синхронизацию каталога (см. ниже).
Настройка «Использовать фотографии групп» позволяет загружать изображения групп из Iiko в категории товаров Zenky (но только если в качестве категорий у вас используются группы).
Настройки заказов
В настройках заказов вы можете отключить или включить отправку заказов в Iiko (при этом возможность оформления заказа на сайте или в приложении отключена не будет; так же вы продолжите получать уведомления о новых заказах в Telegram или на почту), способ отправки заказов в Iiko, проверку статусов (для работы этой функции необходимо сопоставить статусы заказов; см. выше), добавление номера заказа и связанного склада в комментарии к заказам.
Способ отправки заказов в Iiko
Интеграция с Iiko Transport поддерживает три способа отправки заказов из Zenky в Iiko:
На терминалы. Как было описано выше, с этой настройкой мы будем отправлять заказы напрямую на связанный со складом терминал (или на терминал, выбранный по умолчанию, если к заказу не привязан склад);
Автораспределение. В этом случае Iiko будет распределять заказы по терминалам самостоятельно. Для работы этой опции потребуется включить автораспределение на стороне Iiko;
Черновики заказов. Вместо отправки на терминалы мы будет создавать черновики заказов, которые будут доступны операторам облачного Колл-центра Iiko. Операторы смогут переводить черновики в подтверждённые заказы и отправлять их на конкретные терминалы самостоятельно. Для работы черновиков необходимо настроить внешнее меню. Если у вас есть терминалы со включенной опцией «Отправлять заказы напрямую» (в настройках интеграции Zenky с Iiko Transport), черновики для них создаваться не будут, а заказы будут уходить напрямую на такие терминалы.
Внешнее меню для черновиков
Для работы черновиков необходимо настроить и выгрузить в API Iiko Transport внешнее меню. После того, как вы это сделаете, в настройке «Внешнее меню по умолчанию» появится выбор ваших меню. Выберите нужное (если несколько) и сохраните настройки. После этого вы сможете получать заказы в виде черновиков.
Проверка статусов перенесённых заказов
Настройка «Проверять статусы перенесённых заказов» может быть полезна, если у вас несколько точек и вы переносите оформленные заказы между ними. С выключенной настройкой перенесённый заказ получит статус «Отменён», который отобразится в истории заказов на сайте или в мобильном приложении (так же покупатель может получить пуш-уведомление об отмене заказа, если они у вас подключены).
Вместо этого мы можем попытаться отследить статус нового заказа (перенесённого на другую точку) и обновлять исходный заказ в Zenky с его информацией. ID нового заказа определяется с помощью API (мы проверяем поле movedDeliveryId).
Эта функциональность может отслеживать цепочку до 5 заказов. Если заказ был перенесён более 5 раз, мы завершим проверку статусов и отметим его как отменённый.
Покупатели
Раздел «Покупатели» позволяет уточнить, какие данные покупателей будут отправляться в базу Iiko (во время отправки заказов).
В режиме «Перезаписывать всегда» имя, фамилия и дата рождения покупателей будут перезаписываться данными из Zenky в любом случае, даже если они указаны в профиле Iiko. Например, если в базе Iiko покупатель записан как «Иван Иванов», а в базе Zenky – «Ivan Ivanov», после отправки заказа в базе Iiko имя и фамилия станут «Ivan Ivanov»;
В режиме «Перезаписывать пустые значения» данные покупателя будут отправлены в Iiko, только если они не указаны. Например, покупатель с именем Иван (но без фамилии) после отправки заказа будет записан как «Иван Ivanov». Мы рекомендуем использовать этот режим.
Важно отметить, что если какие-то данные покупателя не указаны в базе Zenky, информация в базе Iiko не будет перезаписана пустыми значениями в любом из указанных режимов.
Iiko Card
Если вы используете Iiko Card и у вашего магазина Zenky подключена программа лояльности, в этом разделе вы можете указать дополнительные параметры обмена бонусами.
С помощью настройки «Способ синхронизации бонусов из Iiko Card в Zenky» вы можете выбрать как именно бонусы из Iiko Card будут передаваться в программу лояльности Zenky. Способ «Корректировка баланса» будет создавать одну транзакцию пополнения или списания бонусов в Zenky – например, если баланс покупателя в Zenky – 500 бонусов, а в IikoCard – 250, то во время синхронизации будет создана одна транзакция корректировки на списание 250 бонусов (при этом изначально баланс в Iiko мог быть изменён несколькими транзакциями). Способ «Изменение баланса» будет создавать отдельные транзакции пополнения или списания бонусов после каждой операции в iiko.
Настройка «Источник бонусов для корректировки» может быть полезна, если вы используете несколько кошельков Iiko Card. По умолчанию при корректировке мы берём баланс только из первого кошелька с нужным типом (настройка «Кошелек для пополнения бонусов Zenky»). При работе с несколькими кошельками бонусы могут синхронизироваться некорректно, поэтому вы можете поменять значение на «Использовать баланс всех подходящих кошельков» – в этом случае мы просуммируем баланс бонусов.
В списке «Начисления бонусов Zenky, которые нужно отправлять в Iiko Card» вы можете выбрать типы транзакций Zenky, которые должны изменять баланс покупателя в Iiko Card. Например, если вы используете программу «Пригласи друга» в Zenky, бонусы за приглашения друзей не будут отправляться в Iiko Card, пока вы не выберете тип «Награда за приглашение» в этом списке. Важно: если вы начисляете кэшбэк на стороне Iiko Card, не выбирайте тип транзакции «Кэшбэк» из этого списка. Так же в настройках бонусной программы (раздел «Лояльность» -> «Бонусная система») вам нужно поменять значение настройки «Обработчик кэшбэка» на «Внешняя система». В противном случае покупатель может получить два кэшбэка – один от Zenky и один от Iiko Card.
В настройке «Кошелёк для пополнения баланса в Iiko Card» вы можете выбрать конкретный кошелёк, в который будут отправляться бонусы из Zenky. Если вы используете один кошелёк, можете оставить значение этой настройки по умолчанию («Использовать первый подходящий кошелёк»).
Стоп-листы
Для работы стоп-листов необходимо включить проверку остатков товаров при добавлении товара в корзину или во время оформления заказа. Сделать это можно включив настройку «Проверка остатков товаров» в разделе «Магазин» -> «Настройка заказов». Выберите любой режим проверки и укажите этап проверки остатков.
Если синхронизация стоп-листов включена, остатки всех товаров из вашего стоп-листа будут передаваться в Zenky. Когда остатки в стоп-листе достигнут нуля, заказы с этим товаром нельзя будет оформить (если включена проверка остатков).
Настройка «Поведение остатков при удалении товара из стоп-листа» отвечает за поведение, когда товар удаляется из стоп-листа. Например, вы добавили некий товар в стоп-лист с нулевыми остатками. Через какое-то время вы вернули его в продажу и удалили из стоп-листа. В зависимости от того, какое значение выбрано у этой настройки, товар либо станет доступен для заказа в Zenky, будет снят с продажи или же будет проигнорирован (остатки в Zenky не изменятся).
Адреса доставки
В некоторых базах Iiko могут наблюдаться проблемы с приёмом заказов с сайта или из приложения – бывает, что локальная база адресов имеет некоторые различия и из-за этого не может определить адрес доставки. Например, в вашей базе все улицы могут быть записаны как «Ленина улица», «Октябрьская улица» и т.д., в то время как мы отправляем адрес доставки без указания типа улицы – просто «Ленина» или «Октябрьская». Если вас коснулась эта проблема, мы можете добавить свои правила форматирования улиц, и мы будет формировать адрес доставки в соответствии с этими правилами.
Вы можете добавить несколько правил для тех типов улиц, которые в вашей базе записаны по-особому. Поле «Расположение» отвечает за то, где подставлять тип улицы – до названия («улица Ленина») или после («Ленина улица»). Поле «Тип названия» задаёт короткое название типа улицы («ул») или полное («улица»).
Заполните все поля, чтобы увидеть предпросмотр строки улицы, которая будет отправлена в Iiko.
Перед тем, как добавлять правила, проконсультируйтесь с вашим системным администратором Iiko или с интегратором. Возможно, в вашей базе улицы заполнены без типов, поэтому добавлять правила не потребуется.
Мы используем базу ФИАС, которую получаем от сервиса Dadata.ru.
Импорт каталога
Вы можете выполнить ручную синхронизацию каталога из базы Iiko в базу Zenky, не дожидаясь автоматической выгрузки (происходит раз в 20 минут, если каталог в Iiko изменился).
В столбце слева найдите пункт "Действия" и нажмите на него. В открывшемся окне вы можете указать дополнительные параметры ручной синхронизации.
«Игнорировать ревизию» – синхронзация будет выполнена, даже если каталог в Iiko не изменился. Если настройка не выбрана и каталог не менялся, данные не будут повторно выгружены в Zenky;
«Полная выгрузка» – если выбрано, в Zenky будет передан весь каталог Iiko (товары, категории и модификаторы). В противном случае мы выгрузим только те данные, которые были изменены после последней синхронизации.
После запуска импорта данные поступят в каталог Zenky спустя несколько минут (обычно – не более 5 минут, но в некоторых случаях время ожидание может быть увеличено).
Проверка номенклатуры
Если какие-то товары или категории в вашем каталоге не отображаются (или отображаются неправильно), вы можете проверить актуальный ответ API номенклатуры от Iiko Biz.
Сделать это можно, с помощью блока "Проверка номенкулатуры"
В открывшемся окне нажмите на кнопку «Загрузить номенклатуру». Ответ API будет доступен в текстовом поле (формат JSON). Для проверки данных вам может потребоваться помощь вашего системного администратора Iiko или интегратора.
При проверке обращайте внимание на номер ревизии (поле revision) и дату последней выгрузки (поле uploadDate). Если необходимые данные присутствуют в выгрузке, но не появляются в каталоге Zenky после принудительной ручной синхронизации, вам может потребоваться очистка данных обменника Iiko.
Очистка данных
Мы храним копию вашего каталога Iiko в промежуточном сервисе, который мы называем обменником Iiko. С его помощью мы определяем какие данные изменились (чтобы не синхронизировать весь каталог постоянно), принимаем заказы из Zenky и отправляем их в Iiko, а так же выполняем дополнительные сервисные действия (проверка статусов заказов, синхронизация бонусов и стоп-листов и т.д.).
Если вы заметили какие-то неточности в каталоге или хотите полностью сбросить все данные и начать с чистого листа, вам поможет очистка данных в обменнике Iiko.
Мы удаляем только те данные, которые храним у себя. Никакие очистки данных не удалят информацию из вашей базы Iiko.
Найдите пункт «Очистка данных» - он находится в самом низу страницы "Действия". В открывшемся окне вы можете выбрать, какие именно данные нужно удалить.
«Удалить категории» – из обменника будут удалены все категории товаров (или группы товаров, если в качестве категорий вы используете группы);
«Удалить товары» – из обменника будут удалены все товары;
«Удалить модификаторы» – из обменника будут удалены все модификаторы товаров (групповые и одиночные);
«Удалить стоп-листы» – из обменника будут удалена вся информация о стоп-листах. Остатки товаров в Zenky не будут изменены;
«Удалить заказы» – из обменника будут удалены все заказы, которые были ранее отправлены в Iiko (в самой базе Iiko заказы удалены не будут). Если какие-то заказы ещё находились в стадии проверки статусов, их статусы больше не будут обновляться;
«Удалить статусы заказов» – из обменника будет удалено сопоставление статусов заказов Iiko и Zenky;
«Удалить способы оплаты» – из обменника будет удалено сопоставление способов оплаты Iiko и Zenky;
«Удалить терминалы» – из обменника будет удалено сопоставление терминалов Iiko и складов Zenky.
Выберите нужные опции и нажмите на кнопку «Удалить данные». В течение нескольких минут (до пяти) данные в обменнике будут удалены, после чего вы сможете выполнить ручную синхронизацию для импорта свежих данных.
Очистка каталога Zenky
Если очистка данных обменника не помогла решить проблему или же вы начали наблюдать дубликаты категорий или товаров, вам потребуется очистить каталог Zenky.
Очистка каталога Zenky крайне не рекомендуется для магазинов, которые уже начали работу и принимают заказы. В случае удаления товаров все заказы покупателей в Zenky будут обнулены, и у покупателей не будет возможности просмотреть историю заказов.
Так же изменятся ссылки на товары или категории. Если вы размещали ссылки на конкретные категории товаров, они перестанут работать.
Очистка каталога Zenky доступна в разделе «Магазин» -> «Очистка данных». Очистку данных может запустить только сотрудник магазина с ролью «Владелец» и не чаще одного раза в 24 часа.
После очистки каталога Zenky, повторно очистите данные обменника, подождите несколько минут и выполните ручную синхронизацию.
Обновление API-логина Iiko Transport
Если ваш API-логин Iiko Transport истёк, вы можете обновить его в разделе «Действия» вашей интеграции с Iiko Transport в панели управления магазином Zenky.
Обратите внимание
В статье справочного центра Iiko дана информация о сроках действия API-ключей – https://ru.iiko.help/articles/#!api-documentations/sroki-deystviya-api-klucha
Перейдите в раздел "Интеграции" в панели управления Zenky. На этой странице выберите раздел «Установленные» и нажмите на карточку интеграции с Iiko Transport.
На открывшейся странице выберите раздел «Действия» в левом меню. Найдите блок «Изменить API логин» и введите новый логин в поле «Новый логин API Iiko Transport».
Будьте внимательны!
В этом поле необходимо ввести логин API, который имеет доступ к тем же организациям, что и предыдущий логин. Он должен обладать такими же разрешениями API, иначе мы не сможем корректно синхронизировать каталог и отправлять заказы в Iiko.
Пожалуйста, проконсультируйтесь с вашими специалистами по Iiko, прежде чем изменять API логин.
Если логин не подойдёт, вы увидите текст ошибки во всплывающем окне (см. ниже).
Нажмите на «Сохранить логин». После отправки данных откроется всплывающее окно, в котором вы увидите результат изменения логина.
Выше показан пример успешного изменения логина API. Однако, вы можете увидеть одну из следующих ошибок, если что-то пошло не так:
Вы указали некорректный логин API Iiko Transport. Возникает, когда вы ввели в поле неправильный логин. Перепроверьте значение или проконсультируйтесь с вашими специалистами по Iiko.
Не удалось получить список организаций для этого логина API Iiko Transport. Возникает, когда введён корректный логин, но у него нет доступа ни к одной организации Iiko. Перепроверьте логин или проконсультируйтесь с вашими специалистами по Iiko.
Текущая организация отсутствует в списке организаций, полученных из Iiko Transport. Скорее всего, вы указали логин API, который относится к другой организации. Возникает, когда у нового токена нет доступа к текущей организации по умолчанию. Организация по умолчанию задаётся в настройке «Организация по умолчанию», а отвечает за синхронизацию каталога и бонусов. Убедитесь, что у нового логина есть доступ к этой организации.
Last updated