1. 概述

本文档是法狗狗开放平台API对接文档，旨在给第三方平台（开发者）提供相关接口。
开发者如需使用本接口文档，需要先获取法狗狗服务 appid，appkey，用于摘要认证签名处理。

开发者配置信息

第三方平台接入法狗狗open api服务后，法狗狗将提供如下信息：

appid：用于唯一标识第三方平台
appkey：摘要认证的salt（注意：构造请求数据并签名必须在开发者服务端完成，appkey不要保存在开发者客户端/前端中，也不能从开发者服务端下发）
secret：基本认证的调用凭证（开发者如需使用法狗狗结果页，在会话过期后可通过此凭证获取新token更新会话）

接口请求host：
测试服：https://app-test.fagougou.com
正式服：https://app.fagougou.com
通知回调接口：（由第三方开发者配置或提供）

2. 摘要认证（签名校验）

摘要认证采用MD5、SHA等不可逆哈希算法对参数摘要
1.客户端通过指定的加密算法将随机数、时间戳、密钥等信息生成摘要；
2.调用请求时，将摘要放在请求头中发送给服务器；
3.服务器拿到摘要后，使用同样的算法和密钥进行摘要并对比，匹配则身份验证通过。

交互方式如下图所示：

签名生成的通用步骤

设所有发送的请求参数数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。
特别注意以下重要规则：

参数名ASCII码从小到大排序（字典序）；

参数名区分大小写；

部分请求字段非必填或条件选填，在值为空的情况下不需要参与签名；

传送的sign参数不参与签名，将生成的签名与该sign值作校验；

如果POST请求且Content-Type: application/json，需要对请求体body的json字符串进行MD5，得到 jsonDataStr 后参与签名。

如果POST请求且Content-Type: form/data，包含文件上传，传送的file文件不参与签名，需对file做MD5得到file_md5后参与签名。

在stringA末尾拼接上appkey得到stringSignTemp字符串。

生成签名：对stringSignTemp进行MD5运算，再将得到的字符串所有字符转换为小写，得到签名sign。

3. 接口调用示例

公共参数

请求头参数header

传入参数	是否必填	示例	字段说明
appid	是	xxxxxxxxxxx	开发者appid
timestamp	是	1712130669	当前时间（10位数字时间戳）
nonce	是	ibuaiVcKdpRxfgtr	16位随机字符串
sign	是	********	签名（小32位。生成方式见下方示例）

发送请求示例：

DEMO(java):

<!-- 当前demo所依赖客户端请求框架。也可以选择其它的httpclient框架 -->
<dependency>
    <groupId>org.apache.httpcomponents</groupId>
    <artifactId>httpmime</artifactId>
    <version>4.5.12</version>
</dependency>

1.GET请求示例：

步骤：

第一步：对参数按照 key=value 的格式，并按照参数名ASCII字典序排序如下

第二步：拼接API密钥key

第三步：生成签名

第四步：将sign参数加入header后即可发送API接口请求。

2.POST请求示例：(且Content-Type: application/json)

步骤：

第一步：POST请求且Content-Type: application/json，如果body内容不为空，对body的json内容进行
md5(body)，得到参数 jsonDataStr

第二步：按照 key=value 的格式，并按照参数名ASCII字典序排序如下

第三步：拼接API密钥key

第四步：生成签名

第五步：将sign参数加入header后即可发送API接口请求。

注意：body的json字符串为去除回车换行之后再进行md5。

3.POST请求示例：(Content-Type: form/data)

步骤：

第一步：如果参数包含file文件类型，需对文件进行md5加入到签名参数中，得到参数 file_md5（命名规则为xxx_md5, xxx为文件类型的参数名称）

第二步：按照 key=value 的格式，并按照参数名ASCII字典序排序如下

第三步：拼接API密钥key

第四步：生成签名

第五步：将sign参数加入header后即可发送API接口请求。

4. 回调接口说明

开发者如果需要接受消息通知，需要提供一个“通知回调接口”，法狗狗方将在开发者执行相关操作时调用此“通知回调接口”回传内容通知开发者，开发者对header和body的内容进行处理。

回调交互图

回调发出POST请求，携带参数信息说明

公共header参数：（这里是平台调用开发者系统的时候请求头中携带的内容）

字段名	位置	字段说明	取值范例
Content-Type	Header	固定值：application/json	application/json
fgg-logid	Header	统一日志id，当出现问题时可以提供此id给法狗狗研发人员协助定位问题	780d9ac6-573d-4293-b8e2-b68ad14069e2

以下参数参与签名，请参考-签名算法

字段名	位置	字段说明	取值范例
appid	Header	开发者appid	xxxxxxxxxxx
timestamp	Header	当前时间（10位数字时间戳）	1712130669
nonce	Header	16位随机字符串	ibuaiVcKdpRxfgtr
sign	Header	签名，请参考下方签名算法	******

请求body体参数示例：

{
    "status": "complete",
    "message": "任务执行成功",
    "taskId": "c89cbee0-b3e4-4734-9060-54eccbaa401e",
    "type": "compare",
    "similarity": 0,
    "diffItemsCount": 0,
    "addedCount": 0,
    "changedCount": 0,
    "removedCount": 0
}

第一步：将body请求体Json字符串转为MD5值

第二步：对参数按照 key=value 的格式，并按照参数名ASCII字典序排序如下

第三步：拼接API密钥key

第四步：生成签名

第五步：校验数据完整性

回调接口响应数据要求：

收到通知之后，响应"success" 即可。

如未收到"success" 或请求请求超时，将按如下频率再次调用：1分钟，5分钟，1小时，三次调用后不再尝试。

由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。

5. 错误码集合

类型	code	msg
用户	2002	用户不存在
用户	2003	用户已存在
鉴权	6032	无效的appid
鉴权	6033	无效的签名
鉴权	6034	无效的nonce
鉴权	6035	签名已过期
鉴权	6036	验签失败

接口签名处理说明

1. 概述#

开发者配置信息#

2. 摘要认证（签名校验）#

交互方式如下图所示：#

签名生成的通用步骤#

3. 接口调用示例#

公共参数#

请求头参数header#

发送请求示例：#

DEMO(java):#

1.GET请求示例：#

2.POST请求示例：(且Content-Type: application/json)#

3.POST请求示例：(Content-Type: form/data)#

4. 回调接口说明#

回调交互图#

回调发出POST请求，携带参数信息说明#

公共header参数：（这里是平台调用开发者系统的时候请求头中携带的内容 ）#

以下参数参与签名，请参考-签名算法#

请求body体参数示例：#

5. 错误码集合#

1. 概述

开发者配置信息

2. 摘要认证（签名校验）

交互方式如下图所示：

签名生成的通用步骤

3. 接口调用示例

公共参数

请求头参数header

发送请求示例：

DEMO(java):

1.GET请求示例：

2.POST请求示例：(且Content-Type: application/json)

3.POST请求示例：(Content-Type: form/data)

4. 回调接口说明

回调交互图

回调发出POST请求，携带参数信息说明

公共header参数：（这里是平台调用开发者系统的时候请求头中携带的内容）

以下参数参与签名，请参考-签名算法

请求body体参数示例：

5. 错误码集合