## 核心对象
| 名称 | 定义 |
| ----------------------- | ------------------------------------------------------------ |
| 开发者 / `vendor` | 对接收钱吧API的主体，通常是品牌商户或系统开发团队，持有`vendor_sn`和`vendor_key` |
| 应用 / `app` | 开发者在收钱吧创建的具体应用，使用`app_id`标识 |
| 商户 / `merchant` | 在收钱吧入网的独立收款主体 |
| 门店 / `store` | 商户登记的经营单元，激活码和终端最终归属到门店 |
| 激活码 / `code` | 在指定门店下生成，用于把商户设备绑定到该门店并创建收钱吧终端 |
| 商户设备 | 实际发起交易的收银机、服务器实例或其他业务设备，使用`device_id`标识 |
| 收钱吧终端 / `terminal` | 实际调用支付、查询和退款接口的主体，持有`terminal_sn`和`terminal_key` |
## 商户、门店、设备和终端的关系
```text
商户
└── 门店
├── 商户设备A（device_id A）↔ 收钱吧终端A
├── 商户设备B（device_id B）↔ 收钱吧终端B
└── 商户设备C（device_id C）↔ 收钱吧终端C
```
| 上级对象 | 下级对象 | 关系 |
| ---------- | ---------- | ----------------------------------------------------------- |
| 商户 | 门店 | 一个商户可以包含多个门店，每个门店只归属于一个商户 |
| 门店 | 终端 | 一个门店可以生成多个终端，每个终端只归属于一个门店 |
| 商户设备 | 收钱吧终端 | 每台设备通过全局唯一的`device_id`与一个终端建立一一对应关系 |
| 门店激活码 | 设备和终端 | 激活码把设备绑定到发放该激活码的门店，并在该门店下生成终端 |
## 终端如何生成
```text
vendor_sn + vendor_key
+
app_id + 门店激活码 + 全局唯一device_id
↓ 调用激活接口
terminal_sn + terminal_key
```
开发者参数用于证明谁在创建终端，`app_id`说明终端属于哪个应用，激活码决定终端归属哪个门店，`device_id`决定终端对应哪台商户设备。
## 参数在什么阶段使用
| 参数 | 所属对象 | 使用阶段 | 作用 |
| -------------- | ---------- | -------------------- | -------------------------------- |
| `vendor_sn` | 开发者 | 激活时 | 激活接口的签名序列号 |
| `vendor_key` | 开发者 | 激活时 | 激活接口的签名密钥 |
| `app_id` | 应用 | 激活时 | 标识终端所属应用 |
| `code` | 门店 | 激活时 | 将设备绑定到目标门店 |
| `device_id` | 商户设备 | 激活、签到和设备识别 | 标识实际设备，必须稳定且全局唯一 |
| `terminal_sn` | 收钱吧终端 | 激活后 | 支付、查询、退款和签到的终端标识 |
| `terminal_key` | 收钱吧终端 | 激活后 | 支付、查询、退款和签到的签名密钥 |
## 必须遵守的规则
- 门店必须归属于商户，终端必须归属于门店。
- 同一门店有多台设备时，每台设备使用独立的`device_id`激活并保存自己的终端参数。
- `device_id`不得在不同应用、门店或设备之间重复。
- 一台设备正常情况下只激活一次，后续继续使用已保存的终端参数。
- 签到返回新`terminal_key`后，应使用新密钥替换旧密钥。
- 不要使用`vendor_key`代替`terminal_key`调用支付、查询或退款接口。
收钱吧开放平台