ERP集成平台接口开发指引
[TOC]
| 版本 | 作者 | 日期 | 说明 |
|---|---|---|---|
| V1.0 | 刘登跃 | 2021-01-20 | |
| V1.1 | 刘登跃 | 2021-10-08 | 补充推送接口header参数说明； |
本接口说明文档的目的是描述清楚 ERP 数据同步平台接口目前支持的几种接口说明（包括 主动调异构系统创建/修改接口推送信息、按时间段轮询异构系统增量数据、提供创建/修改接口被动接收异构系统推送信息 三种同步方式），供对接开发者使用，作为对接开发的依据，以避免双方沟通上的差异。
预期读者：需求提出人员，开发人员、测试人员，项目经理。
1.ERP 数据同步平台接口查看/生成方式
接口查看方法：登陆 CRM，进入 管理>系统管理>系统对接管理>ERP 数据同步>数据同步设置 进入后在 ERP 对象管理 页签下，新建 中间表对象后，配置完 ERP 侧对象的字段后返回，点击该对象右侧操作列的 生成api 按钮，即可查看到对应对象的接口格式；
2.ERP 数据同步平台推送
指 ERP 数据同步平台监听 CRM 的 MQ 消息，当客户在 CRM 创建/修改业务单据时，CRM 会实时产生 MQ 消息通知到集成平台，平台接受消息后，实时将业务单据的数据主动推送至异构系统。接口查看方法参见 ERP 数据同步平台接口查看/生成方式部分；
创建接口
接口路径: http://MyDoman/path/create--请将 http://MyDoman/path/ 以及 curl 中地址部分替换为 ERP 厂商设置页签实际填写的 ERP 访问路径
请求方式：POST
数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；
请求格式：具体格式可以参考如下：
curl --location --request POST ' http://MyDoman/path/create' \
--header 'Content-Type: application/json' \
--header 'token: TOKEN' \
--data - raw '{
"objAPIName": "ERP 侧对象的 APIName",
"masterFieldVal": {
"Key1": "value1",
"Key2": "value2",
"Key3": "value3"
},
"detailFieldVals": {
"明细 apiName1": [{
"Key4": "value4",
"Key5": "value5",
"Key6": "value6"
}],
"明细 apiName2": [{
"Key4": "value7",
"Key5": "value8",
"Key6": "value9"
}]
}
}’
\response 示例：**
{
"code": "错误返回码",
"message": "错误提示语",
"data": {
"masterDataId": "dataid",
"detailDataIds": {
"Key10": "value10",
"Key11": "value11",
"Key12": "value12"
}
}
}
修改接口
接口路径: http://MyDoman/path/update --请将 http://MyDoman/path/ 以及 curl 中地址部分替换为 ERP 厂商设置页签实际填写的 ERP 访问路径
请求方式：POST
数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；
请求格式：具体格式可以参考如下：
curl --location --request POST ' http://MyDoman/path/update' \
--header 'Content-Type: application/json' \
--header 'token: TOKEN' \
--data - raw '{
"objAPIName": "ERP 侧对象的 APIName",
"masterFieldVal": {
"Key1": "value1",
"Key2": "value2",
"Key3": "value3"
},
"detailFieldVals": {
"明细 apiName1": [{
"Key4": "value4",
"Key5": "value5",
"Key6": "value6"
}],
"明细 apiName2": [{
"Key4": "value7",
"Key5": "value8",
"Key6": "value9"
}]
}
}'
\response 示例：**
{
"code": "错误返回码",
"message": "错误提示语",
"data": {
"masterDataId": "dataid",
"detailDataIds": {
"Key10": "value10",
"Key11": "value11",
"Key12": "value12"
}
}
}
3.ERP 数据同步平台轮询
ERP 数据同步平台主动查询需要异构系统提供批量和单个的查询接口。轮询 指指 ERP 数据同步平台以 GET 请求方式，定期的轮询异构系统批量的查询接口查询该时间段内增量的数据，可在界面设置最低 6 分钟一次。接口查看方法参见 ERP 数据同步平台接口查看/生成方式部分；
批量查询请求
接口路径:http://MyDoman/path/queryMasterBatch?objAPIName=查询 ERP 对象的 APIName&startTime=数据变更的开始时间(unix 时间戳,单位毫 秒)&endTime=数据变更的结束时间(unix 时间戳,单位毫秒)&includeDetail=true&offset=获取记录的偏移&limit=当前请求记录条数--请将 http://MyDoman/path/ 以及 curl 中地址部分替换为 ERP 厂商设置页签实际填写的 ERP 访问路径
请求方式：GET
返回数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；
请求格式：
GET http://MyDoman/path/queryMasterBatch?objAPIName=查询 ERP 对象的 APIName&startTime=数据变更的开始时间(unix 时间戳,单位毫 秒)&endTime=数据变更的结束时间(unix 时间戳,单位毫秒)&includeDetail=true&offset=获取记录的偏移&limit=当前请求记录条数
response 示例：
{
"code": "错误返回码",
"message": "错误提示语",
"data": {
"totalNum": "总记录数",
"dataList": [{
"masterFieldVal": {
"Key1": "value1",
"Key2": "value2",
"Key3": "value3"
},
"detailFieldVals": {
"明细 apiName1": [{
"Key4": "value4",
"Key5": "value5",
"Key6": "value6"
}],
"明细 apiName2": [{
"Key4": "value7",
"Key5": "value8",
"Key6": "value9"
}]
}
}]
}
}
单个查询请求
接口路径:http://MyDoman/path/queryMasterById?objAPIName=查询 ERP 侧对象的 APIName&dataId=数据 id&includeDetail=true --请将 http://MyDoman/path/ 以及 curl 中地址部分替换为 ERP 厂商设置页签实际填写的 ERP 访问路径
请求方式：GET
返回数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；
请求格式：
GET http://MyDoman/path/queryMasterById?objAPIName=查询 ERP 侧对象的 APIName&dataId=数据 id&includeDetail=true
response 示例：
{
"code": "错误返回码",
"message": "错误提示语",
"data": {
"masterFieldVal": {
"Key10": "value10",
"Key11": "value11",
"Key12": "value12"
},
"detailFieldVals": {
"明细 apiName1": [{
"Key13": "value13",
"Key14": "value14",
"Key15": "value15"
}],
"明细 apiName2": [{
"Key13": "value16",
"Key14": "value17 ",
"Key15": "value18"
}]
}
}
}
4.ERP 数据同步平台接收
指异构系统创建/修改业务单据后，按两种不同的格式（标准格式/非标准格式）将数据推送到 ERP 数据同步平台。ERP 数据同步平台被动接收方式下，要求异构系统推送的数据 Header 参数内容必须按照如下标准格式/非标格式两种方式的一种。若采用异构系统主动推送方式，推荐异构系统优先使用标准格式推送数据。接口查看方法参见 ERP 数据同步平台接口查看/生成方式部分；
推送执行逻辑：外部接口主动调用集成平台的推送接口把数据推送的到集成平台的缓存里。平台会\异步**的从缓存表拉取数据，如果写入缓存表失败则直接返回报错信息，如果是从缓存拉取数据后处理失败需要到集成平台的数据维护里面查看数据错误原因。
注：标准格式和非标准格式是根据异构系统推送数据的格式区分。两种格式下，对推送信息的 Header 参数都有要求（标准格式要求 header 提供数据 id），但非标准格式对推送信息的 body 部分无要求，而标准格式的 body 部分也必须按照平台要求格式提供，具体见下说明：
标准格式推送数据接口说明
接口路径: https://www.fxiaoke.com/erp/syncdata/open/objdata/asyncpush
请求方式：POST
数据格式：仅支持 json 数据格式；
请求 Header 参数：
| 字段 | 说明 |
|---|---|
| token | 请求认证字符串【请联系纷享研发侧提供】 |
| tenantId | 请联系纷享研发侧提供 |
| dataCenterId | 单账套不需要推送该字段，多账套必须推送并填写； |
| objectApiName | ERP 侧真实的对象名称数据同步设置->ERP 对象设置->ERP 对象编码可以找到 |
| version | v1 |
| operationType | 3 作废，其他状态不需要推送该字段； |
| id【小写 id】 | 数据 id 字段【必输字段，传输为标准数据格式时候必输。否则数据解析异常】 |
标准格式如下
请求格式：
{
"objAPIName": "ERP 侧对象的 APIName",
"masterFieldVal": {
"Key1": "value1",
"Key2": "value2",
"Key3": "value3"
},
"detailFieldVals": {
"明细 apiName1": [{
"Key4": "value4",
"Key5": "value5",
"Key6": "value6"
}],
"明细 apiName2": [{
"Key4": "value7",
"Key5": "value8",
"Key6": "value9"
}]
}
}
\response 示例**（注：成功的 errCode 为 s106240000，其他的为失败）：
{
"errCode": "s106240000",
"errMsg": "成功"
}
非标准格式推送数据接口说明
接口路径: https://www.fxiaoke.com/erp/syncdata/open/objdata/asyncpush
数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；
请求 Header 参数：
| 字段 | 说明 |
|---|---|
| token | 请求认证字符串【请联系纷享研发侧提供】 |
| tenantId | 请联系纷享研发侧提供 |
| dataCenterId | 单账套不需要推送该字段，多账套必须推送并填写； |
| objectApiName | ERP 侧真实的对象名称数据同步设置->ERP 对象设置->ERP 对象编码可以找到 |
| version | v1 |
| operationType | 3 作废，其他状态不需要推送该字段； |
请求格式：无限制
\response 示例**（注：成功的 errCode 为 s106240000，其他的为失败）：
{
"errCode": "s106240000",
"errMsg": "成功"
}