从第一笔只读请求开始验证接入，再接入顾客、预约等业务接口。PHP 可直接使用 SDK；其他语言按下方签名规则发送 HTTP 请求。

准备凭证 · PHP SDK 五分钟自测 · 非 PHP 语言对接 · 排错速查 · 接口索引

接入前先确认

当前 PHP SDK 的请求地址指向 dev1.qique.cn。开发环境是否使用独立业务数据请先与对接人员确认；写入类请求只在获准的测试机构及测试数据上执行。正式环境地址和凭证由对接人员确认后再切换。

准备凭证

1. 首次接入的技术服务商联系企雀对接人员（0592-3278866），领取 DistributionAppId 和 DistributionAppSecret。
2. 机构管理员登录 企雀后台 API 设置，获取本机构的 AppId 和 AppSecret。
3. 确认四个值属于同一次对接和目标机构。AppSecret、DistributionAppSecret 只保存在服务端环境变量或密钥管理系统中，不放入前端页面、代码仓库或工单截图。

PHP SDK 五分钟自测

1. 下载并准备运行环境

下载 PHP SDK（20260703QiQueSdk.zip）。解压后保留 QiQue.php 与 lib/ 的相对目录。SDK 需要 PHP 5.3 或更新版本及 cURL 扩展。

2. 配置四个环境变量

在运行自测脚本的服务端配置 QIQUE_APP_ID、QIQUE_APP_SECRET、QIQUE_DISTRIBUTION_APP_ID、QIQUE_DISTRIBUTION_APP_SECRET。不要把真实值写进脚本或发送给其他人。

3. 发起只读请求

在解压目录运行以下 PHP 代码。getPayTypeList(0) 只读取支付方式列表，不创建或修改业务数据。

<?php
require_once __DIR__ . '/QiQue.php';

$keys = array(
    'QIQUE_APP_ID',
    'QIQUE_APP_SECRET',
    'QIQUE_DISTRIBUTION_APP_ID',
    'QIQUE_DISTRIBUTION_APP_SECRET'
);
foreach ($keys as $key) {
    if (!getenv($key)) {
        throw new RuntimeException('Missing environment variable: ' . $key);
    }
}

try {
    $client = new QiQue(
        getenv('QIQUE_APP_ID'),
        getenv('QIQUE_APP_SECRET'),
        getenv('QIQUE_DISTRIBUTION_APP_ID'),
        getenv('QIQUE_DISTRIBUTION_APP_SECRET')
    );
    $result = $client->getPayTypeList(0);
    if (!isset($result['errNum']) || (int)$result['errNum'] !== 0) {
        throw new RuntimeException('API error: ' . json_encode($result));
    }
    echo 'Connected. Items: ' . count($result['list']) . PHP_EOL;
} catch (Exception $e) {
    fwrite(STDERR, $e->getMessage() . PHP_EOL);
    exit(1);
}

执行结果应显示 Connected. Items: N。N 可以为 0；关键是返回 JSON 中 errNum 为 0，并包含 list。若连接失败，先看下方排错速查。

4. 接入业务接口

只读请求成功后，按顾客类接口等接口文档选用 SDK 方法。例如修改顾客信息时，只传确定的字段名，并在测试机构上先验证目标顾客：

$result = $client->editCustomer($cusId, null, array('name' => '测试顾客'));
if (!isset($result['errNum']) || (int)$result['errNum'] !== 0) {
    // 记录业务错误并停止后续写入。
}

editCustomer 是写操作；示例中的 $cusId 应由测试机构提供。写入请求的超时不等于写入失败，重试前先查业务结果，避免重复操作。

非 PHP 语言对接

API 路径的 {method} 使用接口文档中确定的方法名，例如只读自测为 getpaytypelist。GET 参数放在查询字符串，POST 参数使用 application/x-www-form-urlencoded；不要把请求体当作未参与签名的 JSON 发送。每个请求都包含以下公共参数：

签名步骤：

1. 合并公共参数和该接口的业务参数，排除 sign；URL 路由参数 r 不参与签名。
2. 按参数名升序排序。依序拼接每个参数的“字段名 + 原始字符串值”，不加 =、& 或其他分隔符。
3. 计算 md5(AppSecret + DistributionAppSecret + 拼接结果 + AppSecret)，得到 sign。字符串编码、大小写和空值处理须与实际发送的参数一致。
4. 将 sign 与其余参数一起发送。首次对接建议用只读的 GET /index.php?r=data/api/getpaytypelist 验证。

GET https://dev1.qique.cn/index.php?r=data/api/getpaytypelist
    ?t={AppId}&dis={DistributionAppId}&timeStamp={当前时间}
    &format=json&signMethod=md5&v=3.0&sign={按规则计算的值}

不要在浏览器地址栏或截图中粘贴真实签名请求 URL；查询字符串可能进入浏览器历史和访问日志。其他语言的参数细节见非 SDK 对接说明。

排错速查

按顺序检查网络/HTTP、JSON 解析、errNum 和 msg。接口可能在 HTTP 200 中返回业务错误。

仍需协助时，提供请求时间、环境域名、接口方法、HTTP 状态、errNum、msg 和已脱敏的参数名清单。不要发送 AppSecret、DistributionAppSecret、完整签名或顾客隐私数据。

接口索引

• 顾客类接口与 SDK 方法
• 非 SDK 对接说明
• 企雀开放平台文档目录

文档组织参考 GitHub REST API 入门、GitHub 排错指南和 Postman Collection Runner 的分步接入与问题定位方式；企雀的字段和行为以本页及具体接口说明为准。