> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.qfapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ECR HTTPS 整合設定

本指南說明如何設定 **基於 HTTPS 的 ECR（電子收銀機）整合**，涉及以下組件：

* QFPay POS（Haojin App）
* 客戶端裝置（例如收銀 Web App）
* 商戶後端伺服器（用於接收通知，可選）

***

## 整合流程概覽

HTTPS ECR 整合涉及以下幾個部分：

1. **商戶平台（MMS）** → 開啟 HTTPS 模式
2. **POS 裝置（Haojin App）** → 同步並驗證 HTTPS 狀態
3. **客戶端裝置** → 安裝憑證並發送 HTTPS 請求
4. *(選用)* 商戶後端 → 接收交易通知

***

## 1. 在商戶平台（MMS）啟用 HTTPS

前往：\
[商戶後台 - POS 設定](https://merchant.qfpay.global/main/devicePosMSetting)

路徑：\
`Settings` → `Device Setting` → 搜尋 `POS Key List`

* 開啟 **HTTPS**
* 儲存設定

<img src="https://mintcdn.com/qfpay-8e347952/9MJbaQfNfV-8TI7A/images/in-store/ecr-device-posm-settings.png?fit=max&auto=format&n=9MJbaQfNfV-8TI7A&q=85&s=460942d67009924f0d1921094bd027e5" alt="Ecr Device Posm Settings" width="2662" height="940" data-path="images/in-store/ecr-device-posm-settings.png" />

***

## 2. 在 POS（Haojin App）驗證 HTTPS 狀態

啟用後：

* 重新啟動或重新登入 Haojin App
* 設定會自動同步至 POS

檢查位置：

`Settings` → `ECR Status`

確認：

* HTTPS 已**啟用**
* 憑證已**自動產生**

<Warning>
  最低支援版本：**4.34.12**
</Warning>

<img src="https://mintcdn.com/qfpay-8e347952/9MJbaQfNfV-8TI7A/images/in-store/ecr-pos_https_status.png?fit=max&auto=format&n=9MJbaQfNfV-8TI7A&q=85&s=16b9af88fd46c44f3e3e1edcc19defdf" style={{ width: '300px' }} alt="Ecr Pos Https Status" width="878" height="1074" data-path="images/in-store/ecr-pos_https_status.png" />

***

## 3. 設定客戶端裝置（收銀 / Web App）

客戶端裝置需信任 POS 的 HTTPS 憑證。

### 安裝 CA 憑證

下載並安裝： `ca3.crt`

驗證指紋：

```text theme={null}
SHA-256=9C 0F A4 04 C5 9F D7 A2 7E A3 1F 6B 96 F4 74 01 1B 3F 86 8A A0 84 61 47 4D 75 69 ED 63 0D 32 C3 
SHA-1=A7 4C AD CE D7 21 AD CB 77 C8 F6 47 6C 19 E6 C6 4E 0E 6A 61
```

### 安裝說明

* **Android**：安裝至受信任憑證
* **Windows**：\
  `控制台 → 憑證 → 受信任的根憑證授權單位`

***

## 4. 設定商戶後端（非同步通知）

如需接收交易狀態更新，需設定後端通知。

### 設定方式

請聯絡 QFPay 技術支援：

[technical.support@qfpay.com](mailto:technical.support@qfpay.com)

提供以下資訊：

* 商戶 ID
* 門店 ID
* 通知 URL

參考文件： [簽名生成](/zh-hant/integration/preparation/authentication-and-signature).

***

## 設定檢查清單

上線前請確認：

* MMS 已啟用 HTTPS
* POS 顯示 HTTPS 已啟用且憑證已生成
* 客戶端已正確安裝 CA 憑證
* 憑證指紋與 `ca3.crt` 一致
* 客戶端設定正確：
  * POS IP 位址
  * 密鑰 / 憑證
* 已設定 Webhook / 通知 URL

***

## Odoo 整合範例

參考：\
[https://www.odoo.com/documentation/19.0/applications/sales/point\_of\_sale/payment\_methods/terminals/qfpay.html](https://www.odoo.com/documentation/19.0/applications/sales/point_of_sale/payment_methods/terminals/qfpay.html)

範例：

商戶網址：

```text theme={null}
shop-abc.odoo.com
```

通知 URL：

```text theme={null}
https://shop-abc.odoo.com/qfpay/notify
```

***

## 疑難排解

### 連線問題

1. 檢查 POS → `ECR Status` 是否正常運作
2. 使用瀏覽器或 `curl` 測試連線
3. 重新啟動 POS 應用程式
4. 嘗試其他 POS 裝置
5. 檢查網路限制：
   * Wi-Fi 隔離
   * 路由器防火牆

***

### 固定 IP 問題

如連線不穩定：

1. 設定路由器 DHCP
2. 綁定 POS MAC 位址
3. 確保客戶端使用固定 IP

***

## 常見問題

<Warning>
  * 未安裝 CA 憑證 → HTTPS 請求會失敗
  * POS IP 錯誤 → 無法連線
  * MMS 已啟用但 POS 未同步 → 需重新登入
  * 未設定 Webhook → 無法接收交易結果
</Warning>

***

## 總結

完成 HTTPS ECR 設定需：

* 在 MMS 啟用 HTTPS
* 在 POS 驗證狀態
* 在客戶端安裝憑證
* （選用）設定後端通知

完成後，客戶端即可透過 HTTPS 與 POS 安全通訊。