Как работать с Zafiro

Начало

Что такое Zafiro

Система состоит из двух частей:

• Панель на zafiro.kz — открывается в браузере. Здесь работают владелец, администраторы, кассиры и операторы.
• Агент — программа для Windows на каждом ПК клуба. Показывает клиенту экран входа, время и баланс, продаёт тарифы и товары, блокирует ПК, когда время закончилось.

Свой сервер не нужен: данные хранятся в облаке Zafiro, клуб видит только свои данные.

Термины

Клуб

Ваше заведение в Zafiro. У одного аккаунта может быть несколько клубов, они переключаются в панели.

Зона

Часть зала на карте: VIP, Bootcamp, PS5 и т.д. У зоны есть цена часа и список ПК.

Сессия

Оплаченное время на ПК. Начинается с покупки тарифа или минут, заканчивается по времени или кнопкой «Завершить сессию».

Гостевая сессия

Время, проданное на кассе клиенту без аккаунта. ПК открывается без входа.

Ключ установки

Постоянный ключ клуба. Его вводят в агенте при подключении первого ПК.

Токен ПК

Секрет, по которому сервер узнаёт конкретный ПК. Хранится в службе Zafiro Agent, клиент его не видит.

Служба Zafiro Agent

Служба Windows, которую ставит установщик. Хранит токен ПК и снова запускает агент, если его закрыли.

Основной и бонусный счёт

Два баланса клиента. Основной пополняется на кассе деньгами, бонусный — бонусами. Тариф может разрешать оплату бонусами.

Начало

Быстрый старт

Подключение клуба занимает один вечер. Первые 14 дней — бесплатно.

1. Зарегистрируйте клубОткройте zafiro.kz/register, укажите имя, телефон, пароль и название клуба. Вы станете владельцем клуба.
2. Создайте зоны«Зоны» → «Добавить зону». Задайте название, вместимость и цену часа (для поминутной оплаты).
3. Создайте тарифы«Тарифы» → «Новый тариф»: название, длительность, цена, зоны, способ оплаты.
4. Установите агент на первый ПКСкачайте установщик, запустите его от имени администратора, введите ключ установки (Настройки → Настройка клуба) и войдите своим телефоном и паролем. ПК появится на карте.
5. Подключите остальные ПКПовторите установку на каждом ПК или настройте один раз суперклиент для бездисковой системы — остальные ПК подключатся сами.
6. Добавьте сотрудников«Работники» → добавьте кассиров и операторов по телефону или пригласите ссылкой. Задайте PIN для выхода из агента.

Начало

Роли и доступ

Роль задаётся каждому участнику клуба. Кассир и оператор не видят административных разделов: при входе кассир попадает в «Кассу», оператор — на карту клуба.

Клиент — роль посетителя. Клиент не входит в панель: он входит только в агент на ПК, а на сайте подтверждает вход по QR-коду.

Панель

Админпанель

Главная страница для владельца и администраторов: выручка и сессии за период, занятость ПК, последние события. Кассир и оператор её не видят.

Все даты и отчёты «за сегодня» считаются в часовом поясе клуба (Настройки → Настройка клуба → Часовой пояс).

Панель

Касса и смены

Смена

1. «Открыть смену» — укажите начальный остаток в кассе.
2. В течение смены проводите продажи, пополнения и гостевые сессии — всё попадает в смену.
3. «X-отчёт» — промежуточный отчёт без закрытия смены.
4. «Закрыть смену · Z-отчёт» — итог смены и закрытие.

В X- и Z-отчёте видно: приход по видам (продажа товаров, пополнение балансов, гостевые сессии, прочее), проданные товары с количеством и суммой, кто из сотрудников сколько провёл. Отчёт и чек печатаются на 80-мм термопринтер (например, Xprinter) через обычную печать браузера.

Продажа товаров

Выберите товары (с фото и остатком), способ оплаты — наличные, карта или QR-код — и нажмите «Оформить заказ · Оплатить». Товар списывается со склада, продажа попадает в смену.

Пополнение баланса

Найдите клиента по имени или телефону, укажите сумму и способ оплаты, выберите счёт — основной или бонусный. Пополнение видно клиенту в агенте сразу после нажатия «Обновить» или в течение 20 секунд.

Панель

Зоны и карта клуба

Карта показывает зал как он есть: зоны и ПК на своих местах. Цвет ПК — его состояние: свободен, идёт сессия, бронь, не в сети, обслуживание (пунктир — сотрудник на ПК).

Редактор (владелец, админ, менеджер)

• Добавить зону, изменить её название, описание, вместимость, цену часа, иконку и цвет. Диван можно повернуть.
• Перетаскивать зоны и ПК мышью — положение сохраняется.
• Добавить ПК в зону вручную или дождаться, пока агент зарегистрирует ПК сам (он попадёт в зону «Не назначена»).
• Карандаш на ПК — изменить номер, название, MAC-адрес, зону. Там же кнопка «Удалить ПК».

Панель управления выбранными ПК

Выделите один или несколько ПК — снизу появится панель: «Включить», «Перезагрузить», «Выключить», «Бронь» (с выбором клиента и периода) и «Подключить тариф» для гостя.

Щелчок по ПК открывает карточку: статус, клиент и остаток времени, железо (MAC, IP, процессор, память, видеокарта, Windows), кто из сотрудников обслуживает ПК.

Панель

Гостевой режим

Для клиента без аккаунта: кассир выделяет ПК на карте, нажимает «Подключить тариф», выбирает тариф или число минут и способ оплаты. Деньги попадают в открытую смену, а агент на ПК открывается без входа и показывает остаток времени.

• Включается в Настройки → Гости → «Включить гостевой режим». Если выключить, кнопки «Подключить тариф» не будет.
• Гостевое время сбрасывается после перезагрузки ПК или выхода из учётной записи Windows.
• Поминутно гостю можно продать только в зоне, где задана цена часа.

Панель

Брони

Бронь — ПК, закреплённый за клиентом на период. Создаётся на странице «Брони» или с карты (кнопка «Бронь» у выбранных ПК).

• Клиент выбирается из пользователей клуба, период — дата и время начала и конца.
• Между бронями соблюдается интервал из настроек клуба («Интервал между бронированиями»).
• Пока бронь не началась, ПК можно продать, но только на время до начала брони.
• Когда клиент пришёл и начал играть на своём ПК, бронь отмечается как «пришёл». Кнопки «Пришёл» и «Отменить» есть в списке броней.

Панель

Заказы

Сюда приходят заказы из магазина в агенте. Клиент выбирает товары на ПК и платит с основного счёта, товар сразу списывается со склада.

• Число новых заказов видно на пункте меню «Заказы» и в колокольчике. Страница обновляется сама каждые 15 секунд.
• В карточке заказа: номер ПК, клиент, время, состав и сумма.
• «Выдан» — отнесли заказ к ПК. Фиксируется, кто и когда.
• «Отменить» — деньги возвращаются на основной счёт клиента, товар — на склад. Клиент видит возврат в «Истории».

Магазин в агенте включается в Настройки → Настройка клуба → «Включить магазин в агенте».

Панель

Чат и To Do

Чат

Клиент пишет из раздела «Помощь» в агенте. Сообщение приходит в «Чат» с номером ПК. Отвечают кассиры и операторы; владелец и администраторы читают переписку. Непрочитанные видны на пункте меню и в колокольчике.

To Do

Общий список задач на день. Задачу добавляют владелец, админ и менеджер; отметить выполненной может любой сотрудник — у остальных она тоже станет выполненной. Невыполненные задачи переносятся на следующий день.

Панель

Пользователи и работники

Пользователи (клиенты)

• «Добавить клиента»: имя, телефон, пароль, email (необязательно). Владелец и админ задают также скидку и баланс.
• «Изменить» — имя, email и другие данные. «Сбросить пароль» — новый пароль придёт клиенту в Telegram, если он привязал бота Zafiro, иначе покажется на экране один раз.
• Клиент может зарегистрироваться и сам — прямо на ПК в окне входа агента.

Работники

• Добавить можно уже зарегистрированного пользователя (по телефону) или отправить ссылку-приглашение с ролью.
• «Убрать» — аккаунт перестаёт быть сотрудником и остаётся клиентом клуба.
• Лимит сотрудников на смене: Настройки → Настройка клуба → «Сколько кассиров/операторов может быть на смене». На смене — значит вошёл в панель. Следующий войдёт, когда кто-то выйдет или после 2 часов без действий. 0 — без ограничения.

Панель

Склад

• Товары: название, артикул, категория, цена, остаток, фото. Фото показывается в кассе и в магазине агента.
• Категории склада — те же, что видит клиент в магазине агента.
• Оприходование — приход товара, списание — расход. Каждое движение остаётся в истории с сотрудником и остатком после операции.
• Кассир и оператор видят остатки и могут оприходовать товар; создавать и менять товары могут владелец, админ и менеджер.

Панель

Тарифы

Тариф — пакет игрового времени, который клиент покупает в агенте сам или которое продаёт кассир.

Поминутная оплата

Если у зоны задана цена часа, клиент в агенте может купить любое число минут (1–720) по цене часа / 60. Без цены часа в зоне продаются только тарифы. Цены часа меняются в блоке «Поминутная оплата по зонам» на странице тарифов.

Панель

Список ПК и логи

Список ПК

Таблица всех ПК клуба: номер, зона, статус, версия агента, железо, IP, последний сигнал. Если на части ПК стоит старая версия агента, сверху появляется уведомление с кнопкой «Скачать установщик».

Логи

Журнал действий клуба: кто, когда и с какого IP что сделал — продажи, пополнения, изменения настроек и тарифов, вход сотрудников на ПК, удаление ПК, заказы и т.д. Фильтры по событию, сотруднику, дате и тексту.

Панель

Новости, подписка, уведомления

• Новости — новости клуба с картинкой. Показываются клиентам на главной в агенте (вторая карточка; первая — новости Zafiro).
• Подписка — тариф Zafiro, срок пробного периода и оплата. При неактивной подписке агент и API клуба не работают.
• Колокольчик — новые заказы, непрочитанные сообщения чата, мало товара на складе, ПК не в сети, неудачные входы и важные изменения.

Панель

Настройки клуба

Настройка клуба

На этой же странице:

• Ключ установки клуба — для подключения агента. Виден целиком владельцу и админу, кнопка «Копировать».
• Логотип клуба — PNG или JPG до 1 МБ, показывается на заблокированных мониторах.
• Часовой пояс — для всех дат и отчётов.
• PIN-код для выхода из агента — 4–8 цифр. Без PIN закрыть агент на ПК нельзя.
• Время обслуживания ПК — сколько минут сотрудник может работать на ПК после выхода по PIN (по умолчанию 15).

Языки

Какие языки доступны в агенте (русский, казахский, английский) и язык клуба по умолчанию. Клиент меняет язык в агенте сам, после его выхода возвращается язык клуба.

Финансы

Валюта клуба: KZT, RUB или $.

Гости

API и интеграции

Ключи API, вебхуки и журнал запросов. Подробнее — в разделе API и вебхуки.

Агент на ПК

Установка и обновление

Первая установка

1. Скачайте установщикZafiroAgentSetup.exe — один файл для Windows 10/11, ничего дополнительно ставить не нужно.
2. Запустите от имени администратораОтметьте нужные пункты: «Защитить учётную запись клиента», «Значок на рабочем столе», «Запускать агент и под администратором» (если ПК входит в Windows под администратором).
3. Подключите ПКВ окне агента введите ключ установки, телефон и пароль сотрудника. Кнопка «Свернуть, чтобы скопировать ключ» сворачивает окно, чтобы открыть панель и скопировать ключ.
4. ГотовоПК появляется на карте. Сотрудник выходит, агент показывает экран входа для клиентов.

Что ставит установщик

• Агент в C:\Program Files\Zafiro Agent — клиент не может подменить файл.
• Службу Windows Zafiro Agent: хранит токен ПК, раз в минуту отмечает ПК «в сети», запускает агент при входе в Windows и снова, если его закрыли или он завис.
• Защиту учётной записи клиента (по умолчанию Client): без диспетчера задач, редактора реестра, командной строки, PowerShell, «Выполнить», панели управления, Game Bar. Другое имя учётной записи: ZafiroAgentSetup.exe /CLIENTUSER=Имя.
• Значок Zafiro Agent на рабочем столе и в меню «Пуск».

Обновление

Скачайте новый установщик и запустите его от имени администратора. Установщик сам находит установленную версию и показывает кнопку «Обновить». Настройки, ключ клуба и токен ПК сохраняются. Задачи в Планировщике Windows для автозапуска не нужны — удалите их, если создавали.

Агент на ПК

Бездисковые клубы

1. Включите на сервере бездисковой загрузки режим обновления образа и загрузите один ПК (суперклиент).
2. Установите агент и подключите этот ПК ключом установки.
3. Сохраните образ и перезагрузите ПК клуба.

После загрузки служба на каждом ПК сама получает токен по ключу клуба и UUID материнской платы. Незнакомый ПК автоматически добавляется в зону «Не назначена» — разложите ПК по зонам на карте. Клон с чужим MAC-адресом не получит токен другого ПК.

Обновление агента в бездисковом клубе — один раз в образе суперклиента: выйдите из агента по PIN (Ctrl+Alt+P), запустите установщик, сохраните образ.

Агент на ПК

Агент глазами клиента

Вход

• По телефону в формате +7 700 123-45-67 и паролю. Рядом с паролем — текущий язык ввода (РУС/ENG/ҚАЗ), по нажатию переключается.
• По QR-коду, если клуб включил его: клиент сканирует код телефоном, входит на сайте и подтверждает.
• «Нет аккаунта? Зарегистрироваться» — имя, телефон и пароль прямо на ПК.
• Один клиент — один ПК: войти на втором ПК нельзя, пока не выйдешь на первом. Если ПК выключили без выхода, через 2 минуты вход освобождается.

Разделы

Кнопки справа

• На рабочий стол — свернуть агент и играть (только при оплаченной сессии).
• Выбрать тариф / Продлить сессию.
• Пересесть — перенести остаток на свободный ПК на карте клуба (если включено).
• Выйти / Завершить сессию — с подтверждением. Оставшееся время при завершении не возвращается.

Ошибки и предупреждения появляются всплывающими сообщениями: красные — ошибка, жёлтые — предупреждение, зелёные — успех.

Агент на ПК

Сотрудник на ПК

• Ctrl+Alt+P — выход из агента по PIN-коду клуба. PIN проверяется на сервере, поэтому ПК должен быть в сети.
• После выхода служба не запускает агент «время обслуживания» (по умолчанию 15 минут) или до выхода из Windows. На карте ПК отмечен пунктиром, в карточке видно, кто его обслуживает.
• В учётных записях администраторов Windows агент сам не запускается, если при установке не выбран пункт «Запускать агент и под администратором».
• Сотрудник может войти в агент своим аккаунтом: вход отмечается на карте как обслуживание.

Справка

Решение проблем

Где логи на ПК

Файлы agent-ГГГГММДД.log, хранятся 7 дней. Пароли и токены в логи не пишутся.

• Агент: %LOCALAPPDATA%\ZafiroAgent\logs той учётной записи, под которой он работал (например, C:\Users\Client\AppData\Local\ZafiroAgent\logs).
• Служба: C:\Windows\System32\config\systemprofile\AppData\Local\ZafiroAgent\logs (открывать от администратора).

Присылайте в поддержку строки за минуту вокруг проблемы — особенно с метками [Service], [Watchdog], [Vault], [Kiosk].

Справка

API и вебхуки

Для интеграции со своими сервисами: сайтом бронирования, ботом, учётной системой. Полное описание методов — на zafiro.kz/docs/api (там же OpenAPI-файл).

Ключи

• Создаются в Настройки → API и интеграции. Доступ — владелец и сотрудники, которым владелец дал право.
• Ключ показывается один раз. Можно ограничить права, IP-адреса, лимит запросов и срок действия, перевыпустить или отозвать.
• Клуб определяется только по ключу.

curl https://zafiro.kz/api/v1/products \
  -H "Authorization: Bearer zfk_xxxxxxxx_..." \
  -H "Accept: application/json"

Права

Правила

• Лимиты: 120 запросов в минуту на ключ (можно изменить), 600 на клуб; тело запроса до 256 КБ.
• Запись склада и управление питанием требуют заголовок Idempotency-Key — повтор с тем же ключом не выполнит операцию дважды.
• Перезагрузка и выключение не применяются к ПК с идущей сессией (ответ 409), не больше 50 ПК за вызов.

Вебхуки

События: product.created, product.updated, stock.changed, sale.completed, computer.reservation_changed, computer.controlled. Подпись в заголовке X-Zafiro-Signature: v1=hex(HMAC-SHA256(secret, "{timestamp}.{body}")), также X-Zafiro-Timestamp и X-Zafiro-Delivery. Повторы через 10 с, 1 мин, 5 мин, 30 мин и 2 ч; после 20 неудачных доставок подряд адрес отключается. Принимаются только https-адреса с публичным IP.

Справка

Частые вопросы

Что будет, если пропадёт интернет?

Оплаченная сессия продолжается. Агент переподключится к серверу, когда связь вернётся. Покупки, вход и выход по PIN без интернета не работают.

Может ли клиент закрыть агент?

Нет. Агент работает со службой Windows, закрывается только по PIN-коду сотрудника, а закрытый или зависший агент служба запускает снова.

Как вернуть клиенту деньги за заказ?

Заказы → карточка заказа → «Отменить». Деньги вернутся на основной счёт, товар — на склад.

Клиент забыл пароль

Пользователи → «Сбросить пароль». Если клиент привязал Telegram в профиле агента, новый пароль придёт туда.

Можно ли работать с несколькими клубами?

Да. Один аккаунт может состоять в нескольких клубах; клуб переключается в панели. Данные клубов не смешиваются.

На каких языках работает Zafiro?

Панель и агент — на русском, казахском и английском.