POS 集成

集成设置页面用于把符合条件的 HandyCafe 服务端连接到 Ödeal D2D 终端。可用性通过 HandyCafe Cloud 检查。当网咖无权使用 Ödeal 时，该菜单和页面会完全隐藏。

开始之前

您需要一个有效的 HandyCafe Cloud 订阅、一个 Ödeal 商户密钥和一个 Ödeal 私密密钥。您还必须在 Ödeal 的 Cihazlarım 区域中创建该终端。分配给该终端的名称就是它的 externalDeviceKey。请先从 Stage（测试）环境开始。只有在 Ödeal 审核通过生产环境的凭据和回调配置之后，才切换到 Production 环境。

配置 Ödeal

打开设置并选择集成。
在 Ödeal 账户中输入 Ödeal 提供的商户密钥和私密密钥。HandyCafe 会把这些值直接发送到 HandyCafe Cloud。它们经过加密保存，不会存入本地数据库，也不会再次显示。
选择连接测试。当存在新密钥时，HandyCafe 会先安全保存它们，再测试 Ödeal API 连接。此测试只验证 Ödeal 账户，并不能证明终端已经配对或在线。
添加终端。输入一个清晰的本地设备名称。在 **Ödeal 设备名称（externalDeviceKey）**中，填写在 Ödeal 中创建的设备名称，必须完全一致。然后填写可选的 PaxID、环境、支付等待时间、顾客所在城市、顾客所在区县、会话增值税率和订单增值税率。
启用 POS 集成已激活，然后选择保存。
在 Stage 环境中完成一笔现金小票和一笔刷卡支付，以验证终端配对和两条结算路径。

本版本每台服务端只支持一个处于激活状态的 Ödeal 终端。这样可以避免在收银员终端选择器推出之前，支付被路由到非预期的终端。

在 Cloud 验证新的凭据组合之前，HandyCafe 会先把终端清单保存在本地。Ödeal 拒绝凭据不会丢弃终端名称或配对字段。需要新凭据的终端会以未激活状态保存，直到这些凭据在它所选的环境中通过验证。

集成页面直接从本地 SQLite 数据库读取终端清单并显示，无需等待 Cloud。只有加密凭据状态和远程服务商权限需要向 Cloud 发起请求。

如果 Ödeal 拒绝了配置，HandyCafe 会显示 Ödeal 返回的说明。返回“未找到组织资料”表示该商户密钥与私密密钥的组合不属于所选 Stage 或 Production 环境中的任何组织。

支付行为

当激活的支付方式为现金或刷卡时，PC 会话结算、主机会话结算和独立订单结算都会向 Ödeal 发送一个幂等的购物篮。现金按 Ödeal 文档中定义的 CASH 支付选项发送。终端会记录这笔现金付款，并打印税务小票或电子归档收据，不会打开刷卡收款界面。刷卡按 CREDITCARD 发送；顾客在终端上完成支付期间，HandyCafe 会等待回调结果。同时包含现金和刷卡的结算会发送这两个支付选项及各自的金额。

当银行卡和商户协议均支持时，顾客可以在终端上选择分期方案。HandyCafe 会把上报的分期数与本地销售记录一并保存。只有在 Ödeal 确认交易之后，本地销售记录才会提交。如果确认之后本地提交失败，HandyCafe 会请求当日撤销。撤销失败会产生一条人工对账错误，必须在 Ödeal 交易报表中核查。现金和刷卡以外的支付方式类型仍按 HandyCafe 现有的结算流程处理。

测试与终端操作

连接测试只验证 Ödeal 商户凭据和 API 访问权限。它不会打印小票，不会扣款，也不能证明 externalDeviceKey 已经与终端配对。

所提供的 D2D API 文档没有定义单独的打印测试小票或测试扣款接口。验收测试使用 Stage 环境中的正常购物篮：先发送一个现金购物篮并核对打印出的小票，再发送一个刷卡购物篮，并在终端上完成一笔一次性付款或分期交易。只能使用 Ödeal 提供的 Stage 测试卡信息。

Ödeal 的验收用例包含日结和补打上一张小票，但这些属于终端操作。D2D 没有为它们提供远程 API 调用的文档，因此 HandyCafe 不会把它们做成远程按钮。

远程启用与停用

HandyCafe 管理员在仪表板的管理 > 管理设置 > POS 服务商中控制 Ödeal。全局开关是总开关。国家/地区默认值使用两位 ISO 代码，例如 TR。网咖级别的控制可以为某一个许可证明确开启或关闭 Ödeal。针对单个网咖的决定优先于国家/地区默认值。重置该网咖的决定之后，它会重新跟随所在国家/地区的设置。

决策顺序依次是全局开关、网咖级决定、国家/地区默认值。全局开关关闭会对所有网咖关闭 Ödeal。明确关闭某个网咖会隐藏页面，即使它所在的国家/地区是开启的。明确开启某个网咖会允许显示页面，即使它所在的国家/地区不在默认列表中。关闭访问权限会立即阻止创建新的购物篮。已有的待处理交易仍然可以查询或取消，以免进行中的支付被卡住。

服务端通过 HandyCafe Cloud 检查可用性，并缓存最后一次成功验证的国家/地区与网咖决定。当服务商目录的凭据无效时，它会返回 HTTP 200 并带上结构化的 error.code。桌面端收到该响应后会刷新凭据并重试。临时的认证或网络故障不会把管理员已启用的决定误判为停用，因此集成菜单保持稳定。之后一次成功的响应会立即更新缓存，包括管理员的停用决定。如果此前没有已验证的决定，未知的网咖国家/地区、未激活的订阅或已停用的服务商都会让页面保持隐藏。即使使用了缓存的可见性，新的 Ödeal 操作也始终会再次由 Cloud 授权。当同步过来的网咖资料中没有国家/地区时，则使用许可证上保存的国家/地区。

安全与恢复

Ödeal 凭据在 HandyCafe Cloud 中使用部署保险库密钥加密。回调请求通过配置的请求密钥，或通过 Ödeal 商户与私密密钥请求头进行认证。购物篮参考码对每一笔订单或会话保持不变。重复同一次结算不会产生第二笔扣款。

Ödeal 撤销只在 Ödeal 的当日规则下、并且在终端批次结算之前可用。待处理的购物篮可以在支付完成前单独删除。Ödeal D2D 不提供通用的退款操作。当撤销的时间窗口已过时，请使用 Ödeal 后台和交易报表处理。

Ödeal D2D 没有提供文档化的远程 Z 报表或日结操作。请在终端上完成日结。HandyCafe 可以读取交易报表用于对账，并记录来自 Ödeal 的 payback 回调。