Skip to content

F
FMVIPAPI
Commit e1d6beff by NitefullWind
Options

添加1.2.1和2.0.0版本文档

parent b111e6a9
Showing with 1084 additions and 0 deletions
非码会员客户端与POS对接文档 V1.2.1.md 0 → 100644
# 非码会员客户端与POS对接文档 V1.2.1
# 非码会员客户端与POS对接文档 V1.2.1
版本 | 修订时间 | 修订说明
---|---|---
V1.0 | 2017-04-07 | 创建
V1.1 | 2017-05-12 | 1.认证接口返回更多会员信息。2.增加接口请求类型、错误信息、支付类型对照表。
V1.2 | 2017-06-08 | 与扫码支付接口合并
v1.2.1 | 2017-08-14 | 1.增加接口描述信息。 2.修正几个字段名称
##目录：
[TOC]
## 对接须知
**会员客户端只响应带有固定格式消息头的请求数据，请求数据处理规则如下：**
- 将名为 FMSOCKHEADER 结构体类型的消息头添加到原始请求数据(即下文所有定义格式的请求数据)的开头，将新生成的数据作为请求数据发送给会员客户端。
- FMSOCKHEADER 结构体声明如下：
```cpp
typedef struct {
unsigned int flag; // 固定值 0x4d46
unsigned int ver; // 固定值 0x2
unsigned int len; // 原始请求数据的数据长度
}FMSOCKHEADER;
```
- 代码示例
```cpp
// eg：
// 获得POS生成的JSON格式请求数据
char *originData = posReqJson.data(); // 获得原始数据
int originLen = posReqJson.length(); //获得原始数据长度
// 设置消息头的值
FMSOCKHEADER header = {0, 0, 0};
header.flag = 0x4d46;
header.len = originLen;
header.ver = 0x2;
// 声明一个新的数据指针
char* newReqData = new char[originLen + sizeof(FMSOCKHEADER)];
memset(newReqData, 0, originLen + sizeof(FMSOCKHEADER));
memcpy(newReqData, &header, sizeof(FMSOCKHEADER)); // 将消息头拷贝至newReqData
strcat(newReqData, originData); //将原始数据追加到newReqData
// 向会员客户端发送newReqData
```
## 认证接口
如果需要单独进行会员认证功能，请调用该接口。
请求时不需要传入待认证的会员号。
返回会员信息，或者失败信息。
#### 请求参数
字段 | 必选 | 类型 | 说明
---|---|---|---
pos_ver | true | int | 接口版本
operator_id | true | string | 操作员
fm_cmd | true |int | 接口类型(认证:1001)
pos_id | true |string | pos机编号
store_id | true |string | 门店号
business_date | true | string | 营业日
member_sign | false | string | 会员认证身份号,可传入此值进行会员认证
#### 返回参数
字段 | 必选 | 类型 | 说明
---|---|---|---
statusCode | true | string | 是否成功，成功为100，其他为失败
msg | true | string | 失败原因
prompt | true | int | 是否需要pos提示
fm_open_id | true | string | 非码会员唯一标识openid,在其他接口中标识唯一会员
account | true | string | 会员账号,用作展示
amount | true | int | 账户余额(分)
score | true | int | 账户积分(个)
couponList | true | array | 代金券列表
couponList/couponCode | true | string | 代金券券码
couponList/disAmount | true | int | 代金券金额
couponList/desc | true | string | 代金券描述
name | true | string | 姓名
sex | true | string | 性别(男/女)
birthday | true | string | 生日(yyyy-MM-dd)
phone | false | string | 手机号
address | false | string | 通讯地址
email | false | string | 电子邮箱
#### 示例
```json
//会员认证请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 1001,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"member_sign": "12345678"
}
//会员认证返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"fm_open_id":"qweqweqweqweqwe",
"account":"12345678",
"amount": 10000,
"score": 100,
"couponList":[
{
"couponCode":"9980001",
"disAmount":1000,
"desc":"代金券10元"
},
{
"couponCode":"9980002",
"disAmount":2000,
"desc":"20元代金券"
}
],
"name": "非码",
"sex": "男",
"birthday": "1991-01-01",
"phone":"18112341234",
"address":"上海",
"email":"abc@163.com"
}
```
## 充值接口
如果需要实现会员充值功能，请调用该接口。
#### 请求参数
字段 | 必选 | 类型 | 说明
---|---|---|---
pos_ver | true | int | 接口版本
operator_id | true | string | 操作员
fm_cmd | true |int | 接口类型(充值: 1002)
pos_id | true |string | pos机编号
store_id | true |string | 门店号
business_date | true | string | 营业日
recharge_amount | false | string | 充值金额
trans_id | false | string | POS交易号
fm_open_id | false | string | 非码会员唯一标识,如果没有认证过会员则为空
#### 返回参数
字段 | 必选 | 类型 | 说明
---|---|---|---
statusCode | true | string | 是否成功，成功为100，其他为失败
msg | true | string | 失败原因
prompt | true | int | 是否需要pos提示
fm_open_id | true | string | 非码会员唯一标识openid
fm_id | true | string | 非码订单号
amount | true | int | 充值金额
before_amount | false | int | 充值前金额
after_amount | false | int | 充值后金额
discount_amount | false | int | 优惠金额
print | false | string | 打印信息
#### 示例
```json
//会员充值请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 1002,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"recharge_amount": 1270,
"trans_id": "100000010",
"fm_open_id":""
}
//会员充值返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"fm_open_id":"qweqweqweqweqwe",
"fm_id": "sw12313123123123123",
"before_amount": 0,
"after_amount": 5000,
"discount_amount": 0,
"print":"**************"
}
```
## 支付接口
使用非码会员支付、非码支付时，调用该接口。
支付接口同时兼容**会员支付**、**条码支付**
### 会员支付
顾客（仅会员）使用会员码，支付时可使用储值、积分、优惠券等完成订单支付
### 条码支付
顾客（包含会员）使用支付宝、微信等互联网支付平台的条码/二维码进行当面支付
#### 请求参数
字段 | 必选 | 类型 | 说明
---|---|---|---
pos_ver | true | int | 接口版本
operator_id | true | string | 操作员
fm_cmd | true | int | 接口类型(会员支付: 1003；线下扫码支付：10031)
pos_id | true | string | pos机编号
store_id | true | string | 门店号
business_date | true | string | 营业日
trans_id | false | string | POS交易号
fm_id | false | string | 非码订单号,如果一笔订单已经使用过非码会员支付则填上次返回的fm_id，否则为空
fm_open_id | false | string | 非码会员唯一标识,如果没有认证过会员则为空
transaction | true | obj | 交易信息
transaction/order_amount | true | int | 订单总额
transaction/paid_amount | true | int | 已付金额
transaction/undis_amount | true | int | 不可优惠金额
transaction/barcode | false | string | 支付条码
transaction/products | true | array | 商品信息
transaction/products/consume_num | true | string | 商品数量
transaction/products/price | true | string | 商品价格
transaction/products/pid | true | int | 商品id
forward | false | obj | 记录一个jsonobject，用来返回给自己
#### 返回参数
字段 | 必选 | 类型 | 说明
---|---|---|---
statusCode | true | string | 是否成功，成功为100，其他为失败
msg | true | string | 失败原因
prompt | true | int | 是否需要pos提示
fm_open_id | true | string | 非码会员唯一标识
fm_transId | true | string | 非码支付流水号
fm_id | true | string | 非码订单号
paid_total_amount | true | int | 非码会员实际付总金额
invoice_amount | false | int | 发票金额
discount_amount | false | int | 优惠金额
transaction/pay_ids | true | array | 支付信息
transaction/pay_ids\pay_id | true | string | 支付方式
transaction/pay_ids\pay_str | true | string | 支付方式描述
transaction/pay_ids\pay_amount | true | int | 该种支付方式支付金额
transaction/pay_ids\pay_account | ture | string | 支付账户
transaction/pay_ids\platform_discount | false | int | 支付平台折扣金额
transaction/pay_ids\merchant_discount | false | int | 商户活动折扣金额
transaction/pay_ids\ext | false | obj | 支付扩展字段
transaction/pay_ids\ext\print | false | string | 小票打印信息
transaction/pay_ids\code | false | string | 券码
forward | false | obj | 记录一个jsonobject，用来返回给自己
#### 会员支付示例
```json
//会员支付请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 1003,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"trans_id": "123",
"fm_id": "",
"fm_open_id":"",
"transaction": {
"order_amount":9000,
"paid_amount": 0,
"undis_amount": 0,
"products": [
{
"consume_num": 1,
"price": 1000,
"pid": "0079020"
},
{
"consume_num": 1,
"price": 8000,
"pid": "0077842"
}
]
}
}
//会员支付返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"fm_open_id": "qweqweqweqweqwe",
"fm_transId": "1231231231321321",
"fm_id ": "SXWAA1246O277528866",
"paid_total_amount": 9000,
"invoice_amount": 9000,
"discount_amount": 1000,
"pay_ids":[
{
"pay_id": "20001",
"pay_str": "会员储值金支付",
"pay_amount": 1000
},
{
"pay_id": "20002",
"pay_str": "会员积分支付",
"pay_amount": 5000
},
{
"pay_id": "20003",
"pay_str": "代金券支付",
"pay_amount": 1000,
"code": "123123123"
},
{
"pay_id": "20003",
"pay_str": "代金券支付",
"pay_amount": 1000,
"code": "123123124"
}
]
}
```
#### 条码支付示例
```json
//条码支付请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 10031,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"trans_id": "123",
"fm_id": "",
"fm_open_id":"",
"transaction": {
"order_amount":9000,
"paid_amount": 0,
"undis_amount": 0,
"barcode": "2801122356789801",
"products": [
{
"consume_num": 1,
"price": 1000,
"pid": "0079020"
},
{
"consume_num": 1,
"price": 8000,
"pid": "0077842"
}
]
}
}
//条码支付返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"fm_open_id":"",
"fm_transId": "1231231231321321",
"fm_id ": "SXWAA1246O277528866",
"paid_total_amount":9000,
"invoice_amount":9000,
"discount_amount": 1000,
"pay_ids":[
{
"pay_id": "10001",
"pay_str": "支付宝当面付[条码]",
"pay_amount": 8000,
"pay_account": "支付宝账号:abc****@163.com",
"platform_discount": 500,
"merchant_discount": 500,
"ext": {
"print": "\r\n
手机支付(支付宝)交易明细\r\n
---------------------------------------\r\n
账户支付 : 20.50\r\n 优惠金额: 1.00\r\n
支付交易号:2016070821001004480227435236\r\n
商户交易号:1051125947\r\n
---------------------------------------"
}
}
]
}
```
## 结算接口
一笔订单如果进行了非码会员认证，并且认证成功，则订单支付完成后，必须调用该结算接口，并且fm_open_id字段必须填正确。
一笔订单如果使用了非码会员支付，并且支付成功，则订单支付完成后，必须调用该结算接口，并且fm_id和fm_open_id两个字段必须填正确。
根据商户需要，如果商户需要实现微信/支付宝等第三方支付方式支付后送积分功能，则当一笔订单存在这种支付方式支付完成后，必须调用该结算接口。
调用该接口时，必须将该笔订单中所有付款方式信息传入，以保证会员相关功能正确。支付方式及对应的编码，请按照文档结尾的《支付类型对照表》进行一一对应，如果POS上一些支付方式未在表中列出，可先按POS上原有支付编码传入，并告知非码相关人员。
#### 请求参数
字段 | 必选 | 类型 | 说明
---|---|---|---
pos_ver | true | int | 接口版本
operator_id | true | string | 操作员
fm_cmd | true |int | 接口类型(结算: 1007)
pos_id | true |string | pos机编号
store_id | true |string | 门店号
business_date | true | string | 营业日
trans_id | ture | string | POS交易号
fm_id | true | string | 非码订单号
fm_open_id | false | string | 非码会员唯一标识,如果没有认证过会员则为空
transaction | true | obj | 交易信息
transaction/order_amount | true | int | 订单总额
transaction/paid_amount | true | int | 已付金额
transaction/pay_ids | true | array | 支付信息
transaction/pay_ids\pay_id | true | string | 支付方式
transaction/pay_ids\pay_str | true | string | 支付方式描述
transaction/pay_ids\pay_amount | true | int | 该种支付方式支付金额
transaction/pay_ids\pay_transId | false | string | 第三方支付交易号
transaction/pay_ids\code | false | string | 券号
transaction/products | true | array | 商品信息
transaction/products/consume_num | true | int | 商品数量
transaction/products/price | true | int | 商品价格
transaction/products/pid | true | string | 商品id
#### 返回参数
字段 | 必选 | 类型 | 说明
---|---|---|---
statusCode | true | string | 是否成功,成功为100,其他为失败
msg | true | string | 失败原因
prompt | true | int | 是否需要pos提示
fm_id | true | string | 非码订单号
print1 | false | string | 打印信息,可定制
print2 | false | string | 打印信息,可定制
#### 示列
```json
//结算请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 1007,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"trans_id" : "110",
"fm_id": "SXWAA1246O277528866",
"fm_open_id":"",
"transaction": {
"order_amount":14000,
"paid_amount": 14000,
"pay_ids":[
{
"pay_id": "20005",
"pay_str": "现金支付",
"pay_amount": 1000
},
{
"pay_id": "20001",
"pay_str": "会员储值金支付",
"pay_amount": 1000
},
{
"pay_id": "20002",
"pay_str": "会员积分支付",
"pay_amount": 1000
},
{
"pay_id": "20003",
"pay_str": "代金券支付",
"pay_amount": 1000,
"code": "123123123"
},
{
"pay_id": "10001",
"pay_str": "支付宝钱包",
"pay_amount": 5000,
"pay_transId": "4001111111111111111111"
},
{
"pay_id": "10004",
"pay_str": "微信钱包",
"pay_amount": 5000,
"pay_transId": "5001111111111111111111"
}
],
"products": [
{
"consume_num": 1,
"price": 1000,
"pid": "0079020"
},
{
"consume_num": 1,
"price": 8000,
"pid": "0077842"
}
]
}
}
//结算返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"fm_id":"11111111111111",
"print1":"*************",
"print2":"*************"
}
```
## 退款接口
一笔订单，如果已经进行了非码会员支付，取消订单时，必须调用该退款接口，退掉支付。
一笔订单，如果调用了会员结算接口，并返回成功，则退单时必须调用该退款接口，退掉订单。
退款接口同时兼容**会员退款**（退充值、退支付、退订单）、**条码支付退款**
trans_id字段，为要退的那笔支付的trans_id。
#### 请求参数
字段 | 必选 | 类型 | 说明
---|---|---|---
pos_ver | true | int | 接口版本
operator_id | true | string | 操作员
fm_cmd | true |int | 接口类型(会员交易退款: 1004; 条码支付退款: 10041)
pos_id | true |string | pos机编号
store_id | true |string | 门店号
business_date | true | string | 营业日
transaction | true | obj | 交易信息
transaction/refund_amount | true | int | 退款金额
transaction/fm_id | false | string | 非码订单号,退订单时填此字段
transaction/fm_transId | false | string | 非码支付流水号,退支付时填此字段
transaction/trans_id | false | string | POS交易号
#### 返回参数
字段 | 必选 | 类型 | 说明
---|---|---|---
statusCode | true | string | 是否成功，成功为100，其他为失败
msg | true | string | 失败原因
prompt | true | int | 是否需要pos提示
ext | false | obj | 扩展信息
ext/print | false | string | 小票打印信息
#### 会员退款示列
```json
//会员退款请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 10041,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"transaction": {
"fm_transId": "121212121212",
"fm_id":"123123123123123123",
"trans_id": "110",
"refund_amount": 0
}
}
//会员退款返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"ext": {
"print":""
}
}
```
#### 条码支付退款示列
```json
//条码支付退款请求示例
{
"pos_ver": 1,
"operator_id": "00000002",
"fm_cmd": 10041,
"pos_id": "1",
"store_id": "208888",
"business_date": "20150701",
"transaction": {
"fm_transId": "121212121212",
"fm_id":"123123123123123123",
"trans_id": "110",
"refund_amount": 0
}
}
//条码支付退款返回示例
{
"statusCode":100,
"msg":"",
"prompt":0,
"ext": {
"print":"\r\n
支 付 宝 退 款 明 细 \r\n
---------------------------------------\r\n
账 户 支 付 : 0.10\r\n 优惠金额: 0.00\r\n
退款金额: 0.10\r\n 支付交易 号:2015073021001004200028563033\r\n
商户交易号:734668188\r\n---------------------------------------"
}
}
```
## 接口请求类型(fm_cmd)对照表
接口名称 | fm_cmd取值
--- | ---
认证接口 | 1001
充值接口 | 1002
会员支付接口 | 1003
条码支付接口 | 10031
会员退款接口 | 1004
条码支付退款接口 | 10041
结算接口 | 1007
## 错误信息对照表
错误信息 | 错误编码
--- | ---
成功 | 100
超时 | 102
Json解析错误 | 103
连接非码服务器时网络异常 | 104
非码服务器返回错误 | 105
程序运行时被关闭 | 106
## 支付类型对照表
支付方式 | 支付类型编码
--- | ---
支付宝 | 10001
微信 | 10004
百度 | 10008
电信 | 10010
银行卡 | 10011
会员储值金 | 20001
会员积分 | 20002
代金券 | 20003
商品券 | 20004
现金 | 20005
\ No newline at end of file
非码会员客户端与POS对接文档 V2.0.0.md 0 → 100644
# 非码会员客户端与POS对接文档 V2.0.0
# 非码会员客户端与POS对接文档 V2.0.0
[TOC]
***
## 对接须知
### 对接方式
- 会员客户端作为Socket服务器运行在POS机上，处理POS程序发来的Socket请求
- 会员客户端监听本机端口: 23770
### Socket消息头
为加强数据传输可靠性性，推荐POS在每一次请求时，在请求数据前加上一个消息头。
#### 消息头构成说明：
>一个固定值(0x4d46) + 版本号(0x2) + 本次请求数据长度
#### 带消息头的请求构造举例：
- 将名为 FMSOCKHEADER 结构体类型的消息头添加到原始请求数据的开头，将新生成的数据作为请求数据发送给会员客户端。
- FMSOCKHEADER 结构体声明如下：
```cpp
typedef struct {
unsigned int flag; // 固定值 0x4d46
unsigned int ver; // 版本号 0x2
unsigned int len; // 原始请求数据的数据长度
}FMSOCKHEADER;
```
- 代码示例：
```cpp
// eg：
// 获得POS生成的JSON格式请求数据
char *originData = posReqJson.data(); // 获得原始数据
int originLen = posReqJson.length(); //获得原始数据长度
// 设置消息头的值
FMSOCKHEADER header = {0, 0, 0};
header.flag = 0x4d46;
header.len = originLen;
header.ver = 0x2;
// 声明一个新的数据指针
char* newReqData = new char[originLen + sizeof(FMSOCKHEADER)];
memset(newReqData, 0, originLen + sizeof(FMSOCKHEADER));
memcpy(newReqData, &header, sizeof(FMSOCKHEADER)); // 将消息头拷贝至newReqData
strcat(newReqData, originData); //将原始数据追加到newReqData
// 向会员客户端发送newReqData
```
## 常见使用场景举例
### 使用会员支付并积分
- 调用[会员结算](#会员结算)时，字段：fm_open_id、products 可不传或传空
- 如果支付成功，但结算失败，POS需要能够重新结算或请求退款
![会员支付会员结算流程图](http://172.16.12.240/zhenfei.zhang/FMVIPAPI/raw/master/Pictures/pay&order.PNG)
***
### 使用非码支付[^fmPay]并积分
- 调用[会员结算](#会员结算)时，字段：fm_open_id、products 可不传或传空
- 如果支付成功，但结算失败，POS需要能够重新结算或请求退款
![非码支付会员结算流程图](http://172.16.12.240/zhenfei.zhang/FMVIPAPI/raw/master/Pictures/fmpay&order.PNG)
***
### 使用现金等其他支付方式支付并积分
- 其他POS上已有支付方式想要积分，流程类似
- 可在[会员认证](#会员认证)前或后进行支付
- 可以混合使用[会员支付](#会员支付)或**非码支付[^fmPay]**
- 调用[会员结算](#会员结算)时，字段：fm_open_id、products **不能为空**
![会员认证会员结算流程图](http://172.16.12.240/zhenfei.zhang/FMVIPAPI/raw/master/Pictures/login&order.PNG)
***
## 接口
### 设置门店信息
#### 注意事项
- 收银机开机时调用
- 门店号、POS号、收银员号或营业日信息更改时调用
#### 请求参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| fm_cmd | true | int | [请求类型](#请求类型对照表)(1000) |
| store_id | true | string | 门店编号 |
| pos_id | true | string | POS编号 |
| business_date | true | string | 营业日(yyyyMMdd) |
| operator_id | true | string | 收银员 |
#### 响应参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| status_code | true | int | [响应状态码](#状态信息对照表) |
| statusCode | false | int | 响应状态码, 同status_code字段。兼容老版本接口。|
| msg | false | string | 响应信息 |
#### 示例
```JSON
请求：
{
"fm_cmd": 1000,
"store_id": "fm9999",
"pos_id": "1",
"business_date": "20171016",
"operator_id": "001"
}
响应：
{
"status_code": 100,
"msg": ""
}
```
***
### 会员认证
#### 注意事项
- 调用之前必须已经调用过**[设置门店信息](#设置门店信息)**接口
- 需要获取会员信息时调用
#### 请求参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| fm_cmd | true | int | [请求类型](#请求类型对照表)(1001) |
#### 响应参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| status_code | true | int | [响应状态码](#状态信息对照表) |
| statusCode | false | int | 响应状态码, 同status_code字段。兼容老版本接口。|
| msg | false | string | 响应信息 |
| fm_open_id | true | string | 非码会员唯一标识openid,在其他接口中标识唯一会员 | |
| amount | true | int | 账户余额(分) |
| score | true | int | 账户积分(个) |
| name | false | string | 姓名 |
| sex | false | string | 性别(男/女) |
| birthday | false | string | 生日(yyyy-MM-dd) |
| phone | false | string | 手机号 |
| address | false | string | 通讯地址 |
| email | false | string | 电子邮箱 |
#### 示例
```json
请求：
{
"fm_cmd": 1001
}
响应：
{
"status_code":100,
"msg":"",
"fm_open_id":"qweqweqweqweqwe",
"amount": 10000,
"score": 100,
"name": "非码",
"sex": "男",
"birthday": "1991-01-01",
"phone":"18112341234",
"address":"上海",
"email":"abc@163.com"
}
```
***
### 会员支付
#### 注意事项
- 调用之前必须已经调用过**[设置门店信息](#设置门店信息)**接口
- 支付成功后，如果要取消支付或取消订单，需要调用**[会员退款](#会员退款)**接口进行退款
#### 请求参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| fm_cmd | true | int | [请求类型](#请求类型对照表)(1003) |
| order_amount | true | int | 订单总额(分) |
| trans_amount | true | int | 交易金额(分) |
| undis_amount | false | int | 不可优惠金额(分)，默认为0 |
| order_id | true | string | POS订单号 |
| trans_id | true | string | POS交易号 |
| code | false | string | 支付条码。如果不传该字段，则会弹窗由收银员录入。 |
| products | true | array | 商品信息 |
| products/pid | true | string | 商品货号 |
| products/name | true | string | 商品名称 |
| products/price | true | int | 商品单价 |
| products/consume_num | true | int | 商品数量 |
#### 响应参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| status_code | true | int | [响应状态码](#状态信息对照表) |
| statusCode | false | int | 响应状态码, 同status_code字段。兼容老版本接口。|
| msg | false | string | 响应信息 |
| fm_open_id | true | string | 非码会员唯一标识openid |
| fm_order_id | true | string | 非码订单号 |
| fm_trans_id | true | string | 非码交易号 |
| paid_amount | true | int | 交易金额(分) |
| dis_amount | true | int | 优惠金额(分) |
| pay_list | true | array | 支付方式列表 |
| pay_list\pay_id | true | string | [支付方式编码](#支付类型对照表)
| pay_list\pay_str | true | string | 支付方式描述
| pay_list\pay_amount | true | int | 该种支付方式支付金额
| pay_list\pay_account | false | string | 支付账户
| pay_list\platform_discount | false | int | 支付平台折扣金额
| pay_list\merchant_discount | false | int | 商户活动折扣金额
| pay_list\ext | false | obj | 支付扩展字段
| pay_list\ext\print | false | string | 小票打印信息
| pay_list\coupon_code | false | string | 券码
#### 示例
```JSON
请求：
{
"fm_cmd": 1003,
"order_amount":9000,
"trans_amount": 8000,
"undis_amount": 8000,
"order_id": "20171018001",
"trans_id": "100001",
"products": [
{
"pid": "0079020",
"name": "测试商品1",
"price": 1000,
"consume_num": 1
},
{
"pid": "0077842",
"name": "测试商品2",
"price": 8000,
"consume_num": 2
}
]
}
响应：
{
"status_code":100,
"msg":"",
"fm_open_id": "qweqweqweqweqwe",
"fm_order_id ": "SXWAA1246O277528866",
"fm_trans_id": "1231231231321321",
"paid_amount": 9000,
"dis_amount": 0,
"pay_list":[
{
"pay_id": "20001",
"pay_str": "会员储值金支付",
"pay_amount": 1000
},
{
"pay_id": "20002",
"pay_str": "会员积分支付",
"pay_amount": 5000
},
{
"pay_id": "20003",
"pay_str": "代金券支付",
"pay_amount": 1000,
"coupon_code": "123123123"
},
{
"pay_id": "20003",
"pay_str": "代金券支付",
"pay_amount": 1000,
"coupon_code": "123123124"
}
]
}
```
***
### 会员退款
#### 注意事项
- 目前仅支持在原消费POS上退款
#### 请求参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| fm_cmd | true | int | [请求类型](#请求类型对照表)(1004) |
| order_id | true | string | POS订单号 |
#### 响应参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| status_code | true | int | [响应状态码](#状态信息对照表) |
| statusCode | false | int | 响应状态码, 同status_code字段。兼容老版本接口。|
| msg | false | string | 响应信息 |
| refund_amount | true | int | 退款金额 |
#### 示例
```json
请求：
{
"fm_cmd": 1004,
"order_id": "12345678"
}
响应：
{
"status_code":100,
"msg":"",
"refund_amount": 100
}
```
***
### 会员结算
#### 注意事项
- 如果订单使用了**[会员支付](#会员支付)**，必须进行结算
- 如果结算返回失败，可以尝试重新结算。如果放弃结算，必须调用**[会员退款](#会员退款)**接口将已付金额退款
- 如果订单没有使用**[会员支付](#会员支付)**或**非码支付[^fmPay]**，则请求参数中字段：fm_open_id、products 不能为空
- 如果订单中含有**[会员支付](#会员支付)**或**非码支付[^fmPay]**以外的其他支付方式，则需要在字段：pay_list 中传给非码。否则默认当作现金处理。
#### 请求参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| fm_cmd | true | int | [请求类型](#请求类型对照表)(1007) |
| order_id | true | string | POS订单号 |
| order_amount | true | int | 订单总金额 |
| fm_open_id | false | string | 将此订单结算给指定会员。订单中使用了[会员支付](#会员支付)或非码支付[^fmPay]后，可不传此字段，或传空；如果没用过则必须传此字段。|
| products | false | array | 商品信息。订单中使用了[会员支付](#会员支付)或非码支付[^fmPay]后，可不传此字段，或传空；如果没用过则必须传此字段。|
| products/pid | true | string | 商品货号 |
| products/name | true | string | 商品名称 |
| products/price | true | int | 商品单价 |
| products/consume_num | true | int | 商品数量 |
| pay_list | false | array | 支付方式列表。此字段用来补充订单中的其他支付方式 |
| pay_list\pay_id | true| string | [支付方式编码](#支付类型对照表) |
| pay_list\pay_str | true | string | 支付方式描述 |
| pay_list\pay_amount | true | int | 该种支付方式支付金额 |
| pay_list\pay_account | false | string | 支付账户 |
| pay_list\ext | false | obj | 支付扩展字段 |
#### 响应参数
| 字段 | 必选 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| status_code | true | int | [响应状态码](#状态信息对照表) |
| statusCode | false | int | 响应状态码, 同status_code字段。兼容老版本接口。|
| msg | false | string | 响应信息 |
| fm_order_id | true | string | 非码订单号 |
| ext | false | string | 扩展字段 |
| ext/print | false | string | 打印信息 |
#### 示例
```json
请求：
{
"fm_cmd": 1007,
"order_id": "12345678"
}
响应：
{
"status_code":100,
"msg":"",
"fm_order_id":"123456789"
}
```
***
## 请求类型对照表
| 请求类型 | 对应接口 | 备注 |
|: ------ :| -------- |: -- :|
| 1000 | [设置门店信息](#设置门店信息) | \ |
| 1001 | [会员认证](#会员认证) | \ |
| 1003 | [会员支付](#会员支付) | \ |
| 1004 | [会员退款](#会员退款) | \ |
| 1007 | [会员结算](#会员结算) | \ |
***
## 状态信息对照表
| 状态码 | 状态信息 |
|:------:| -------- |
| 100 | 成功 |
| 101 | 一般错误 |
| 102 | 超时错误 |
| 103 | Json解析错误 |
| 104 | 连接非码服务器时网络异常 |
| 105 | 非码服务器返回错误 |
| 106 | 程序运行时被关闭 |
***
## 支付类型对照表
| 支付方式编码 | 支付方式说明 |
|:------------:| -------- |
| 10001 | 支付宝 |
| 10004 | 微信 |
| 10008 | 百度 |
| 10010 | 电信 |
| 10011 | 银行卡 |
| 20001 | 会员储值金 |
| 20002 | 会员积分 |
| 20003 | 代金券 |
| 20004 | 商品券 |
| 20005 | 现金 |
***
## 修订历史
| 版本号 | 修订时间 | 修订内容 |
| ----- | ------- | ------- |
| V2.0.0 | 2017-10-24 09:59 | 创建2.0版本文档 |
[^fmPay]: 非码支付(非码收银)，统一收银服务。详见[www.freemud.cn](http://www.freemud.cn/service.html)
\ No newline at end of file
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment