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

一、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、通用签名生成步骤

拼接字符串："自己的secretKey" + "appId" + "自己的appId" + "timestamp" + "当前时间戳（毫秒）timestamp" + "接口请求参数json" + "自己的secretKey" ，得到rawSign

将rawSign进行md5加密，并转换为大写的十六进制

案例：
appId = abcdef
secretKey = 123456
timestamp = 1745831078000
requestBody = {"cityId": 1111}

rawSign = secretKey + "appId" + appId + "timestamp" + timestamp + requestBody + secretKey
rawSign = 123456abcdef1745831078000{"cityId": 1111}123456
sign = 对rawSign进行md5加密后，转换为大写的十六进制

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

三、API对接流程

3.1、关注【良票】公众号后，点击放单，注册账号，联系平台运营提供业务端账号，开通api接入权限，获取api接入参数

3.2、API地址

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

四、影票订单信息异步回调

4.1、简要描述

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

4.2、回调url

请从创建订单api入参

4.3、请求类型

application/json

4.4、请求方式

POST

4.5、回调参数

参数名	类型	说明
refundTime	String	退款/失败时间
seatInfos	List<CallbackSeatInfoDto>	座位信息Json数组（换座时会有新的座位信息，否则为空）
refuseMsg	String	订单失败/退票原因
tickets	List<CallbackTicketDto>	出票信息
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	出票失败（含流单、弃单、订单关闭）

返回格式

{
  "changeSeatState":"2",// 换座状态
  "finalPrice":3572,// 单座位出票价
  "finalPriceAll":7144,// 整单出票价
  "orderNumber":"良票订单号",
  "outOrderNumber":"您自己的订单号",
  "priceAll":9580,// 整单原价
  "refundTime":"1970-01-01 08:00:00",
  "refuseMsg":"",// 失败原因
  "seatCount":2,// 座位信息只有在换座时存在
  "seatInfo":"6排13座,6排12座",
  "seatInfos":[
    {
      "col":"",
      "row":"",
      "seatName":"6排13座"
    },
    {
      "col":"",
      "row":"",
      "seatName":"6排12座"
    }
  ],
  "shortCodeUrl":"短链接",
  "status":"UPLOAD_TICKET_CODE",// 出票状态
  "tickets":[
    {
      "ticket":"票根图片",
      "ticketCode":"取票码",
      "validateCode":""
    }
  ],
  "timeStamp":"1748053753707"
}

返回说明

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

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

当前暂无订单逆向状态回调（出票成功后主动订单退款），由客服人员在对接群通知单号，后续将完善

五、影票识别记录回调

5.1、简要描述

用户选座截图识别成功后会自动回调识别结果。

5.2、回调url

请从添加识别任务api入参

5.3、请求类型

application/json

5.4、请求方式

POST

5.5、回调参数

回调数据

参数名	类型	说明
data	Object	回调数据
message	String	异常信息
result	Boolean	是否正常
state	Integer	状态码

data

参数名	类型	说明
taskId	Long	良票识别任务ID
outTaskId	String	您自己生成的识别任务ID
filmId	Long	影片ID
filmName	String	影片名称
filmImg	String	影片海报
discern	Object	识别结果
showTime	String	场次时间
seatNos	List<String>	座位名称列表
totalImagePrice	String	图片总价格

discerns

参数名	类型	说明
area	String	区名
showId	Long	场次ID
province	String	省名
city	String	城市名
cinemaName	String	影院名称
cinemaCode	String	影院转资
cinemaId	Long	影院ID
hallName	String	影厅名称
planType	String	影片类型
cinemaAddress	String	影院地址
seats	List<Object>	座位列表
cinemaLineId	Long	院线ID
cinemaLineName	String	院线名称
showTime	String	场次时间
cityCode	String	省市区编号

seats

参数名	类型	说明
row	String	行
col	String	列
seatNo	String	座位名称
seatType	String	座位类型（空为普通座位、L为情侣座左、R为情侣右）
canUse	Boolean	是否可用
regionName	String	座位区域名称
price	Integer	座位原价

返回格式

{
  "data":{
    "taskId":1387081673547304960,
    "outTaskId":"1387081673438789632",
    "filmId":1377863135561089024,
    "filmName":"新·驯龙高手",
    "filmImg":"https://p0.pipi.cn/mediaplus/friday_image_fe/0fa3345b77e4a13d696b1bce686a9a1be7efb.jpg?imageMogr2/thumbnail/1246x1246%3E",
    "discern":{
      "area":"裕华区",
      "showId":1386292254846300176,
      "province":"河北省",
      "city":"石家庄市",
      "cinemaName":"完美世界影城石家庄万象汇店",
      "cinemaCode":"13011441",
      "cinemaId":1166369852942741504,
      "hallName":"5号激光沙发厅",
      "planType":"国语 3D",
      "cinemaAddress":"裕华区裕华东路311号石家庄高新万象汇L402号商铺",
      "seats":[
        {
          "row":"5",
          "col":"14",
          "seatNo":"5排10座",
          "seatType":"",
          "canUse":true,
          "regionName":"4875",
          "price":4000
        }
      ],
      "cinemaLineId":1182612695204413440,
      "cinemaLineName":"其他",
      "showTime":"2025-06-25 16:10:00",
      "cityCode":"130100"
    },
    "showTime":"2025-6-25 16:10:00",
    "seatNos":[
      "5排10座"
    ],
    "totalImagePrice":"3990"
  },
  "message":"",
  "result":true,
  "state":200
}

返回说明

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

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

六、关于费用、押金、及合同

【费用押金】

影票代订业务：3000元/年；年满1w单有效订单后返还
实物分销业务：业务暂未上线

【合同/合作协议】

接入方要求必须为：企业或个体工商户，签署合作协议，个人暂不支持接入

一、API规范#

1.1、api规则#

1.2、请求公共参数#

1.3、响应参数格式说明#

二、API签名算法#

2.1、通用签名生成步骤#

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

三、API对接流程#

3.1、关注【良票】公众号后，点击放单，注册账号，联系平台运营提供业务端账号，开通api接入权限，获取api接入参数#

3.2、API地址#

四、影票订单信息异步回调#

4.1、 简要描述#

4.2、回调url#

4.3、请求类型#

4.4、请求方式#

4.5、回调参数#

返回格式#

返回说明#

五、影票识别记录回调#

5.1、 简要描述#

5.2、回调url#

5.3、请求类型#

5.4、请求方式#

5.5、回调参数#

返回格式#

返回说明#

六、关于费用、押金、及合同#

【费用押金】#

【合同/合作协议】#

一、API规范

1.1、api规则

1.2、请求公共参数

1.3、响应参数格式说明

二、API签名算法

2.1、通用签名生成步骤

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

三、API对接流程

3.1、关注【良票】公众号后，点击放单，注册账号，联系平台运营提供业务端账号，开通api接入权限，获取api接入参数

3.2、API地址

四、影票订单信息异步回调

4.1、简要描述

4.2、回调url

4.3、请求类型

4.4、请求方式

4.5、回调参数

返回格式

返回说明

五、影票识别记录回调

5.1、简要描述

5.2、回调url

5.3、请求类型

5.4、请求方式

5.5、回调参数

返回格式

返回说明

六、关于费用、押金、及合同

【费用押金】

【合同/合作协议】