近期陆续收到一些反馈，不少客户在使用web Api接口做对接，上传客户、联系人和客户地址的时候，出现不少的疑问。在这里，简单介绍一下这三者之间的关系，以及如何使用接口上传这些数据的操作过程和步骤，通过Excel引入的操作步骤也相同，希望对大家有所帮助。
由于之前的改造，联系人数据与客户数据已做了分离，现在客户联系人和客户，实际上是相对独立的两个基础资料，在客户的联系人页签里，看到的联系人数据实际上是客户在打开的时候动态查询并加载上去的，客户的数据包里并不存储联系人的数据。因此，上传客户的时候不能同时上传联系人，必须分开操作，即第一步先上传客户资料，第二步再上传联系人，第三步才上传客户地址或者给客户地址信息里的联系人字段进行赋值或者设置默认联系人。相关的改造介绍请参考以下帖子：客户联系人的近期改造说明介绍
第一步：上传客户资料。
通过web API，调用客户的保存接口，传入新增客户的数据资料。但请注意，由于联系人数据在这一步里不能同时传入，且客户数据包里的联系人页签是没有物理表的，所以，这一步中请勿对联系人相关字段传值，即删除客户保存的JSON数据里的"FT_BD_CUSTLOCATION"代码块部分。
补充说明，在补丁版本PT-146915 [8.0.0.202206]之前，通过API上传联系人（带地点名称和详细地址）后，还不会自动同步到地址信息页签，在这一步，可以先行上传客户地址，但由于现在还没有客户联系人，因此，这一步中客户地址中的联系人字段先留空不传。
更新补丁版本PT-146915 [8.0.0.202206]或更新补丁后，通过API上传联系人（带地点名称和详细地址）后，实现了自动同步到地址信息页签，此时在这一步，就无需上床客户地址，即删除客户保存的JSON里的 "FT_BD_CUSTCONTACT"代码块部分。
自动同步的过程需要用到地点编码字段做关联条件，因此，不允许同一个客户内地点编码重复，历史数据中可能存在同一个客户地点编码重复的可能性，遇到这种数据时，自动同步就会失败并有报错，需要做数据处理，将地点编码修复成不重复，最新版本的补丁中已增加了保存校验，不允许同一个客户内地点编码重复。
JOSN数据代码示例如下：
{
"NeedUpDateFields": [],
"NeedReturnFields": [],
"IsDeleteEntry": "true",
"SubSystemId": "",
"IsVerifyBaseDataField": "false",
"IsEntryBatchFill": "true",
"ValidateFlag": "true",
"NumberSearch": "true",
"InterationFlags": "",
"Model": {
"FCUSTID": 0,
"FCreateOrgId": {
"FNumber": "103"
},
"FUseOrgId": {
"FNumber": "103"
},
"FName": "测试客户",
"FCOUNTRY": {
"FNumber": "China"
},
"FINVOICETITLE": "测试客户",
"FIsGroup": false,
"FIsDefPayer": false,
"FCustTypeId": {
"FNumber": "KHLB001_SYS"
},
"FTRADINGCURRID": {
"FNumber": "PRE001"
},
"FInvoiceType": "1",
"FTaxType": {
"FNumber": "SFL02_SYS"
},
"FPriority": 1,
"FTaxRate": {
"FNumber": "SL02_SYS"
},
"FISCREDITCHECK": true,
"FIsTrade": true,
"FT_BD_CUSTOMEREXT": {
"FEnableSL": false,
"FALLOWJOINZHJ": false
},
"FT_BD_CUSTCONTACT": [
{
"FNUMBER1": "BIZ202008200905570",
"FNAME1": "测试地址",
"FADDRESS1": "测试地址",
"FMOBILE": "13788888888",
"FIsDefaultConsignee": false,
"FIsDefaultSettle": false,
"FIsDefaultPayer": false,
"FIsUsed": true
}
]
}
}
这一步，还另外需要注意的是，在基础管理和销售管理的客户列表中，默认过滤的是交易客户，对应的客户字段是FIsTrade，如果是非交易客户，在客户列表中是过滤不出来的。因此，在传客户json数据的时候，FIsTrade要设置为 true，如上述代码示例。
同时，基础资料的列表默认都是按使用组织进行数据过滤隔离，而在Web API中，使用组织字段不传值的话，默认就等于当前登陆组织。在实际应用中发现，有些客户在调用API接口的时候不会注意到当前组织与上传客户的创建组织不是同一个组织，当使用组织不传值的时候，上传之后，客户的使用组织等于当前登陆组织，而不是创建组织，因此，客户数据上传成功，但按所上传的组织进行过滤的时候，列表过滤不出来。因此，建议客户在调用客户接口的时候，注意当前登陆组织，要让当前登陆组织等于创建组织，最好直接传入客户的使用组织字段 FUseOrgId，使用组织等于创建组织。
第二步，上传联系人。
在第一步上传客户之后，返回得到客户的编码（CUST0084）和FCUSTID （641449），以及上传的客户地址的ID（100098）。上传联系人，不是调用客户的接口，而是联系人的接口，业务对象注意是不同的。联系人的业务对象是在供应链--采购管理--基础资料里的联系人 BD_CommonContact。
金蝶云星空有一个在线Web API功能，可以查阅对应API接口的参数说明和代码示例。
在这个功能里，左边的树结构里的各个业务对象，都是已发布到主控台菜单里的业务对象，未发布的业务对象在这里是看不到。不过发布与否，只影响在这个功能里直接使用，客户用代码发起API调用是不影响的。联系人的业务对象在2020年8月份补丁之前的版本里，默认是未发布的，因此在这个功能里是看不到联系人对象的，8月份补丁标准产品里已默认发布，可以直接查看并使用。因此8月份补丁之前的版本客户，如果需要在web API功能里测试并查看联系人接口的代码示例，需要先自行通过BOS设计器将联系人发布为不可见主控台菜单。发布示例如下：
打开BOS设计器，在BOS设计器的最上方菜单栏点击发布下拉按钮，选择发布到主控台，在弹出来的功能发布管理里，依次选择供应链--采购管理--基础资料，点击下方列表的新增按钮，在主控台功能维护里，编码和名称可以自定义编辑，勾选桌面端和浏览器，业务对象要选联系人（BD_CommonContact），可见性里勾选全部去掉，编辑完毕之后，保存即可。如下图：
联系人对象发布主控台菜单完毕之后，遍可以直接在web API功能里看到该对象，可以直接测试接口并查阅接口参数数量和代码示例。联系人的保存接口代码示例如下：
{
"NeedUpDateFields": [],
"NeedReturnFields": [],
"IsDeleteEntry": "true",
"SubSystemId": "",
"IsVerifyBaseDataField": "false",
"IsEntryBatchFill": "true",
"ValidateFlag": "true",
"NumberSearch": "true",
"InterationFlags": "",
"Model": {
"FCONTACTID": 0,
"FName": "测试联系人",
"Fex": {
"FNumber": "SEX01_SYS"
},
"FCompanyType": "BD_Customer",
"FCompany": {
"FNumber": "CUST0084"
},
"FMobile": "13788888888",
"FEmail": "aaaa@qq.com",
"FBizAddress": "测试地址",
"FBizLocation": "测试地址",
"FBizLocNumber": "BIZ202008200905570"
}
}
联系人的保存接口在构建上述Json数据的时候，要注意以下几点：联系人与客户的联系是通过联系人里的类型字段（FCompanyType）以及所属公司（FCompany）来建立联系的，传入联系人的数据时，首先要注意这两个字段的顺序，必须是先传入类型（FCompanyType），再传入所属公司（FCompany），顺序不可改变。类型传入常量 BD_Customer，所属公司按基础资料字段的传值方式传入客户的编码，如 CUST0084。
第三步，设置客户地址里的联系人或者新上传地址或者设置默认联系人
特别再次说明：更新补丁版本PT-146915 [8.0.0.202206]或更新补丁后，第二步操作上传客户联系人后，系统会自动同步带地址名称和详细地址的联系人信息到地址信息页签，此时，这个第三步操作无需执行。
由于客户地址是客户的所属页签，默认联系人是客户商务信息里的默认联系人字段，它们都是客户数据包里一部分内容，因此，这个时候需要再次调用客户的保存接口，传入客户的FCUSTID，使用保存接口做修改操作，对这部分数据进行修改或新增。代码示例如下：
{
"NeedUpDateFields": [],
"NeedReturnFields": [],
"IsDeleteEntry": "false",
"SubSystemId": "",
"IsVerifyBaseDataField": "false",
"IsEntryBatchFill": "true",
"ValidateFlag": "true",
"NumberSearch": "true",
"InterationFlags": "",
"Model": {
"FCUSTID": 641449,
"FT_BD_CUSTOMEREXT": {
"FEntryId": 102034,
"FDefaultContact": {
"FNUMBER": "CXR000049"
}
},
"FT_BD_CUSTCONTACT": [{
"FENTRYID": 100098,
"FTContact": {
"FNAME": "测试联系人"
}
},
{
"FENTRYID": 0,
"FNUMBER1": "BIZ202008200905580",
"FNAME1": "测试地址2",
"FADDRESS1": "测试地址2",
"FTRANSLEADTIME1": 0,
"FTContact": {
"FNAME": "测试联系人"
},
"FMOBILE": "",
"FIsDefaultConsignee": "false",
"FIsDefaultSettle": "false",
"FIsDefaultPayer": "false",
"FIsUsed": "true"
}
]
}
}
在保存操作做修改时，只需要传入管理的ID字段和所需要修改的字段即可，其他不做修改的字段无需传入，如上述示例代码中，需要传入需要修改的客户的ID（"FCUSTID": 641449,），本次修改做的操作是设置默认联系人，传入商务信息代码块，传入商务信息数据的ID，以及默认联系人字段，传值是联系人的编码 CXR000049
"FT_BD_CUSTOMEREXT": {
"FEntryId": 102034,
"FDefaultContact": {
"FNUMBER": "CXR000049"
}
},
同时，对新增客户时候已传入的客户地址赋值客户地址联系人，传入客户地址ID和联系人字段
{
"FENTRYID": 100098,
"FTContact": {
"FNAME": "测试联系人"
}
},
但注意客户地址里的联系人字段传值使用的联系人姓名 测试联系人，之所以与默认联系人的传值不同，是由于这里传值的内容是由BOS设计器里，对应基础资料的关联检索字段属性设置的，默认联系人字段的关联检索字段设置了编码，而客户地址里的联系人字段的关联检索字段设置了姓名，有所不同，因此传值有所不同，客户可以通过代码示例和BOS设计器里的字段属性设置来查阅需要传入的内容。
上述代码在修改客户地址，赋值联系人字段的同时，也新增了一行新的客户地址，对于新的客户地址的新增，只需要传入地址ID为0即可，ID为0做新增，ID为大于0且等于已存在的字段ID，则做修改，这个就是API里保存接口的操作原理。
但是，需要特别注意的是，在接口的参数中，有一个IsDeleteEntry，是否删除分录，这个参数的用法是：如果 IsDeleteEntry=true，会删除分录中未传入的数据，IsDeleteEntry=false，不删除未传入的分录，仅做新增，因此，如果要在修改操作里做分录数据的新增，最好设置为 IsDeleteEntry: false，避免删除已存在的分录数据。
推荐阅读