Меню

Особенности подключения Iiko API

logo
Iiko API это JSON API. Каждый запрос нужно подписывать специальным временным токеном доступа. Получить временный токен можно используя имя и пароль Вашего Iiko аккаунта, предоставленного Вам Iiko.
Особенности подключения Iiko API

Iiko API это JSON API. Каждый запрос нужно подписывать специальным временным токеном доступа. Получить временный токен можно используя имя и пароль Вашего Iiko аккаунта, предоставленного Вам Iiko.

Чтобы получить токен обратитесь по адресу https://card.iiko.co.uk/api/0/auth/access_token?user_id=$username&user_secret=$password, где $username и $password - это имя и пароль Вашего аккаунта Iiko.

Все дальнейшие действия будут совершаться с использованием токена, который будет передаваться в строке запроса как значение ключа access_token. Также можно указать таймаут запроса, request_timeout в формате "H:i:s".

Внутри Iiko все сущности, такие как рестораны, номенклатура и т.д., привязаны к основной сущности - организации, поэтому прежде чем использовать другие возможности Iiko API, давайте получим список организаций с помощью /api/0/organization/list?access_token=$access_token&request_timeout=$request_timeout, где $access_token - Ваш ранее полученый временный токен, $request_timeout - таймаут. Из выбранного массива доступных организаций выберите необходимую и сохраните её Id.

Используем сохраненный Id организации, $organizationId, для получения например номенклатуры. Будьте внимательны, Id организации может использоваться как в строке запроса, так и в теле запроса и даже в пути (path), при чем это не зависит однозначно от метода запроса (GET/POST), для надежности обратитесь к документации (ссылка https://docs.google.com/document/d/1pRQNIn46GH1LVqzBUY5TdIIUuSCOl-A_xeCBbogd2bE/edit#). Используя адрес /api/0/nomenclature/$organizationId мы можем получить список всех доступных продуктов и категорий, в терминах Iiko - групп, Вашего заведения. Каждая сущность имеет свой Id в системе Iiko, который Вам необходимо сохранить на своем сайте, т.к. он будет использоваться далее. Будьте внимательны, продукты могут иметь разные типы и некоторые продукты могут быть составнимы, продукт с ингредиентами. Более того, продукты, ингредиенты которого отмеченные как обязательные, не может быть передан в Iiko без этих ингредиентов. Также ингредиенты могут иметь минимальное и максимальное количество вхождений в продукт и несоответствие этого количества границам может повлечь за собой отказ Iiko сохранять заказ.

Также перед использованием API учтите, что массовый импорт групп и продуктов производится только сотрудниками Iiko. Также стоит учитывать, что все остальные манипуляции могут быть осуществлены с помощью терминала Iiko Biz, который также необходимо будет установить на рабочие компьютеры.

При создании заказа в Iiko с помощью API, мы можем указать много полезной информации. Используйте ранее созраненные временный токен и Id организации, чтобы получить списки доступных:

типов оплат - /api0/rmsSettings/getPaymentTypes?organisation=$organizationId&access_token=$access_token, типов заказов - /api0/rmsSettings/getOrderTypes?organisation=$organizationId&access_token=$access_token, маркетинговых источников - /api0/rmsSettings/getMarketingSources?organisation=$organizationId&access_token=$access_token. пунктов выдачи (терминалов доставки) - /api0/deliverySettings/getDeliveryTerminals?organisation=$organizationId&access_token=$access_token.

Будьте внимательны, любое изменение вышеуказанных типов/пунктов/источников в терминале Iiko Biz повлечет за собой изменение Id сущности, поэтому, если Вы используете периодическую синхронизацию этих данных, при очередной настройке на всякий случай проведите синхронизацию внеочередно, много времени это не займет, но позволит избежать отказа Iiko от сохранения заказов.

Что же касается самого сохранения заказа - здесь мы будем использовать все то, что получили ранее. Рассмотрим json, соответствующий заказу с сайта, который мы будем передавать:

{
   "organization" : $organizationId,
   "deliveryTerminalId" : $deliveryTerminalId,
   "customer" :
   {        "id" : $customerId,
       "name" : "Asabix",
       "phone" : "+380979981891",
       "email" : "[email protected]"
   },
   "order" :
   {
       "date" : $deliveryDate,
       "phone" : "+380979981891",
       "customerName" : "Asabix",
       "fullSum" : "613.00",
       "isSelfService" : true,
       "orderTypeId" : $orderTypeId,
       "personsCount" : $personsCount,
       "marketingSourceId" : $marketingSourceId,
       "items" : [
    {
       "id" : $firstProductId,
       "name" : "First Product",
       "amount" : "1",
       "code" : $firstSku,
       "sum" : "502.00"
    },
    {
       "id" : $secondProductId,
       "name" : "Second Product",
       "amount" : "1",
       "code" : $secondSku,
       "sum" : "111.00",
       "modifiers" : [
    {
       "id" : $firstModifierId,
       "name" : "First Modifier",
       "amount" : $firstModifierAmount,
       },
    {
        "id" : $secondModifierId,
        "name" : "Second Modifier",
        "amount" : $secondModifierAmount,
       }
        ]
    }
    ],
    "address" :
    {
       "city" : "Zhytomyr",
       "street" : "Vitruka",
       "home" : "9v",
       "housing" : null,
       "apartment" : null,
       "entrance" : null,
       "floor" : null,
       "doorphone" : null,
       "comment" : "From Small To Extra Large. Everywhere. Everytime"
    },
    "paymentItems" : [
    {
       "sum":"613.00",
       "paymentType":
       {
          "id" : $paymentTypeId,
          "code" : $paymentTypeCode,
          "name" : "",
          "comment" : "full"
       },
       "isProcessedExternally" : false
    }
    ]
   }
}

Видим, что мы используем ранее сохраненный $organizationId, на этот раз в теле запроса, а также $deliveryTerminalId, $orderTypeId, $marketingSourceId, $paymentTypeId, которые были получены ранее. Таким образом мы можем узказать тип заказа, тип оплаты, а в используя ключ paymentItems и передать информацию об оплате. Кроме того, $paymentTypeId может быть заменен на $paymentTypeCode, где может храниться человекопонятный код, например "CASH" или "CARD". $deliveryDate - это желаемые дата и время доставки в формате "Y-m-d H:i:s", $customerId - Id клиента в Iiko, который привязан к номеру телефона. Его можно получить с помощью /api/0/customers/get_customer_by_phone или, если его нет, создать /api/0/customers/create_or_update, см. документацию (ссылка https://docs.google.com/document/d/1pRQNIn46GH1LVqzBUY5TdIIUuSCOl-A_xeCBbogd2bE/edit#).

Данные о продуктах хрантся в orders > items. Также использованы $firstProductId и $secondProductId, которые являются Id продуктов в Iiko, о которых мы говорили ранее, и они обязательны при передаче заказа, без них Iiko откажется сохранять заказ. Для второго продукта приведен пример передачи модификаторов, о которых также говорилось ранее. Если их наличие обязательно в составе продукта, то их тоже нужно включать в запрос на сохранение, иначе Iiko откажется сохранять заказ. Для них так же необходимы их Id, поэтому их тоже нужно сохранять в базе данных сайта. Учитывая, что некоторые из них могут быть самостоятельными продуктами, их связь с родительскими продуктами можно описать с помощью шаблона Composite, он же позволит удобнее формировать передаваемую структуру продуктов в заказе. $firstModifierAmount и $secondModifierAmount напомают, что их значения должны удовлетворять некоторым границам, указанным в Iiko Biz. $firstProductSku, $secondProductSku и $personsCount - необязательные параметры для API, но полезные с точки зрения отчетности.

Обработка ошибок Iiko API может вызвать некоторые проблемы, т.к. способ возвращения ошибок вариируется от типа ошибок. Так отлавливаемые ошибки в логике Iiko возвращаются в удобном формате и с кодом 4xx, например превышен amount модификатора, а неотлавливаемые могут вернуться как стэк вызовов функций (в данном случае Java) и с кодом 500, например amount модификатора превысил верхнюю границу значений типа переменной или произошла ошибка приведения типа и параметр имеет целочисленный тип вместо ожидаемого булевого, 1 вместо true, что случается при разработке/тестировании =).

Конечно Вы можете далеть запросы на получение всех Id типов заказов, оплат и так далее, каждый раз при сохранении заказа, но как минимум номенклатуру стоит синхронизироть периодически, но если система стабильна и все типы меняются крайне редко - переведите и их на периодику, в крайнем случае запускайте синхронизацию вручную. Без периодики Вы будете испытывать проблемы с производительностью, а с периодикой, но частым изменением типов, - Iiko будет отказываться сохранять заказы для несуществующих типов и заказы могут тормозить очередь вплоть до следующей синхронизации.

Оптимизация веб-проекта — 3 способа ускорить загрузку веб-страниц 01.09.2019 Оптимизация веб-проекта — 3 способа ускорить загрузку веб-страниц
Вы разработали дизайн сайта, подобрали соответствующие теме картинки и заказали дорогой текст для лендинга, но количество посещений минимальное. Если Вам знакома такая ситуация, не спешите вкладываться в контекстную рекламу и другие сервисы для увеличения числа посетителей. Прежде всего, Вам нужна оптимизация сайта.

Реализация подключения API Payoneer 10.09.2019 Реализация подключения API Payoneer
Подключение к платежной системе API Payoneer. Основные среды подключения. Прохождение пользователем регистрации/авторизации по предоставленной ссылке, список пользователей.

Возврат к списку