Интеграции с POS

Страница настроек Интеграции подключает подходящий сервер HandyCafe к терминалу Ödeal D2D. Доступность проверяется через HandyCafe Cloud. Если кафе не имеет права работать с Ödeal, пункт меню и сама страница полностью скрыты.

Прежде чем начать

Вам понадобятся действующая подписка HandyCafe Cloud, ключ продавца Ödeal и секретный ключ Ödeal. Кроме того, терминал нужно создать в разделе Ödeal Cihazlarım. Точное имя, присвоенное этому терминалу, и есть его externalDeviceKey. Начните со среды Stage. Переходите на Production только после того, как Ödeal утвердит рабочие учетные данные и настройку обратных вызовов.

Настройка Ödeal

1. Откройте Настройки и выберите Интеграции.
2. В блоке Учетная запись Ödeal введите ключ продавца и секретный ключ, выданные Ödeal. HandyCafe передает эти значения напрямую в HandyCafe Cloud. Там они шифруются, не сохраняются в локальной базе данных и больше нигде не показываются.
3. Выберите Проверка соединения. Если введены новые ключи, HandyCafe сначала безопасно сохраняет их, а затем проверяет соединение с API Ödeal. Эта проверка подтверждает только саму учетную запись Ödeal. Она не доказывает, что терминал привязан и находится в сети.
4. Добавьте терминал. Укажите понятное локальное имя устройства. В поле Имя устройства в Ödeal (externalDeviceKey) введите точное имя устройства, созданного в Ödeal. Затем заполните необязательный PaxID, среду, время ожидания оплаты, город и район клиента, ставку НДС для сессий и ставку НДС для заказов.
5. Включите параметр Интеграция POS активна и выберите Сохранить.
6. Проведите в среде Stage один чек за наличные и один платеж картой, чтобы проверить привязку терминала и оба сценария расчетов.

В этом выпуске поддерживается только один активный терминал Ödeal на сервер. Так платеж не уйдет на посторонний терминал, пока в интерфейсе кассира нет выбора терминала.

HandyCafe сохраняет список терминалов локально еще до того, как облако проверит новую пару учетных данных. Отклонение учетных данных Ödeal не стирает имя терминала и поля привязки. Терминал, которому нужны новые учетные данные, хранится как неактивный, пока эти данные не пройдут проверку в выбранной для него среде.

Страница «Интеграции» читает список терминалов напрямую из локальной базы SQLite и показывает его, не дожидаясь ответа облака. Обращение к облаку требуется только для статуса зашифрованных учетных данных и для разрешения на провайдера, которое задается удаленно.

Если Ödeal отклоняет конфигурацию, HandyCafe показывает пояснение, полученное от Ödeal. Ответ о том, что профиль организации не найден, означает, что пара из ключа продавца и секретного ключа не принадлежит ни одной организации в выбранной среде Stage или Production.

Как проходит оплата

Если активным способом оплаты выбраны наличные или карта, закрытие сессии на ПК, закрытие сессии на консоли и закрытие отдельного заказа отправляют в Ödeal идемпотентную корзину. Наличные передаются с документированным вариантом оплаты CASH. Терминал фиксирует оплату наличными и печатает фискальный чек или электронный чек e-Arşiv, не открывая экран приема карты. Карта передается как CREDITCARD, и HandyCafe ждет результат обратного вызова, пока клиент завершает оплату на терминале. Если в расчете есть и наличные, и карта, отправляются оба варианта оплаты с соответствующими суммами.

Клиент может выбрать на терминале рассрочку, когда ее поддерживают карта и договор с продавцом. HandyCafe сохраняет вместе с локальной продажей количество платежей рассрочки, полученное от терминала. Локальная продажа фиксируется только после того, как Ödeal подтвердит транзакцию. Если после подтверждения локальная запись не сохранилась, HandyCafe запрашивает отмену в тот же день. Неудачная отмена приводит к ошибке ручной сверки, и такой платеж нужно проверить в отчете о транзакциях Ödeal. Способы оплаты, отличные от наличных и карты, обрабатываются обычным механизмом расчетов HandyCafe.

Тесты и операции на терминале

Проверка соединения подтверждает только учетные данные продавца Ödeal и доступ к API. Она не печатает чек, не списывает средства с карты и не доказывает, что externalDeviceKey привязан к терминалу.

Предоставленная документация по API D2D не описывает отдельных методов Печать тестового чека или Тестовое списание. Приемочное тестирование выполняется обычными корзинами в среде Stage: отправьте корзину с оплатой наличными и проверьте напечатанный чек, затем отправьте корзину с оплатой картой и проведите на терминале операцию единым платежом или в рассрочку. Используйте только тестовые карты, предоставленные Ödeal для среды Stage.

Приемочные сценарии Ödeal включают закрытие дня и повторную печать последнего чека, но это операции на самом терминале. В D2D нет документированных удаленных вызовов API для них, поэтому HandyCafe не выводит для них отдельные кнопки.

Удаленное включение и отключение

Администраторы HandyCafe управляют Ödeal в панели управления, в разделе Администратор > Настройки > POS providers. Общий переключатель служит главным элементом управления. Значения по умолчанию для стран задаются двухбуквенными кодами ISO, например TR. Настройки на уровне кафе позволяют явно открыть или закрыть Ödeal для одной лицензии. Решение по конкретному кафе имеет приоритет над значением по умолчанию для страны. Сброс решения по кафе возвращает это кафе к правилу его страны.

Решение принимается в таком порядке: общий переключатель, затем решение по конкретному кафе, затем значение по умолчанию для страны. Выключенный общий переключатель закрывает Ödeal для всех кафе. Явный запрет для кафе скрывает страницу, даже если его страна открыта. Явное разрешение для кафе открывает страницу, даже если его страны нет в списке по умолчанию. Отключение доступа сразу блокирует создание новых корзин. Уже созданные незавершенные транзакции по-прежнему можно проверить или отменить, чтобы платеж в процессе не завис.

Сервер проверяет доступность через HandyCafe Cloud и кэширует последнее успешно подтвержденное решение по стране и по кафе. Когда учетные данные каталога провайдеров недействительны, каталог возвращает HTTP 200 со структурированным полем error.code. Настольное приложение обрабатывает такой ответ обновлением учетных данных и повторной попыткой. Временный сбой аутентификации или сети не превращает включенное решение администратора в отключенное, поэтому пункт меню «Интеграции» остается стабильным. Успешный последующий ответ сразу обновляет кэш, в том числе решение администратора об отключении. Если ранее подтвержденного решения нет, страница остается скрытой при неизвестной стране кафе, неактивной подписке или отключенном провайдере. Новые операции Ödeal всегда заново авторизуются облаком, даже когда используется кэшированная видимость. Если у синхронизированного профиля кафе нет страны, используется страна, сохраненная в лицензии.

Безопасность и восстановление

Учетные данные Ödeal шифруются в HandyCafe Cloud ключом хранилища развертывания. Запросы обратного вызова аутентифицируются настроенным ключом запроса либо заголовками с ключом продавца и секретным ключом Ödeal. Ссылочный код корзины остается одинаковым для каждого заказа или сессии. Повторное проведение того же расчета не создает второе списание.

Отмена в Ödeal доступна только по правилам Ödeal в тот же день, до закрытия пакета транзакций на терминале. Незавершенную корзину можно удалить отдельно, пока оплата не завершена. В Ödeal D2D нет общей операции возврата средств. Если окно отмены уже закрылось, используйте бэк-офис Ödeal и отчет о транзакциях.

В Ödeal D2D нет документированной удаленной операции Z-отчета или закрытия дня. Закрывайте день на терминале. HandyCafe может читать отчеты о транзакциях для сверки и записывает обратные вызовы о выплатах от Ödeal.