hamster_kingdee

介绍

金蝶云星空（下称星空系统）WebAPI二次封装应用，方便第三方异构系统与星空系统对接。
星空系统对单据的操作动作拆分粒度比较细，而且WebAPI字段数目多，这样很好地支持了业务管控，但是带来的问题就是操作步骤多，这些步骤还包含了星空系统的校验逻辑。给于第三方对接团队带来了极大的心理压力和工作负担，严重的会导致项目失败。因此，在实际的实施工作中，第三方基本上会要求金蝶实施方对星空系统的接口做二次封装。
本应用将常用的单据操作筛选出来，并将多个操作步骤整合到一个请求中，而且简化了字段，这样既简化了系统对接，也降低了工作人员的工作量。

软件架构

本软件使用金蝶云星空系统自定义插件机制开发而成。
开发语言：C#
环境：.NET Framework 4.0

安装教程

1. 编译项目生成Hamster.K3Cloud.WebAPI.ServerExtend.dll；
2. 复制到金蝶安装目录：\Kingdee\K3Cloud\WebSite\Bin（默认为：C:\Program Files (x86)\Kingdee\K3Cloud\WebSite\Bin）
3. 重启IIS服务器

使用说明

使用文档：《使用文档》

接口报文样例

{
	"LocalFormId": "PUR_ReceiveBill",
	"NextFormId": "STK_InStock",
	"RuleId": "PUR_ReceiveBill-STK_InStock",
	"NextQueryEntryKey": "PUR_ReceiveEntry",
	"NextEntryKey": "FInStockEntry",
    "ActionName": "PushAndUpdate",
	"IsAutoSubmitAndAudit": true,
	"Modle": {
		"FInStockEntry": [{
			"FLot": {
				"FNumber": "111"
			},
			"FNote": "测试单据体备注1",
			"FRealQty": "10",
			"FSrcBillEntryID": "113928",
			"FGiveAway": false,
			"FProduceDate": "2021-06-13 00:00:00",
			"FExpiryDate": "2025-06-13 00:00:00"
		}, {
			"FLot": {
				"FNumber": "111"
			},
			"FNote": "测试单据体备注2",
			"FRealQty": "10",
			"FSrcBillEntryID": "113931",
			"FGiveAway": false,
			"FProduceDate": "2021-06-13 00:00:00",
			"FExpiryDate": "2025-06-13 00:00:00"
		}]
	}
}

如果使用Postman等类似工具进行测试，则报文如下

{
	"parameters": [{
		"LocalFormId": "PUR_ReceiveBill",
		"NextFormId": "STK_InStock",
		"RuleId": "PUR_ReceiveBill-STK_InStock",
		"NextQueryEntryKey": "PUR_ReceiveEntry",
		"NextEntryKey": "FInStockEntry",
		"ActionName": "PushAndUpdate",
		"IsAutoSubmitAndAudit": true,
		"Model": {
			"FInStockEntry": [{
				"FLot": {
					"FNumber": "111"
				},
				"FNote": "测试单据体备注1",
				"FRealQty": "10",
				"FSrcBillEntryID": "113928",
				"FGiveAway": false,
				"FProduceDate": "2021-06-13 00:00:00",
				"FExpiryDate": "2025-06-13 00:00:00"
			}, {
				"FLot": {
					"FNumber": "111"
				},
				"FNote": "测试单据体备注2",
				"FRealQty": "10",
				"FSrcBillEntryID": "113931",
				"FGiveAway": false,
				"FProduceDate": "2021-06-13 00:00:00",
				"FExpiryDate": "2025-06-13 00:00:00"
			}]
		}
	}]
}

使用Postman等工具发送报文，需要将正式报文包含在{"parameters": []}中。

上方样例报文使用的场景：
用户在星空系统创建了一个采购收料通知单，当单据被审核之后，该单据的数据发送到了第三方系统（一般为仓库管理系统[WMS]）。当第三方系统的用户完成了这个单据的作业之后（一般为仓库收货入库），将上述报文发送到星空系统。那么插件将自动做如下操作：

1. 自动从收料通知单下推采购入库单；
2. 将批号、备注、实收数量等业务数据更新到下推的对应的分录明细中；
3. 自动提交和审核该采购入库单。

参数说明

固定参数
LocalFormId 当前单据的FormId
NextFormId 下游单据FormId
RuleId 下推规则标识串
NextQueryEntryKey 上下游单据查询标识串
NextEntryKey 分录明细Key
ActionName 动作名称
IsAutoSubmitAndAudit 是否自动提交和审核

固定参数用于指明单据的操作。
LocalFormId 和 NextFormId 是星空系统的单据ID，可以在BOS系统中查看。
RuleId 是星空系统单据下推规则，可以在BOS系统中查看。
NextQueryEntryKey 是单据关联关系表中FSTableName（源单表名）字段中的值（省略了前导 t_）。
NextEntryKey 为单据明细属性Key。
ActionName 单据操作的动作名称，当前支持以下几种动作：

1. Push 下推
2. Save 保存（创建和更新）
3. Delete 删除
4. Audit 审核
5. UnAudit 反审核
6. PushAndUpdate 下推并更新

备注说明

• 创建和更新都可以使用 Save 动作。如果 Model 中没有设置 FID 或者 FBillNo 字段的值，则为创建单据，反之则为更新。更新单据时 FID 或者 FBillNo 必须填写一项，FSrcBillEntryID（明细内码）必填；
• 使用 PushAndUpdate 动作时 固定参数NextQueryEntryKey必填。用于查找上下游单据的对应关系。

IsAutoSubmitAndAudit 是否自动提交审核

单据参数
Modle 单据字段对象
Model为单据参数集合，对应官方文档中WebAPI接口中的Model，参数格式与要求与官方文档一致。

特殊参数
FSrcBillEntryID 源单分录明细内码。此参数主要用于需要指定明细内码的操作动作，例如：更新、下推等。对应FEntryID。

说明

1. 本应用还不是很完善，支持的动作有限；
2. 没有支持撤销接口，撤销接口金蝶云星空官方在20210422 PT 146874补丁及其以后的补丁中包含；
3. 调用失败，数据回退支持不好。例如在连续动作下推->更新->提交->审核中，如果审核动作没有通过星空系统的校验，那么下推的单据无法被清理，需要手动处理，然后第三方系统再次发起请求。原因是在没有PT 146874补丁的系统，不支持撤销动作接口；
4. 保存接口还不支持新增明细分录的功能，新增明细分录的功能将在增强版中提供支持；
5. 本项目完全开源，并且没有任何使用限制，可以商用。

支持我们

如果您觉得有价值或者对您的朋友会有帮助，那么就将本项目分享出去吧。
我们也需要大家的支持

参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request