PHP版-接入钉钉审批

示例框架 laravel 5.x + 官方sdk + 钉钉小程序

如果不使用官方SDK包 可通过composer安装插件(非官方开发)
插件地址：https://github.com/mingyoung/dingtalk

钉钉步骤

1、注册企业钉钉
2、按照文档：https://ding-doc.dingtalk.com/doc#/serverapi2/dr0du9 根据自身需求 选择创建微应用H5 or 钉钉小程序(我选择小程序)
3、应用首页中设置IP白名单，安全URL，接口权限(我选择通讯录,审批等权限)，创建审批模板流程等
Ps：创建审批模板的时候可以在url中获取PROCESS_CODE，发起审批的必传参数
4、通过创建钉钉小程序得到corpid AppKey AppSecret 用于获取token等

框架步骤

1、下载钉钉sdk-php版(https://ding-doc.dingtalk.com/doc#/faquestions/vzbp02)
2、解压后删除无用文件 aliyun,QimenCloud 两个目录后，重命名目录 dingdingsdk
3、将sdk放入到自己合适的项目目录下(我选择extend目录)
4、修改根目录 composer.json文件，autoload字段的files值 新增extend//dingdingsdk/TopSdk.php用于框架自动加载
5、命令行 根目录下运行 composer dump-autoload 更新加载器
6、.env文件添加自己需要用到的配置常量

例如：
DINGDING_DEV 如不设置 默认为调用测试模板 TRUE则为线上
DINGDING_KEY 钉钉key  - 开发后台->应用首页->应用详情
DINGDING_SECRET 钉钉服务的secret - 开发后台->应用首页->应用详情
DINGDING_CALLBACKURL 钉钉审批事件回调地址 - 线上审批回调地址(测试地址为：https://wyx.jinshuizhiguan.com/api/admin/dingdingcallback)
DINGDING_TOKEN 加解密需要用到的token，ISV(服务提供商)推荐使用注册套件时填写的token，普通企业可以随机填写+-*//*-
DINGDING_AESKEY 数据加密密钥。用于回调数据的加密，长度固定为43个字符，从a-z, A-Z, 0-9共62个字符中选取,您可以随机生成，ISV(服务提供商)推荐使用注册套件时填写的EncodingAESKey  或者自己写43个字符，例如(测试)：xxxx2222lvdhntotr3x9qhlbytb18zyz5zxxxxxxxxx
DINGDING_SUITEKEY 使用注册时 CorpId 即可(开发者后台首页)

7、可以在sdk目录创建一个共用api

调用钉钉接口(在线测试平台中有不同代码版本的调用示例)：

1、发起审批需要有对应的模板ID 例如：PROC-2604BD64-F743-4847-A497-20D35F04NCN8
2、实例化 & 获取钉钉token 因为自动加载 可以直接调用方法

//前面要加 ‘ \ ’    \DingTalkConstant::$METHOD_POST 请求类型 可以在调用之前进行修改
$dingding = new \DingTalkClient(\DingTalkConstant::$CALL_TYPE_OAPI, \DingTalkConstant::$METHOD_POST , \DingTalkConstant::$FORMAT_JSON);

//获取token 使用自己小程序的key & secret
$req = new \OapiGettokenRequest;
$req->setAppkey(env('DINGDING_KEY', 'dingxxxxxxxxxxx'));
$req->setAppsecret(env('DINGDING_SECRET', 'xxxxxxxxxxxxxxxx'));
//重新设置请求类型为 GET
$dingding->httpMethod = 'GET';
//第二参数为token 没有时候传null 第三参数为请求地址 文档中有示例
$resp = $dingding->execute($req, null, "https://oapi.dingtalk.com/gettoken");
//如果请求IP不在白名单中 则返回格式为 code  msg ，errcode可能没有这个参数，这点要注意(第一处 踩坑)  格式均为json返回
if(isset($resp->errcode) && $resp->errcode == 0)
{
   return $resp->access_token;
}
//完整返回值
{
    "errcode": 0,
    "errmsg": "ok",
    "access_token": "fw8ef8we8f76e6f7s8df8s"
}

3、所有接口调用 在官方文档中均有示例，如果想要得到PHP版 可以从在线接口测试平台得到，下面举例发起审批

$req = new \OapiProcessinstanceCreateRequest;
$processCode = 'PROC-2604BD64-F743-4847-A497-20D35F04NCN8';
$req->setProcessCode($processCode); //审批模板唯一标识码
//如果没有钉钉ID 可以通过 通讯录->用户管理 根据手机号获取 文档：[https://ding-doc.dingtalk.com/doc#/serverapi2/ege851/soV11] 
$req->setOriginatorUserId(这里为钉钉ID); //发起人ID
//发起人所在部门可以根据钉钉userid获取 接口文档：
$req->setDeptId(部门ID); 
//添加表单这里 一定一定要注意格式 官方文档中没有提到多个的例子
$data = [];
foreach($params['list'] as $key => $item)
{
   $form = new \FormComponentValueVo; //设置表单参数
   $form->name=$item['name']; //每一栏名称
   $form->value=$item['value']; //每一栏值
   $data = array_merge($data, [$form]);
}
//表单参数
$req->setFormComponentValues($data);
$dingding>httpMethod = 'POST'; //修改请求方式
$resp = $dingding->execute($req,上面获取的access_token,"https://oapi.dingtalk.com/topapi/processinstance/create");

4、注册回调事件, 因为只用到了 审批，所以此处只注册了审批的回调
bpms_task_change：发起的审批通过和拒绝，返回的事件类型bpms_instance_change：发起的审批撤销了，返回的事件类型
钉钉的回调事件 可以进行删除(整体删除)，修改，也可以获取已经注册回调的参数详情 ，可以参考文档

$req = new \OapiCallBackRegisterCallBackRequest;
//此处传递的监听事件，根据自己需求选择，切记 切记 切记 传参是个字符串，里面是个数组(第二处 踩坑)。。。。官方举例只有单个“bpms_task_change” 类似于这种
$req->setCallBackTag("['bpms_task_change','bpms_instance_change']");
$req->setToken(加解密用的token 自行设置);
$req->setAesKey(aes_key 上面有格式举例，自行设置);
//回调URL地址 必须为公网
$req->setUrl(回调的公网地址);
$dingding->httpMethod = 'POST'; //设置请求方式
$resp = $dingding->execute($req,上面获取的access_token, "https://oapi.dingtalk.com/call_back/register_call_back");

5、当注册成功后 钉钉官方会进行请求，确认接口是否可用，此时 需要给官方返回字符串 success 的加密串 ，进行确认。加/解密可以看参考资料 记得替换函数。

tail -f 观察nginx请求日志可以得到回调信息，使用命令行在本地测试请求：
curl 'http://www.zbkj_site.com/api/admin/dingdingcallback?signature=54028798ed15a239ffa4ec8e3008791ae0c67528×tamp=1592887313454&nonce=IkK7MCr5' -d '{"encrypt":"uuAEcGOkIZ1l7ymCqVQBk+iZcgUVV+OK9vC3r/kcdZV+1PLREsqKsdn05UdmFn+GI6dWM8JQZ1e7vfVQTBggwTqXnNFPZfIHIoCAyz2s+zDf5HXKyh6lFeg03T54L+es"}' -H 'Content-Type:application/json'

encrypt 解密后
   $data =  array(2) {
      ["errCode"]=>
      int(0)
      ["msg"]=>
      string(25) "{"EventType":"check_url"}"
    }

解密出来的msg 进行 $eventMsg = json_decode($data['msg']);
$eventType = $eventMsg['EventType'];
//通过switch进行判断，对应的case 中书写自己的逻辑，数据状态扭转等
switch($eventType)
            {
                case "bpms_task_change":
                    //审批任务开始，结束，转交

                    break;
                case "bpms_instance_change":
                    //审批实例开始，结束

                    break;
            }
调用官方demo的加密方法
$timestamp， $nonce 用官方传递给我们的就可以，直接echo输出返回
echo EncryptMsg('success', $timestamp, $nonce, '');

参考资料：
官方文档：https://ding-doc.dingtalk.com/doc#/serverapi2/dr0du9
在线调试地址：https://open-dev.dingtalk.com/apiExplorer#/?devType=org&api=/processinstance/create
错误码：https://ding-doc.dingtalk.com/doc#/faquestions/rftpfg
权限申请：https://ding-doc.dingtalk.com/doc#/serverapi2/ca8r99
审批接入：https://ding-doc.dingtalk.com/doc#/serverapi2/tvu5f4
创建模板：https://ding-doc.dingtalk.com/doc#/serverapi2/tvu5f4
EncodingAESKey说明：https://ding-doc.dingtalk.com/doc#/faquestions/ltr370
替换mcrypt 7.1版本之后已经被遗弃：https://blog.csdn.net/zfh168/article/details/83028183
钉钉加/解密php-demo：https://github.com/injekt/openapi-demo-php/tree/master/isv/crypto