Jupiter.KDS API - мониторы повара и сборщика

Авторизация рабочего места сборщика

/kds/auth

Параметры запроса

• uid - код места расположения принтера
• tz - код торгового зала

Параметры ответа

• status - статус обработки запроса
• message - объект с параметрами ответа
  • uid - уникальный идентификатор места приготовления, использовать в дальнейших запросах
  • tz - уникальный идентификатор торгового зала, использовать в дальнейших запросах
  • text - текст ошибки. Передается только если при обработке запроса были ошибки

Логика работы

• Поиск реквизитов рабочего места сборщика по человеко-читаемым параметрам: код места приготовления (uid - место расположения принтера в Юпитере), код торгового зала (tz).
• Если данные найдены, то возвращает UID объектов в Jupiter.
• После успешной авторизации реквизиты сохраняются в LocalStorage, повторная регистрация не требуется. Во всех последующих запросах нужно передавать UID'ы объектов, а не коды.

Примеры

POST запрос:

{
    "uid" : "1-000008",
    "tz": "000840"
}

Ответ успех:

{
    "status": "ok",
    "message": {
      "uid": "4:1:0:48",
      "tz": "4:98:0:27813",
    }
}

Ответ ошибка:

{
    "status": "error",
    "message": {
      "text": "В системе не найдено место расположения принтера с таким кодом"
    }
}

Получение списка заказов сборщика\очереди

/kds/get_orders

Параметры запроса

• uid - UID места расположения принтера (из настроек)
• tz - UID торгового зала (из настроек)
• timestamp - дата\время последнего запроса данных
• queue - признак, что это запрос от монитора очереди. Если запрос от монитора сборщика, то параметр = 0. Если от монитора очереди, то queue = 1. На монитор очереди передаются ВСЕ заказы, а не только приготовленные (как на монитор сборки)

Параметры ответа

• status - статус обработки запроса
• message - объект с параметрами ответа
  • timestamp - новый timestamp, который должен будет использоваться в следующем запросе
  • orders - массив со списком заказов
    • order_uid - уникальный идентификатор заказа в Юпитере
    • kod - кода заказа в Юпитере (уникален в рамках рабочего дня)
    • label - заголовок заказа. Если заказ на доставку, то выводится адрес, иначе имя сотрудника, который открыл заказ.
    • source - название источника заказа
    • type - название вида заказа
    • cooking_time - время на приготовление заказа по нормативу. Кол-во минут.
    • status - статус сборки заказа. 0 - не собран, 1 - собран (готов к передачи клиенту)
    • persons - кол-во гостей
  • lines - массив с базовыми строкам
    • item_name - название товара
    • item_quant - количество товара
    • line_uid - уникальный идентификатор строки
  • modifiers - массив с строками модификаторов
    • item_name - название товара
    • item_quant - количество товара. Количество выводится в формате "Кол-во в базовой строке" X "Кол-во модификатора"
    • line_uid - уникальный идентификатор строки
    • base_line_uid - ссылка на базовую строку, к которой относится строка модификатора
    • text - текст ошибки. Передается только если при обработке запроса были ошибки

Логика работы

• Проверяет, что в системе были изменения, которые нужно отобразить на мониторе сборщика. Для этого используется timestamp (дата в формате ГГГГМММДДЧЧММСС).
• Если изменения были то возвращает массив заказов (orders), которые относятся к указанному в запросе торговому залу (tz - uid торгового зала) и месту приготовления (uid - uid места приготовления)
• Если изменений не было, то массив orders не возвращается.
• Если timestamp не получен, то возвращает все заказы.
• Также в ответе возвращает новый timestamp, который должен будет использоваться в следующем запросе.
• В массиве lines передается список базовых строк заказа.
• В массиве modifiers передается список строк-модификаторов, строка модификатора имеет ссылку на базовую строку заказа (base_line_uid). Порядок элементов в массиве значения не имеет.
• Если не включена роль "Работа КЦ без точек", то на монитор сборщика передаются заказы с признакам, что заказ приготовлен

Примеры

POST запрос:

{
    "uid" : "4:1:0:48",
    "tz": "4:98:0:27813",
    "timestamp": "20210806222346",
    "queue": 0
}

Ответ успех, c прошлого обращения произошли изменения в списке заказов:

{
  "status": "ok",
  "message": {
    "timestamp": "20210806233513",
    "orders": [
      {
        "order_uid": "5:3:0:768201",
        "kod": "6",
        "label": "Москва, ул.Тверская, д.1, кв.1",
        "source": "Сайт",
        "type": "Доставка",
        "cooking_time": 20,
        "status": 0,
        "persons": 1,
        "lines": [
          {
            "item_name": "КРЕВЕТКИ С ЛАПШОЙ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507564"
          },
          {
            "item_name": "ГОВЯДИНА С  ЛАПШОЙ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507561"
          }
        ],
        "modifiers": [
          {
            "item_name": "ПШЕНИЧНАЯ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507562",
            "base_line_uid": "6:3:0:4507561"
          },
          {
            "item_name": "ГРЕЧНЕВАЯ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507566",
            "base_line_uid": "6:3:0:4507564"
          },
          {
            "item_name": "ПШЕНИЧНАЯ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507565",
            "base_line_uid": "6:3:0:4507564"
          },
          {
            "item_name": "ГРЕЧНЕВАЯ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507563",
            "base_line_uid": "6:3:0:4507561"
          }
        ]
      },
      {
        "order_uid": "5:3:0:768202",
        "kod": "5",
        "label": "Иванов И.И.",
        "source": "Телефон",
        "type": "Обычный заказ",
        "cooking_time": 20,
        "status": 1,
        "persons": 2,
        "lines": [
          {
            "item_name": "ГОВЯДИНА С ОВОЩАМИ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507568"
          },
          {
            "item_name": "КРЕВЕТКИ ВАСАБИ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507567"
          },
          {
            "item_name": "КРЕВЕТКИ С АНАНАСАМИ В К-С СОУСЕ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507570"
          },
          {
            "item_name": "КРАБОВЫЕ ШАРИКИ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507601"
          }
        ],
        "modifiers": [
          {
            "item_name": "ГРЕЧНЕВАЯ",
            "item_quant": 1,
            "line_uid": "6:3:0:4507569",
            "base_line_uid": "6:3:0:4507568"
          }
        ]
      }
    ]
  }
}

Ответ успех, c прошлого обращения нет изменений в списке заказов:

{
  "status": "ok",
  "message": {
    "timestamp": "20210806233513"
  }
}

Ответ успех, c прошлого обращения произошли изменения в списке заказов, но список заказов пуст:

{
  "status": "ok",
  "message": {
    "timestamp": "20210806233513",
    "orders": []
  }
}

Ответ ошибка:

{
    "status": "error",
    "message": {
      "text": "Неправильный идентификатор места приготовления",
    }
}

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

/kds/set_order_status

Параметры запроса

• uid - UID места расположения принтера (из настроек)
• tz - UID торгового зала (из настроек)
• timestamp - дата\время последнего запроса данных
• order_uid - UID заказа, у которого нужно изменить статус
• status - код нового статуса
• queue - признак, что это запрос от монитора очереди. Если запрос от монитора сборщика, то параметр = 0. Если от монитора очереди, то queue = 1. На монитор очереди передаются ВСЕ заказы, а не только приготовленные (как на монитор сборки)

Параметры ответа

• Для статусов 1, 2 варианты ответа полностью идентичны с запросом на получение список заказов (get_orders).
• Для статуса 3, возвращается только статус обработки запроса (status)

Логика работы

Изменяет статус переданного заказа (order_uid). Статус заказ определяется параметром status. Возможные варианты:

• 1 - Заказ собран сборщиком.
  • Статус заказа изменяется на "Готов к передачи клиенту".
  • При необходимости статус заказа передается на сайт\приложение\агрегаторы
• 2 - Заказ передан клиенту.
  • Заказ удаляется с монитора сборщика.
  • Если включена опция "Работа КЦ без точек", то статус заказа изменяется на "Назначен курьеру", иначе статус заказа не изменяется.
• 3 - Заказ приготовлен поваром.
  • Заказ удаляется из очереди на приготовление, появляется на мониторе сборщика.
  • Статус заказа изменяется на "Приготовлен"
  • В заказ записывается "Дата\время, когда заказ приготовлен", по алгоритму:
    • Проверяет, был ли просрочен заказ
      • Для этого вычисляется "Дата\время когда заказ должен быть приготовлен по нормативу". Формула: "Дата\Время, когда начали готовить" (параметр заказа) + "Время необходимое для приготовления заказа" (параметр заказа)
      • Сравнивается с текущей датой\время на сервере

    • Если заказ был просрочен, то фиксируем 2 времени:

      •  "Дата\время когда заказ должен быть приготовлен по нормативу" в параметр "Дата\время, когда заказ приготовлен"

      • Текущая дата\время на сервере в параметр "Дата\время, когда просроченный заказ приготовлен". Этот параметр будет флагом, что заказ просрочен

    • Если заказ приготовлен вовремя, то фиксируем текущую дату\время на сервере как "Дата\время, когда заказ приготовлен"

Примеры

POST запрос:

{
  "uid": "4:1:0:48",
  "tz": "4:98:0:27813",
  "timestamp": "20210806233513",
  "order_uid": "5:3:0:768201",
  "status": 1,
  "queue": 0
}

• Для статусов 1, 2 варианты ответа полностью идентичны с запросом на получение список заказов (get_orders).
• Для статуса 3, возвращается только статус обработки запроса (status)

Трекер повара. Получить заказ

/kds/get_order

Параметры запроса

• uid - UID места расположения принтера (из настроек)
• tz - UID торгового зала (из настроек)
• station_num - номер станции (из настроек)
• timestamp - дата\время последнего запроса данных

Параметры ответа

• status - статус обработки запроса
• message - объект с параметрами ответа
  • timestamp - новый timestamp, который должен будет использоваться в следующем запросе
  • order - объект с параметрами заказа
    • order_uid - уникальный идентификатор заказа в Юпитере
    • kod - кода заказа в Юпитере (уникален в рамках рабочего дня)
    • label - заголовок заказа. Если заказ на доставку, то выводится адрес, иначе имя сотрудника, который открыл заказ.
    • source - название источника заказа
    • type - название вида заказа
    • cooking_time - время на приготовление заказа по нормативу. Кол-во минут.
    • status - статус сборки заказа. 0 - не собран, 1 - собран (готов к передачи клиенту)
  • lines - массив с базовыми строкам
    • item_name - название товара
    • item_quant - количество товара
    • line_uid - уникальный идентификатор строки
  • modifiers - массив с строками модификаторов
    • item_name - название товара
    • item_quant - количество товара. Количество выводится в формате "Кол-во в базовой строке" X "Кол-во модификатора"
    • line_uid - уникальный идентификатор строки
    • base_line_uid - ссылка на базовую строку, к которой относится строка модификатора
  • orders_in_queue - текущее количество заказов в очереди на приготовление
  • text - текст ошибки. Передается только если при обработке запроса были ошибки

Логика работы

• Проверяет, что в системе были изменения после переданного timestamp, которые нужно отобразить на трекере повара.
• Если изменения были, то возвращает заказ (параметр ответа "order"), который нужно готовить:
  • Если для станции уже есть незавершенный заказ, то возвращает его.
  • Если текущего заказа нет, то возвращает первый по очереди заказ.
    
    • Записывает в заказ признак, что заказ принят в работу.
    • Записывает текущую дату\время на сервере в параметр заказа "Дата/время когда начали готовить заказ".
• Если изменений не было, то заказ не возвращается.
• 2022-03-14 Если запрос пришел от станции чей номер > 1, то дополнительно выполняем проверку, что можно отдать заказ на эту станцию. Это нужно для соблюдения очереди станций. В первую очередь заказы передаются на станции с меньшим номером. Проверка выполняется по алгоритму:
  • В памяти сохраняется дата\время последнего запроса от каждой станции
  • Если с момента прошлого запроса прошло более 20 сек, то станция считается выключенной\занятой
  • Перед тем как отправить заказ на станцию с номером > 1, проверяем, что все предыдущие станции выключены\заняты.
  • Если какая либо из этих станций работает, то заказ не отдаем и ждем запрос от работающей станции чей номер ниже текущей

Примеры

POST запрос:

{
    "uid" : "4:1:0:48",
    "tz": "4:98:0:27813",
    "station_num": "1",
    "timestamp": "20210806222346"
}

Ответ успех, c прошлого обращения произошли изменения:

{
    "status": "ok",
    "message": {
        "timestamp": "20210806233513",
        "order": {
            "order_uid": "5:3:0:768201",
            "kod": "6",
            "label": "Москва, ул.Тверская, д.1, кв.1",
            "source": "Сайт",
            "type": "Доставка",
            "cooking_time": 20,
            "status": 0,
            "persons": 2,
            "lines": [{
                    "item_name": "ГОВЯДИНА С  ЛАПШОЙ",
                    "item_quant": 1,
                    "line_uid": "6:3:0:4507561"
                }
            ],
            "modifiers": [{
                    "item_name": "ПШЕНИЧНАЯ",
                    "item_quant": 1,
                    "line_uid": "6:3:0:4507562",
                    "base_line_uid": "6:3:0:4507561"
                }
            ]
        },
        "orders_in_queue": 4
    }
}

Ответ успех, c прошлого обращения нет изменений:

{
  "status": "ok",
  "message": {
    "timestamp": "20210806233513"
  }
}

Ответ успех, c прошлого обращения произошли изменения, но заказа для готовки нет:

{
  "status": "ok",
  "message": {
    "timestamp": "20210806233513",
    "order": {},
    "orders_in_queue": 0
  }
}

Ответ ошибка:

{
    "status": "error",
    "message": {
      "text": "Неправильный идентификатор торгового зала",
    }
}

Трекер повара. Завершить работу

/kds/stop_work

Параметры запроса

• uid - UID места расположения принтера (из настроек)
• tz - UID торгового зала (из настроек)
• station_num - номер станции (из настроек)

Параметры ответа

• status - статус обработки запроса
• message - объект с параметрами ответа
  • text - текст ошибки. Передается только если при обработке запроса были ошибки

Логика работы

• Если для станции есть незавершенный заказ, то отмечает его как завершенный (по логике запроса set_order_status)
• Снимает со всех заказов станции признак "Заказ в работе".

Примеры

POST запрос:

{
    "uid" : "4:1:0:48",
    "tz": "4:98:0:27813",
    "station_num": "1"
}

Ответ успех:

{
    "status": "ok",
}

Ответ ошибка:

{
    "status": "error",
    "message": {
      "text": "Неправильный идентификатор торгового зала",
    }
}