对接插件 - 插件开发

本插件用于无缝对接，实现商品目录同步、余额查询、商品下单、订单状态查询及异步回调通知。基于 HTTP + MD5 签名认证，集成方便，适合快速搭建卡网或发卡平台。
## 1. 概述

**命名空间：**  `admin\dock` 
**核心类：**  `kakayun` 
**依赖函数：** 需外部实现  `get_curl($url, $postData, $isPost=true)`  发起 POST 请求并返回响应内容。
所有接口均返回 **JSON 字符串**，调用方需自行解析。
## 2. 类与配置

插件内置元数据配置，可通过  `config()`  方法获取。

```
private $config = [
    'id' => 2,
    'class' => 'kakayun',
    'type' => 1,
    'name' => '卡卡云',
    'Version' => 1.0,
    'description' => '对接卡卡云系统的插件',
    'author' => '小蕾Gg'
];
```
 `config()`  返回上述配置的 JSON 字符串，用于系统识别插件信息。
## 3. 通信与签名机制

所有请求（除异步通知验签外）均需携带  `sign`  参数。签名算法由  `getKkySign($param, $userkey)`  实现：

- 对参数数组按键名升序排序 ( `ksort` )；
- 遍历参数，跳过空值及键名为  `sign`  的项；
- 拼接为  `key1=value1&amp;key2=value2`  格式；
- 将拼接结果与用户密钥直接拼接： `$signtext . $userkey` ；
- 计算 MD5 值作为签名。

✅ **示例：**  `$params = ['userid'=>123, 'goodsid'=>456]; $key='abc123';` 
排序后拼接:  `goodsid=456&amp;userid=123`  → MD5( `goodsid=456&amp;userid=123abc123` ) 得到签名。
## 4. API 方法详解

### 4.1 get_login($url, $appid, $key)

**功能：** 查询账户余额。
**请求接口：**  `/dockapi/index/userinfo` 
**返回示例：**

```
{
  "user_balance": "100.50"   // 或错误信息，如“网站无法正常访问”
}
```
### 4.2 getDir_list($url, $appid, $key)

**功能：** 获取商品分类目录（品牌→分组两级结构）。
**接口：**  `/dockapi/v2/getallgoodsgroup` 
**返回结构：**

```
[
  {
    "id": 10,
    "goods_name": "品牌名称",
    "color": "blue",
    "img": "http://.../brand.png",
    "stock_child": [
      { "goods_name": "分组A", "id": 101, "img": "http://..." }
    ]
  }
]
```
⚠️ 当请求失败时，方法会直接  `die()`  输出错误信息，集成时请注意捕获或确保输出缓冲区处理。
### 4.3 goods_list($url, $appid, $key, $type, $word, $page, $limit, $code, $skey)

**功能：** 分页获取商品列表（一次性拉取最多9999条，内部做内存分页）。
**参数说明：**

-  `$type=1`  时按分类ID查询， `$word`  为分类ID；否则按商品名模糊搜索。
-  `$page`  当前页码， `$limit`  每页数量。

**返回格式：**

```
{
  "code": 1,
  "data": [
    {
      "id": 123,
      "money": "15.00",
      "goods_name": "商品名称",
      "type": "提取卡密",
      "typelx": "提取卡密",
      "state": 1,
      "url": null
    }
  ],
  "count": 98
}
```
### 4.4 goodxq($url, $appid, $key, $goodsid, $code, $skey)

**功能：** 获取商品详情（包含自定义字段模板、库存、介绍等）。
**接口：**  `/dockapi/v2/goodsdetails.html` 
**返回关键字段：**

```
{
  "code": 200,
  "data": {
    "id": 456,
    "money": "29.9",
    "type": 0,          // 0=代充，1=卡密
    "templates": "QQ号", // 第一个附加字段名
    "tpl": [{"name":"区服"}],
    "kucun": 999,
    "note": "充值必填",
    "desc": "商品详情html"
  }
}
```
### 4.5 do_goods($url, $appid, $key, $code, $skey, $goodsid, $num, $input, $tradeno, $goods_type, $moneys, $host)

**功能：** 提交订单（下单）。
**参数：**

-  `$input`  : JSON字符串，存放自定义字段值，如  `{"qq":"123456"}` 
-  `$tradeno`  : 本地唯一订单号
-  `$host`  : 当前站点域名，用于构造回调URL:  `http://{$host}/Notify/ordersyn?url={$url}&amp;appid={$appid}`

**返回示例：**

```
{
  "code": 1,
  "msg": "下单成功",
  "data": {
    "order": "KK20231201001",
    "card": [{"card":"卡密内容"}]
  }
}
```
若商品为卡密类型且返回卡密列表，将自动填充到  `card`  数组中。
### 4.6 order($url, $appid, $key, $code, $skey, $order_id)

**功能：** 主动查询订单状态及退款信息。
**接口：**  `/dockapi/index/queryorder.html` 
**状态映射表：**

|卡卡云 status |插件返回 state |说明 |
|:--|
|3 |2 |已完成 |
|4 |4 |处理中 |
|5 |3 |失败 |

**退款字段：**  `tk` ：1=全部退款，2=部分退款，3=退单无退款； `tkmoney` ：-1 表示全额退，0 无退款，正数为部分退款金额。

```
{
  "code": 1,
  "data": {
    "order_id": "KK20231201001",
    "state": 2,
    "tk": 0,
    "tkmoney": 0
  }
}
```
### 4.7 verifyNotify($param, $userkey)

**功能：** 验证卡卡云异步回调请求的签名，并解析订单状态。
**调用场景：** 在回调接收脚本中，获取 POST 参数后调用此方法。
**参数：**  `$param`  为回调参数数组（包含 sign）， `$userkey`  应包含键  `sk_key`  作为密钥。
**返回：**

```
{
  "code": 200,
  "data": {
    "order_id": "本地订单号",
    "state": 2,
    "tk": 0,
    "tkmoney": 0
  }
}
```
⚠️ 当前源码中签名验证失败时未作返回，建议集成方自行补充错误响应。另外回调参数中的  `appid`  和  `url`  字段会被临时移除再计算签名。
## 5. 调用示例

```
<?php
require_once 'kakayun.php';
use admin\dock\kakayun;

$api = new kakayun();
$url = 'https://your-kakayun.com';
$appid = '10001';
$key = 'your_secret_key';

// 1. 获取目录
$dirJson = $api->getDir_list($url, $appid, $key);
$dir = json_decode($dirJson, true);

// 2. 获取某个分组下的商品列表（type=1，word=分组id）
$goodsJson = $api->goods_list($url, $appid, $key, 1, '101', 1, 20, '', '');
$list = json_decode($goodsJson, true);

// 3. 查看商品详情
$detail = $api->goodxq($url, $appid, $key, 4567, '', '');
$detailArr = json_decode($detail, true);

// 4. 下单（代充示例）
$inputFields = json_encode(['account' => 'user123']);
$orderResult = $api->do_goods(
    $url, $appid, $key, '', '', 
    4567, 1, $inputFields, 'LOCAL_ORDER_001', 0, 25.00, 'yourdomain.com'
);
print_r(json_decode($orderResult, true));

// 5. 查询订单状态
$query = $api->order($url, $appid, $key, '', '', 'KK20231201001');
echo $query;
?>
```
## 6. 集成注意事项

- **必须实现  `get_curl`  函数：** 插件依赖该函数发起 POST 请求，需返回响应体字符串。建议设置超时时间 10~30 秒。
- **异步回调地址：** 下单时传入的  `callbackurl`  必须公网可访问，接收卡卡云 POST 参数后调用  `verifyNotify`  处理，并返回字符串  `success`  或对应结果（具体以卡卡云要求为准）。
- **调试日志：** 源码中存在  `file_put_contents("kkyxd.txt", ...)`  等日志输出，生产环境请移除或改为条件日志，避免磁盘 IO 压力。
- **错误处理：**  `getDir_list`  在请求失败时会直接  `die()`  输出信息，不建议在生产环境直接终止，可修改为抛出异常或返回错误结构。
- **分页限制：**  `goods_list`  一次拉取最多 9999 条商品，若商品量极大需联系卡卡云官方调整接口或改造为支持分页参数。
- **签名与编码：** 确保 http_build_query 时使用原始格式，插件内部已将参数进行 urldecode 再发送，请注意不要重复编码。

## 7. 错误码说明

📌 所有接口返回值均为 JSON 字符串，调用后须使用  `json_decode($response, true)`  解析。
## 补充说明

**签名验证示例（异步回调）：**

```
// 假设在 Notify/ordersyn 接收脚本中
$postData = $_POST;
$kakayun = new \admin\dock\kakayun();
$userkey = ['sk_key' => '远程分配的密钥'];
$result = $kakayun->verifyNotify($postData, $userkey);
$res = json_decode($result, true);
if($res['code'] == 200){
    // 更新本地订单状态，$res['data']['order_id'] 为本地订单号
    echo 'success';
} else {
    echo 'fail';
}
```

更新于 2026-09-28 13:57 阅读 79

相关问题