用户数据推送同步相关接口文档
目录
1概述
1.1请求规则
| 规则名称 | 描述 |
|---|---|
| 请求地址(测试环境) | 由接收分发数据系统提供 |
| 请求方式 | GET/POST |
| 参数格式 | application/json |
| 字符编码 | 统一采用UTF-8字符编码 |
1.2安全控制
系统采用如下方式保证产品需求方平台的安全性
- 平台各接口支持HTTPS协议。
- 访问任意接口都需要验证签名才能访问。
2 企业信息同步接口
2.1新增-编辑企业信息同步
- 接口地址
/api/datapush/enterpriseUpdate`
功能说明
当系统在平台企业新增、修改时，分发推送到相关业务系统请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| virtId | string | 是 | oUdulwb0saPji7MF_PpJLDhQ8oYM | 企业ID |
| orgId | int | 是 | 项目 ID | |
| virtCode | string | 否 | 企业编码 | |
| virtName | string | 是 | 企业名称 | |
| createTime | string | 是 | 创建时间 | |
| updateTime | string | 否 | 修改时间 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
2.2企业信息删除
- 接口地址
/api/datapush/enterpriseDelete`
功能说明
当系统在平台企业删除时，分发推送到相关业务系统请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| virtId | string | 是 | oUdul | 企业ID |
| virtCode | string | 否 | 企业编码 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
2.3企业信息查询
- 接口地址
/api/opendata/openinfo/enterpriseQuery
功能说明
接口由平台提供，由业务系统查询平台企业信息数据请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| orgId | int | 是 | 项目 ID | |
| startTime | string | 是 | 2023-12-01 15:00:00 | 修改开始时间 |
| endTime | string | 是 | 2024-03-01 15:00:00 | 修改结束时间 |
| pageNo | int | 是 | 0 | 从第1页开始第几页，返回条数由平台控制 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
| data | object | 否 | 返回结果,信息数组 |
data返回值说明
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| totalPage | int | 是 | 5 | 总页数 |
| totalNumber | int | 是 | 52 | 总条数 |
| dataInfos | Array | 是 | 信息数组 |
dataInfos返回值说明
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| virtId | int | 是 | 企业ID | |
| orgId | int | 是 | 项目 ID | |
| virtCode | string | 是 | 企业编码 | |
| virtName | string | 是 | 企业名称 | |
| createTime | string | 是 | 创建时间 | |
| updateTime | string | 否 | 修改时间 |
3 商户信息同步接口
3.1新增-编辑商户信息同步
- 接口地址
/api/datapush/merchantUpdate`
功能说明
当系统在平台商户新增、修改时，分发推送到相关业务系统请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| merchantId | string | 是 | oUdulwb0saPji7MF_Pp | 商户ID |
| orgId | int | 是 | 项目 ID | |
| merchantCode | string | 否 | 商户编码 | |
| merchantName | string | 是 | 企业名称 | |
| address | string | 否 | 地址 | |
| lng | decimal | 否 | 经度 | |
| lat | decimal | 否 | 维度 | |
| createTime | string | 是 | 创建时间 | |
| updateTime | string | 否 | 修改时间 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
2.2用户信息删除
- 接口地址
/api/datapush/merchantDelete
功能说明
当系统在平台商户删除时，分发推送到相关业务系统请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| merchantId | string | 是 | oUdulwb0saPji7MF_PpJLDh | 商户ID |
| merchantCode | string | 否 | 商户编码 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
2.3商户信息查询
- 接口地址
/api/opendata/openinfo/merchantQuery
功能说明
接口由平台提供，由业务系统查询平台商户数据请求方式
请求方法: POST
Content-Type: application/json
编码方式: UTF-8
- 请求参数
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| orgId | int | 是 | 项目 ID | |
| startTime | string | 是 | 2023-12-01 15:00:00 | 修改开始时间 |
| endTime | string | 否 | 2024-03-01 15:00:00 | 修改结束时间 |
| pageNo | int | 否 | 0 | 第几页 |
- 返回值
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| code | int | 是 | 200 | 响应状态码 |
| msg | string | 是 | 签名错误 | 返回状态码信息 |
| data | object | 否 | 返回结果,信息数组 |
data返回值说明
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| totalPage | int | 是 | 5 | 总页数 |
| totalNumber | int | 是 | 52 | 总条数 |
| dataInfos | Array | 是 | 用户信息数组 |
dataInfos返回值说明
| 参数名称 | 参数类型 | 是否必须 | 示例值 | 描述 |
|---|---|---|---|---|
| merchantId | string | 是 | oUdulwb0saPji7MF_Pp | 商户ID |
| orgId | String | 是 | 项目 ID 可以多个逗号隔开 | |
| merchantCode | string | 否 | 商户编码 | |
| merchantName | string | 是 | 企业名称 | |
| address | string | 否 | 地址 | |
| lng | decimal | 否 | 经度 | |
| lat | decimal | 否 | 维度 | |
| createTime | string | 是 | 创建时间 | |
| updateTime | string | 否 | 修改时间 |
3签名规则
3.1签名介绍
调用接口都需要携带签名,服务端会根据请求参数,对签名进行校验,签名不合法的请求将会被拒绝。
3.2签名方法
以接口/api/opendata/userQuery为例
请求的参数如下
appKey：
fwzc8EtxzIfX9Ql3Hmghtimestamp：
1680580829000userId：
ZZGX20230404173443981
平台方提供的密钥secretKey为77f44bf82004154f763a2eb4fa096487a017fe9c
- 将请求参数中除appKey、sign外的多个键值对,根据键按照字典序排序,并按照
key1=value1&key2=value2...的格式拼成一个字符串。
string str = "userId=ZZGX20230404173443981×tamp=1680580829000";- 将secretKey拼接在第一步中排序后的字符串后面得到待签名字符串。
string signTemp = str + "&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c";
//userId=ZZGX20230404173443981×tamp=1680580829000&secretKey=77f44bf82004154f763a2eb4fa096487a017fe9c- 对待签名字符串求MD5摘要并转为大写即为sign：
4CC2EB02383141C666F14D0EE681FB7A
需要注意以下规则
- 请求参数的值为空则不参与签名
- 参数名区分大小写
- appKey、sign参数不参与签名
验签和解析示例 参考
http://doc.superdesk.cn/docs/superdesk_open_api/superdesk_open_api-1fn1lgtsm5in1
附录：结果码code说明
| code状态码 | 说明 |
|---|---|
| 200 | 成功 |
| 500 | 失败 |
