法大大电子合同云API文档

概要说明

对于一些非实时处理或系统中有关心的事件发生的场景，法大大平台通过HTTPS回调方式向应用推送事件消息，例如实名绑定事件、填写完成事件、签署完成事件等信息，可以让应用更好地与法大大平台集成。

云苍穹接收回调API配置

通知请求格式

开放平台配置自定义接口，请求参数和返回都不需要填写取默认值，开放匿名访问，业务处理在插件fdd.fasc.web.formplugin.signtask.webapi.CallbackApiPlugin

数据从bizContent中读取

法大大配置

该接口服务需要支持http post，法大大将事件消息推送到该Web服务。

回调地址格式：schema://{host}:{port}/{path}

注意：回调地址必须是可以由外网访问的

法大大企业工作台-集成-应用详情-事件订阅中，维护异步通知地址，并根据自身业务需求订阅业务事件。

回调通知格式

通知请求格式

注意：

通知请求格式中，参数类型为header表示该参数放在http请求头当中，参数类型body为http表单参数

表单中bizContent参数格式示例(以事件列表中-个人用户授权事件为例)：

{

    "eventTime": "1648174466368",

    "signature": "xxxx",

    "openUserId": "xxxx",

    "authResult": "success",

    "authScope": [

        "ident_info"

    ],    

    "identMethod": "face",    

    "identProcessStatus": "success",}

通知响应格式

当集成方的Web服务收到通知请求后，返回HTTP 200状态码响应，且body中包含success，法大大才会判定此事件通知成功。

body中格式建议：

{"msg":"success"}

接收回调代码示例(JAVA)

@ResponseBody@PostMapping(value = "path")public String fddEventCallback(@RequestHeader HttpHeaders headers,

                         @RequestParam("bizContent") String bizContent) {

    //appSecret，由开发者登陆到法大大官网，在应用管理管理中点击应用详情里面获取

    String appSecret = "xxxx";

    //获取请求头参数

    String appId = headers.getFirst("X-FASC-App-Id");

    String signType = headers.getFirst("X-FASC-Sign-Type");

    String sign = headers.getFirst("X-FASC-Sign");

    String timestamp = headers.getFirst("X-FASC-Timestamp");

    //事件名称，开发者可以根据不同事件名称去解析bizContent的值，实现不同的逻辑

    String event = headers.getFirst("X-FASC-Event");

    String nonce = headers.getFirst("X-FASC-Nonce");

    //验签

    Map<String, String> paramMap = new HashMap<>();

      paramMap.put("X-FASC-App-Id", appId);

    paramMap.put("X-FASC-Sign-Type", "HMAC-SHA256");

    paramMap.put("X-FASC-Timestamp", timestamp);

    paramMap.put("X-FASC-Nonce", nonce);

    paramMap.put("X-FASC-Event", event);

    paramMap.put("bizContent", bizContent);

    //参数排序，ascii码排序

    String sortParam = FddCryptUtil.sortParameters(paraMap);

    //生成签名后可以进行校验

    String signature =  FddCryptUtil.sign(sortParam, timestamp, appSecret);

    if(signature.equals(sign)) {

        //log.error("日志记录，签名失败");

        //为了不重复接收该请求，建议这里返回success，返回success后这条消息法大大将中断重试回调机制

        return "{\"msg\":\"success\"}";

    }

    return "{\"msg\":\"success\"}";

}

回调通知安全机制

为了保证接收事件回调Web服务的安全性，法大大提供两种机制保证。

IP白名单

为了防止回调服务被攻击，集成方需要在接收事件回调的Web服务配上IP白名单：

回调数据带上签名计算

集成方在接收回调事件时，可以对整个回调请求进行签名计算。

异步通知计算签名代码示例(以事件列表中-个人用户授权事件为例):

    //appSecret 业务一应用<AppId, AppSecret>对中的秘钥AppSecret

    String appSecret = "XXXXXX";

    //随机数

    String nonce = UUIDGenerator.getUUID();

    //Unix标准时间戳

    String timestamp = Long.toString(System.currentTimeMillis());

    //表单里面得bizContent参数

    String bizeContent = "json字符串";

    //参与签名计算的Key-Value列表

    Map<String, String> paramMap = new HashMap<>();

      paramMap.put("X-FASC-App-Id", appId);

    paramMap.put("X-FASC-Sign-Type", "HMAC-SHA256");

    paramMap.put("X-FASC-Timestamp", timestamp);

    paramMap.put("X-FASC-Nonce", nonce);

    paramMap.put("X-FASC-Event", "user-authorize");

    paramMap.put("bizContent", bizContent);

    //得到排序后的字符串，FddCryptUtil为法大大提供得签名工具类

    String paramToSignStr = FddCryptUtil.sortParameters(paramMap);

    //计算之后得到签名 该签名需要放到请求头

    String signature = FddCryptUtil.sign(paramToSignStr, timestamp, appSecret);

回调事件列表

详情见FASC OpenAPI (服务端) V5.1：

https://dev.fadada.com/api-doc/L6ZJYQLBPC/UHNUHNUCSZLSYN4J/5-1