接口开发

本接口说明文档的目的是描述清楚 ERP 数据同步平台接口目前支持的几种接口说明（包括主动调异构系统创建/修改接口推送信息、按时间段轮询异构系统增量数据、提供创建/修改接口被动接收异构系统推送信息三种同步方式），供对接开发者使用，作为对接开发的依据，以避免双方沟通上的差异。

接口查看方法：登陆 CRM，进入管理>系统管理>系统对接管理>ERP 数据同步>数据同步设置进入后在 ERP 对象管理页签下，新建中间表对象后，配置完 ERP 侧对象的字段后返回，点击该对象右侧操作列的生成api 按钮，即可查看到对应对象的接口格式；

指 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](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](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"
    }
  }
}

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": [
      {
        "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"
            }
          ]
        }
      }
    ]
  }
}

接口路径: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": {
    "objAPIName": "ERP 侧对象的 APIName",
    "masterFieldVal": {
      "Key10": "value10",
      "Key11": "value11",
      "Key12": "value12"
    },
    "detailFieldVals": {
      "明细 apiName1": [
        {
          "Key13": "value13",
          "Key14": "value14",
          "Key15": "value15"
        }
      ],
      "明细 apiName2": [
        {
          "Key13": "value16",
          "Key14": "value17 ",
          "Key15": "value18"
        }
      ]
    }
  }
}

指异构系统创建/修改业务单据后，按两种不同的格式（标准格式/非标准格式）将数据推送到 ERP 数据同步平台。ERP 数据同步平台被动接收方式下，要求异构系统推送的数据 Header 参数内容必须按照如下标准格式/非标格式两种方式的一种。若采用异构系统主动推送方式，推荐异构系统优先使用标准格式推送数据。接口查看方法参见 ERP 数据同步平台接口查看/生成方式部分；

推送执行逻辑：外部接口主动调用集成平台的推送接口把数据推送的到集成平台的缓存里。平台会** __异步的从缓存表拉取数据，如果写入缓存表失败则直接返回报错信息，如果是从缓存拉取数据后处理失败需要到集成平台的数据维护里面查看数据错误原因。

注：标准格式和非标准格式是根据异构系统推送数据的格式区分。两种格式下，对推送信息的 Header 参数都有要求（标准格式要求 header 提供数据 id），但非标准格式对推送信息的 body 部分无要求，而标准格式的 body 部分也必须按照平台要求格式提供，具体见下说明：

接口路径: //www.sxgtbz.com/erp/syncdata/open/objdata/asyncpush

请求方式：POST

数据格式：仅支持 json 数据格式；

请求 Header 参数：（参数获取可以点击ERP对象列表中任意一个对象的生成api按钮，进入的推送的接口说明即可以查看到相关的参数）

字段	说明
token	请求认证字符串【请联系纷享研发侧提供】
tenantId	CRM的企业ei
dataCenterId	单账套不需要推送该字段，多账套必须推送并填写；
objectApiName	ERP 侧真实的对象名称数据同步设置->ERP 对象设置->ERP 对象编码可以找到
version	v1
operationType	3 作废，其他状态不需要推送该字段；
id【小写 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": "成功"
}

接口路径: //www.sxgtbz.com/erp/syncdata/open/objdata/asyncpush

数据格式：支持 xml.text.json 等多种数据格式，推荐使用 json 格式；

请求 Header 参数：

字段	说明
token	请求认证字符串【请联系纷享研发侧提供】
tenantId	CRM的企业ei
dataCenterId	单账套不需要推送该字段，多账套必须推送并填写；
objectApiName	ERP 侧真实的对象名称数据同步设置->ERP 对象设置->ERP 对象编码可以找到
version	v1
operationType	3 作废，其他状态不需要推送该字段；

请求格式：无限制

__response 示例（注：成功的 errCode 为 s106240000，其他的为失败）：

{
  "errCode": "s106240000",
  "errMsg": "成功"
}

自定义函数可以插入/修改/查询数据映射表，函数例子如下：

Map header=[:] //创建数据映射 Map param1=["ployDetailId":"155bd981457343f291e0edc13776217f",//策略明细id，如果策略被删除重新建了，这里需要改动 "sourceObjectApiName":"AccountObj",//源对象apiName，如果对象apiName变了，这里要改动 "destObjectApiName":"BD_Customer.BillHead",//目标对象apiName（虚拟的），如果对象apiName变了，这里要改动 "sourceDataId":"sourceDataId123",//源对象数据id "destDataId":"destDataId123666",//目标对象数据id "sourceDataName":"sourceDataName3666",//源对象数据name属性 "destDataName":"destDataName66",//目标对象数据name属性 "remark":"remark1341"];//备注 def result1=Fx.proxy.callAPI("erp.syncData.createSyncDataMapping",header,param1); //[false, HttpResult(statusCode=200, content={"errCode":"s106240000","errMsg":"成功"}, bytes=null), ] s106240000成功，其他失败 log.info(result1)
//根据源对象数据id更新目标对象数据id Map param2=["sourceObjectApiName":"AccountObj",//源对象apiName，如果对象apiName变了，这里要改动 "destObjectApiName":"BD_Customer.BillHead",//目标对象apiName（虚拟的），如果对象apiName变了，这里要改动 "sourceDataId":"sourceDataId123",//源对象数据id "destDataId":"destDataId123666"]//目标对象数据id def result2=Fx.proxy.callAPI("erp.syncData.updateSyncDataMapping",header,param2); //[false, HttpResult(statusCode=200, content={"errCode":"s106240000","errMsg":"成功"}, bytes=null), ] s106240000成功，其他失败 log.info(result2)
//查询源对象数据id是否存在映射关系 Map param3=["sourceObjectApiName":"AccountObj",//源对象apiName，如果对象apiName变了，这里要改动 "destObjectApiName":"BD_Customer.BillHead",//目标对象apiName（虚拟的），如果对象apiName变了，这里要改动 "sourceDataId":["sourceDataId123"]]//源对象数据ids,List //如果需要查询目标对象数据id是否存在映射关系，把sourceDataId改成destDataId,如果两个都传只会根据源数据id查询 def result3=Fx.proxy.callAPI("erp.syncData.getSyncDataMappingBySourceDataId",header,param3); // [false, HttpResult(statusCode=200, content={"data":{"sourceDataId123": //{"sourceDataId":"sourceDataId123","isCreated":true,"destDataId":"destDataId123666","sourceDataName":"sourceDataName1233","updateTime":1611047455451,"lastSyncStatus":6, //"destDataName":"destDataName123","destTenantId":"81138","sourceObjectApiName":"AccountObj","destObjectApiName":"BD_Customer.BillHead","sourceTenantId":"81138", //"statusName":"新增成功","id":"aa46ed320312476485e932a1ca4b4263","lastSyncDataId":"92c86fb175254e54b990bd86b6ce1145","status":1}},"errCode":"s106240000","errMsg":"成功"}, bytes=null), ] //s106240000成功，其他失败 //data是一个Map,存储着存在映射关系的数据，key是源数据id，value是已存在的对应关系， log.info(result3)

//channel合法值有 ERP_K3CLOUD,ERP_SAP,ERP_U8,OA,STANDARD_CHANNEL //"dataType":"employee" 表示新建的是人员 //dataCenterId是数据中心id //fsDataId是crm上的数据id.对于人员，这里是员工ID，不是crm人员对象的数据id. //erpDataId是erp上的数据id //fsDataName是crm的数据名称 //erpDataName是erp上的数据名称
Map data = ["dataCenterId":"数据中心id", "channel":"ERP_K3CLOUD","dataType":"employee", "fsDataId":"fsDataId","fsDataName":"fsDataName","erpDataId":"erpDataId","erpDataName":"erpDataName"];
def ret = Fx.proxy.callAPI("erp.syncData.createErpfieldmapping", [:], data); Fx.log.info("ret is : "+ret)

2024-05-22

接口开发

一、集成平台接口查看/生成方式

二、集成平台推送

2.1 创建接口

2.2 修改接口

三、集成平台轮询

3.1 批量查询请求

3.2 单个查询请求

四、集成平台接收

4.1 标准格式推送数据接口说明

4.2 非标准格式推送数据接口说明

五、数据中间表开放接口能力

六、自定义函数新建erp字段映射表

本页目录