README

专资办购票交易 SDK（legacy 协议）— 用于购票流程中的影院 / 影厅 / 场次 / 座位查询、锁座、下单、退票等交易操作。

功能

类别	方法	说明
查询	`getCinemaInfo`	影院信息下载
查询	`getScreenInfo`	影厅信息下载
查询	`downloadFilmInfo`	影片信息下载（分页）
查询	`querySessionInfo`	排片信息查询（分页）
查询	`queryScreenSeatInfo`	影厅座位布局查询
查询	`querySeatStatusInfo`	场次座位售出状态查询
交易	`lockSeatsInfo`	座位锁定
交易	`releaseSeatsInfo`	座位解锁
交易	`submitOrder`	确认订单交易
交易	`queryOrderInfo`	订单详情查询
交易	`refundTicket`	退票
交易	`refundTicketByLockOrderId`	按锁座单号退票（先查单再退票）
上报	`reportTicket`	票房数据上报（legacy 签名）
上报	`reportTicketByLockOrderId`	按单号售票上报（先查单再上报）
上报	`refundReportTicketByLockOrderId`	按单号退票上报
上报	`downloadReportRecord`	数据比对文件下载（返回原始内容）

环境要求

PHP >= 8.1
ext-openssl
ext-curl

安装

composer require kylin987/zzb-ticket-sdk

快速开始

<?php

use ZzbTicketSdk\Config;
use ZzbTicketSdk\ZzbTicketService;

$config = new Config([
    'serviceUrl'    => 'https://your-host/serverapp',
    'reportUrl'     => 'https://your-host/serverapp',
    'channelCode'   => 'your-channel-code',
    'certId'        => 'your-cert-id',
    'appId'         => 'your-app-id',
    'interfaceKey'  => 'your-interface-key',
    'certFile'      => '/path/to/cert.pem',
    'certFilePwd'   => 'your-cert-password',
    'trustFile'     => '/path/to/rootcert.pem',
    'version'       => '1.0',
]);

$service = new ZzbTicketService($config);

// 查询影院信息
$result = $service->getCinemaInfo('13090401');
if ($result->isSuccess()) {
    $cinema = $result->data;
    echo $cinema->cinemaName;
}

// 查询排片
$sessions = $service->querySessionInfo('13090401', '2026-01-01', '2026-01-31', 1);
if ($sessions->isSuccess() && $sessions->data) {
    foreach ($sessions->data->sessionList as $session) {
        echo $session->sessionCode . PHP_EOL;
    }
}

// 锁座
$lockResult = $service->lockSeatsInfo('13090401', 'SE0001', 'APP_LOCK_001', [
    ['seatCode' => '88888888010010011101'],
]);

// 确认订单
if ($lockResult->isSuccess()) {
    $lockOrderId = $lockResult->data->lockOrderId;
    $orderResult = $service->submitOrder($lockOrderId, '13090401', 'SE0001', [
        [
            'seatCode'         => '88888888010010011101',
            'regionCode'       => 'R1',
            'sectionCode'      => 'S1',
            'ticketPrice'      => 56.00,
            'screenServiceFee' => 0.00,
            'netServiceFee'    => 8.00,
        ],
    ]);
}

配置参数

参数	类型	说明
`serviceUrl`	string	信息下载接口地址
`reportUrl`	string	数据上报接口地址
`channelCode`	string	网售编码
`certId`	string	证书 ID
`appId`	string	应用 ID（不填时回退到 certId）
`interfaceKey`	string	接口密钥（配置后使用 SM3 摘要签名，否则使用私钥签名）
`certFile`	string	证书文件路径（支持 PFX/P12、PEM 合并、PEM 私钥）
`certFilePwd`	string	证书密码
`keyFile`	string	独立私钥文件路径（PEM 格式，与证书分离时使用）
`keyFilePwd`	string	私钥密码
`trustFile`	string	信任根证书路径
`trustFilePwd`	string	信任证书密码
`cssConfigFile`	string	cssconfig.properties 文件路径
`version`	string	API 版本号（默认 `1.0`）
`proxy`	string	代理地址（不填时默认禁用系统代理）
`httpLogger`	callable	HTTP 日志回调，接收 array 上下文

签名方式

SDK 根据是否配置 interfaceKey 自动选择签名方式：

1. interfaceKey + SM3 摘要

配置了 interfaceKey 时，将请求报文原文与 password、timestamp 作为同级字段，按键名升序序列化后做 SM3 摘要，再 Base64。

2. SM2 / RSA 私钥签名

未配置 interfaceKey 时，使用私钥对排序后的 JSON 报文签名。自动检测密钥类型：

EC 密钥（SM2）：尝试 SM3 摘要签名，失败回退 SHA256
RSA 密钥：使用 SHA256 签名
结果 urlencode(base64_encode(signature))

证书格式支持

格式	配置方式	说明
PFX / P12	`certFile` + `certFilePwd`	自动解析并转换为 PEM 临时文件
PEM 合并文件	`certFile` + `certFilePwd`	文件同时包含私钥和证书
PEM 分离文件	`certFile`(证书) + `keyFile`(私钥)	证书和私钥分别配置
PEM 私钥文件	`certFile`(私钥) + `certFilePwd`	自动查找同目录下的 certificate.pem

API

ZzbTicketService

所有方法返回 ZzbResult，通过 $result->isSuccess() 判断是否成功，$result->data 获取解析后的数据对象。

详细方法签名见 ZzbTicketService.php。

数据模型

模型	说明
`ZzbCinema`	影院信息
`ZzbCinemaScreen`	影厅信息
`ZzbFilmPage`	影片分页
`ZzbSessionPage`	排片分页
`ZzbScreenSeatInfo`	影厅座位布局
`ZzbSeatStatusResult`	场次座位状态
`ZzbLockSeatsResult`	锁座结果
`ZzbReleaseSeatsResult`	解锁结果
`ZzbSubmitOrderResult`	提交订单结果
`ZzbQueryOrderResult`	订单详情
`ZzbRefundTicketResult`	退票结果
`ZzbTicket`	上报票据信息
`ZzbResult`	统一响应

与旧包的关系

本包从 kylin987/zzb-sdk-php 2.x 提取 legacy 逻辑而来，去掉了 netsale2025 模式分支和 V-STK 签名相关代码。如果只需要购票 / 查询 / 交易能力，使用本包即可，无需安装旧包。

版本

版本	说明
v1.0.0	从 zzb-sdk-php 2.x 提取 legacy 逻辑，去除 netsale2025 分支

License

MIT

kylin987/zzb-ticket-sdk

包简介

README 文档