第三方业务服务商-对接必读

一、API规范

1.1、api规则

操作	规范
传输方式	采用 HTTP、HTTPS
提交方式	采用 POST 方法提交
请求参数类型	Content-Type: application/json
响应参数类型	Content-Type: application/json
字符编码	统一采用 UTF-8 字符编码
签名算法	MD5 （32位）
分页传参	page、size（最大限制100）

1.2、请求公共参数

字段	必填	类型	描述
appId	是	String	key
sign	是	String	签名
timestamp	是	String	时间戳

1.3、响应参数格式说明

注：以下接口均为有返回，返回值放在数据实体 data 里，如无实体值，则以 state 判断结果，state为200时表示成功，其他值时为失败#

二、API签名算法

2.1、通用签名生成步骤

1. 将secretKey+"appId"+appId+"timeStamp"+timeStamp+RequestBody接口请求参数+secretKey进行如上顺序拼接(没有'+'号)，得到StringA
2. 将StringA进行md5加密，并转换为大写的十六进制

2.2、通用签名生成示例代码

//php示例

//java示例
    
    String joinedParams = joinRequestParams(params, body, secretKey, keys);
    // 使用加密算法进行加密（目前仅支持md5算法）
    byte[] abstractMesaage = digest(joinedParams);
    // 把二进制转换成大写的十六进制
    String md5 = byte2Hex(abstractMesaage);
    
    private static String joinRequestParams(Map<String, String> params, String body, String secretKey, String[] sortedKes) {
        StringBuilder sb = new StringBuilder(secretKey); // 前面加上secretKey
        for (String key : sortedKes) {
            if ("sign".equals(key)) {
                continue; // 签名时不计算sign本身
            } else {
                String value = params.get(key);
                if (!StringUtils.isEmpty(key) && !StringUtils.isEmpty(value)) {
                    sb.append(key).append(value);
                }
            }
        }
        sb.append(body); // 拼接body体
        sb.append(secretKey); // 最后加上secretKey
        return sb.toString();
    }

三、API对接流程

3.1、注册良票开放平台-业务端（http://business-v2.liangpiao.net.cn/ ）后，联系平台运营提供业务端账号，开通api接入权限，获取api接入参数，上线前与平台运营沟通是否接入极速出票（秒级出票）

3.2、API地址

环境	地址
生产（正式）环境	business-api.liangpiao.net.cn
测试环境	暂无

四、SDK接入

4.1、 接入流程（这里使用idea2023.2示例）

2.

3.

4.

4.2、 注意事项

如果返回结果包含乱码，请在启动类添加如下配置：

@Bean
public RestTemplate restTemplate(){
    RestTemplate restTemplate = new RestTemplate();
    restTemplate.getMessageConverters().stream().filter(converter -> converter instanceof StringHttpMessageConverter).forEach(converter -> ((StringHttpMessageConverter) converter).setDefaultCharset(Charset.forName("UTF-8")));
    return restTemplate;
}

五、订单信息异步回调

5.1、 简要描述

订单状态发生改变时通知接入方，接入方可以根据订单状态做相应操作。

5.2、回调url

请从创建订单api入参

5.3、请求类型

application/json

5.4、请求方式

POST

5.5、回调参数

参数名	类型	说明
refundTime	String	退款/失败时间
seatInfos	List	座位信息Json数组
refuseMsg	String	订单 失败/退票 原因
tickets	List	出票信息
seatInfo	String	座位简要信息
changeSeatState	String	换座状态（0 不可换座 1 可换座 2 已换座
timeStamp	String	回调时间戳，13位毫秒级
status	String	订单状态
outOrderNumber	String	订单编号
priceAll	Integer	原价（总价,单位为分）
finalPrice	Integer	实付价（单位为分）
finalPriceAll	Integer	实付价总价（单位为分）
seatCount	Integer	座位数量

CallbackSeatInfoDto

参数名	类型	说明
seatName	String	座位名
row	String	行
col	String	列

CallbackTicketDto

参数名	类型	说明
ticket	String	票根
ticketCode	String	取票码
validateCode	String	验证码

status

状态值	状态说明
UPLOAD_TICKET_CODE	出票成功
CHANGE_TICKET_CODE	订单票码发生了改变
UPLOAD_TICKET_TIMEOUT	出票失败（含流单、弃单、订单关闭）

返回说明

如果正常接收到订单信息，请返回以下json格式字符串

{
    "result":true,
    "message":""
}

我方接收到以上返回将认为接入方已处理完成，不会再进行回调。
若返回其他的一律认为没有收到应答，将继续回调。