本文由hhw_1979贡献
doc文档可能在WAP端浏览体验不佳。建议您优先选择TXT，或下载源文件到本机查看。
U8API U8API 开发手册
作者：李静、 作者：李静、袁昌龙 版本号：V872 版本号： 时间：2008 10时间：2008-10-07 版权所有： 版权所有：用友软件股份有限公司
1.简介 1.简介
U8API 是为 U8 客户化应用开发提供的一套标准化的 U8ERP 业务编程接口。是 U8UAP 二 次开发体系的重要组成部分。它包括一整套涵盖 U8ERP 采购、销售、库存、制造（规划中） 、 财务（规划中） 、基本档案（规划中）等业务模块的 API 接口资源。U8API 的推出为 U8 标准 产品更好的适应用户的个性化需求，更好的实现客户化交付提供了有力支持。 U8API 按照 U8ERP 业务产品模块进行分类，并以 U8 主要业务实体（单据、档案、凭证） 作为操作对象， 提供了常用的基本操作。 比如： 对于库存的收发单据， 提供 “新增” 、 “审核” 、 “弃审”“删除”“装载”“修改”六个 API 接口。目前，U8API 提供了供应链采购、销售、 、 、 、 库存三个产品的所有单据的增删改、审核/弃审等 API 接口，后续版本会逐步将制造、财务、 基本档案等模块的 API 纳入进来。 U8API 通过“U8API 资源管理器”对 U8 范围内所有 API 进行集中统一分类管理，形成了 一套完整的 U8API 资源库。U8API 的使用者可以使用“U8API 资源管理器”浏览、查看 API 及其接口定义，并可辅助进行代码生成（目前支持 C#和 VB 语言） ；API 的开发者可以通过此 工具发布、注册 API，所有业务 API 都必须在“U8API 资源管理器”中进行注册。 U8API 还提供了一套运行时调用框架——U8APIBroker。它是所有 U8API 的调用代理， 用户要使用某个 API 只需调用 U8APIBroker 即可，无需直接访问真正的 API。U8APIBroker 作为一个服务代理中间件， 起到了隔离 API 的提供者与使用者的作用， 降低了耦合依赖关系。 U8API 与 U8EAI 接口从功能上看比较相识，但它们的特性有差别。U8API 采用传统的编 程模型， 更靠近底层， 业务逻辑粒度更细， 而且还需要或依赖一些特定的上下文环境， 比如： login、事务等；而 U8EAI 接口则是完全松耦合的，采用 XML 和请求/响应的消息传递模式， 且业务粒度比较粗放。这些特性的差别决定了它们的应用领域不同，U8API 更适合于 U8 内 部的功能扩展和客户个性化开发，而 U8EAI 则适合外部系统与 U8 之间以业务数据交换为特 征的应用集成开发。
2.API 2.API 应用
2.1. API 总体应用过程
2.1.1 API 浏览查找
在“开始”->“程序”->“用友 ERP-U8”->“UAP”目录下找到“U8API 资源管理器” ， 单击，登录，进入“U8API
资源管理器” 。在左侧 “U8API” 树形节点下，找到某某模块， 如“库存管理”模块（可以看到下面列有很多个单据，如盘点单、采购入库单等） ，展开要 操作的单据，分两个子节点： “事件”和“服务接口” ，在“服务接口”下可以看到该单据提 供的 API 接口，如“添加新单据”“审核单据”等。双击这些节点出现该 API 的详细描述， 、 如下图 2.1 所示。在节点上右键单击弹出“上下文菜单” ，在“代码示例”菜单项上弹出下 一级子菜单，单击它们，如单击“C#代码示例”则可以看到调用该 API 的 C#示例代码，如 下图 2.2 所示。直接拷贝这些代码，然后在集成开发环境（IDE）中编辑和编译这些代码， 即能实现调用 U8 标准 API。利用这些代码示例时，请按照其中每一步骤的提示说明正确操
作， 如添加必要的引用、 按照自动生成的代码填入正确的参数等。 正确使用则可以调用成功， 否则会返回详细的错误信息。 以下代码中均以 C#为例，VB 语言请具体查看对应的 VB 代码示例部分。
图 2.1 接口描述
图 2.2 代码示例
2.1.2 API 调用过程 组件引用
针对两种语言，需要引用不同的组件。 (1) C#： %U8SOFT%\Interop\Interop.U8Login.dll、 %U8SOFT%\Interop\Interop.MSXML2.dll、%U8SOFT%\UFMOM\U8APIFramew ork\UFIDA.U8.U8APIFramework.dll、%U8SOFT%\UFMOM\U8APIFramework\ UFIDA.U8.MomServiceCommon.dll、%U8SOFT%\UFMOM\U8APIFramework\UF IDA.U8.U8MOMAPIFramework.dll 如下图 2.3、2.4、2.5 所示。 （2）VB： %U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8APIFramework. tlb 、 %U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.MomServiceCommon. tlb、%U8SOFT%\UFMOM\U8APIFramework\UFIDA.U8.U8MOMAPIFramework. tlb、 添加 Microsoft XML v3.0 引用 如下图 2.6、2.7 所示。 其中，%U8SOFT%表示 U8-872 的安装目录。
图 2.3 添加对 U8Login.dll 引用
图 2.4 添加对 Interop.MSXML2.dll 引用
图 2.5 添加对 U8API 框架类库引用（.dll）
图 2.6 添加对 U8API 框架类库引用(.tlb)
图 2.7 添加 Microsoft XML v3.0 引用
API 调用
添加必要的引用后，可以直接利用自动生成的代码示例（支持 C#和 VB 两种语言） ，结 合 API 接口详细描述，填入必要的参数值，就可以调用 U8 API。 总体上，对 U8 API 的调用分成七个步骤： 1) 构造 u8login 对象并登陆； 2) 构造环境上下文对象，传入 login，并按需设置其它上下文参数； 3) 设置 API 地址标识(Url)参数； 4) 构造 APIBroker； 5) API 参数赋值； 6) 调用 API； 7) 获取返回结果。 详细的 API 调用过程请看下文“API 内容”中各个模块中介绍的“开发步骤” 。 下面重点介绍几个关键要点和步骤：环境上下文、API 地址、APIBroker、普通参数赋 值、BO 参数赋值。
环境上下文
环境上下文指在调用 U8API 时需要初始化的调用环境，包括 Login、事务、特殊的业务 参数等。环境上下文被初始化后，相关的环境参数会被业务 API 使用。
U8EnvContext envContext = new U8EnvContext();
Login 需要将 U8Login 对象传递给环境上下文，U8Login 对象必须已经登录过。 envContext.U8Login = u8Login; 事务 如果需要由外部发起事务，则可以发起事务的 ADOConnection 对象传递给环境上下文：
ADODB.ConnectionClass conn = new ConnectionClass(); https://www.doczj.com/doc/2e14113779.html,DbConnection = conn;
同时需要设置一个外部事务标记：
envContext.IsIndependenceTransaction = true;
特殊业务参数 特殊业务参数指调用某些 API 需要设置的特定上下文参数， 比如： 销售的 API 必须要设 置如 VoucherType 上下文参数，设置方法为：
envContext.SetApiContext("VoucherType", 23);
API 地址
API 地址是指 API 在 U8API 系统中的唯一标识，也叫 API 的 URI，调用 API 时，需要通 过 API 地址构建一个代表此 API 的 Broker 对象：
U8ApiAddress myApiAddress = new U8ApiAddress("U8API/PurchaseOrder/VoucherSave");
APIBroker
APIBroker 是所有 U8API 的调用代理接口。使用 U8 所有 API 都必须通过 APIBroker 间
接调用。APIBroker 作为一个服务代理中间件，起到了隔离 API 的提供者与使用者的作用， 降低了耦合依赖关系。创建 APIBroker 必须传入 API 地址和环境上下文：
U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);
普通参数赋值
API 参数分两种类型：BO 参数和普通参数。普通参数是指非单据表头表体类型的参数， 包括基本类型参数（String、Integer 等） 、知名对象参数（Connection、DOMDocument 等） 。 普通参数的赋值采用如下方式：
broker.AssignNormalValue("voucherState", 2);
BO 参数赋值
BO 参数即单据表头或表体类型的参数。对 BO 参数，支持两种方式传入，一种传 BO 对 象，另一种传 DOM 对象。以下分别介绍： 传 BO 对象 给 BO 表头参数或表体参数赋值，推荐使用 BO 对象（BussinessObject） 。 例如：
BusinessObject DomHead = broker.GetBoParam("DomHead"); DomHead.RowCount = 10; //设置行数，不设置也可 //给 BO 对象的字段赋值，值可以是真实类型，也可以是无类型字符串 //以下代码示例只设置第一行值。各字段定义详见 API 服务接口定义 /****************************** 以下是必输字段****************************/ DomHead[0]["poid"] = ""; //主关键字段，int 类型 DomHead[0]["dpodate"] = ""; //日期，DateTime 类型 DomHead[0]["cpoid"] = ""; //订单编号，string 类型 …… /***************************** 以下是非必输字段****************************/ DomHead[0]["ipresent"] = ""; //现存量，string 类型 DomHead[0]["cmaketime"] = ""; //制
单时间，DateTime 类型 DomHead[0]["cmodifytime"] = ""; //修改时间，DateTime 类型 ……
在此种情况下 U8 API 框架会对 BO 对象各字段进行参数校验。对字段进行赋值时，值可 以是真实类型，也可以是无类型字符串。 传 DOM 对象 给 BO 表头参数或表体参数赋值，也支持直接传入 DOM 对象（DOMDocument） 。 例如：
MSXML2.DOMDocumentClass domHead = new MSXML2.DOMDocumentClass(); domHead.load("domHead.xml"); broker.AssignNormalValue("domHead", domHead);
但是，在此种情况下 U8 API 框架不会对 DOM 对象进行参数验证。请在使用该方法之前， 确保 DOM 对象的正确性。
2.1.3 API 典型应用场景 执行单一操作
单一操作指一项任务只需要一个 API 完成，比如：单据新增、审核/弃审、删除等单一 操作。这是 API 调用最常见的场景，只需按照 API 的接口规范构造参数直接调用即可。
执行复合操作
复合操作，即一项任务由多个 API 的协作来完成。比如，自定义的单据维护界面的主要 逻辑，一般由以下四个步骤构成： 1) 加载单据； 2) 在编辑界面上显示； 3) 用户修改单据字段； 4) 提交保存。 以上步骤需要进行两次 API 调用： 1) 加载单据时候调用“加载 API” ，以获取单据 BO 对象（或原始 DOM 对象）并在界面 上展现； 2) 用户在修改单据时其实就是在修改 BO 对象，用户保存单据时调用“保存 API” ，此 时要将此 BO 对象传给“保存 API” （而不用构造新的 BO 对象） 。 代码示例： 首先，登陆；
//构造 u8login 对象并登陆 U8Login.clsLogin u8Login = new U8Login.clsLogin(); String sSubId = "AS"; String sAccID = "(default)@001"; String sYear = "2008"; String sUserID = "demo"; String sPassword = ""; String sDate = "2008-09-30"; String sServer = "localhost"; String sSerial = ""; if (!u8Login.Login(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial)) { Console.WriteLine("登陆失败，原因：" + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login); return; }
然后，通过 LOAD 接口获取 BO 对象；
//构造环境上下文对象，传入login，并按需设置其它上下文参数
U8EnvContext envContext = new U8EnvContext(); envContext.U8Login = u8Login; //设置上下文参数
……
//设置 API 地址标识(Url) U8ApiAddress myApiAddress = new U8ApiAddress(“装载单据的地址标识”); //构造APIBroker U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext); //API参数赋值 broker.AssignNormalValue("参数名", "参数值"); …… //调用LOAD接口API if (!broker.Invoke()) { //错误处理 Exception apiEx = broker.GetException(); if (apiEx != null) { if (apiEx is MomSysException) { MomSysException sysEx = apiEx as MomSysException; Console.WriteLine("系统异常：" + sysEx.Message); //todo:
异常处理 } else if (apiEx is MomBizException) { MomBizException bizEx = apiEx as MomBizException; Console.WriteLine("API异常：" + bizEx.Message); //todo:异常处理 } } //结束本次调用，释放API资源 broker.Release(); return; } //获取表头或表体的BO对象，如果要取原始的XMLDOM对象结果，请使用GetResult(参数名) BusinessObject DomRet = broker.GetBoParam("表头或表体参数名");
接着，BO 对象经用户修改重新赋值,并传递给 UPDATE 接口提交保存；
//修改获取的BO对象，对需要更改的字段重新赋值 DomRet[0]["字段名"] = 新的字段值;
……
//重新构造“新增或修改”API的地址标识 myApiAddress = new U8ApiAddress("新增或修改”API的地址标识");
//重新构造APIBroker broker = new U8ApiBroker(myApiAddress, envContext); //表头或表体参数赋值 broker.SetBoParam("表头或表体参数名", DomRet); //API参数赋值 broker.AssignNormalValue("参数名", "参数值"); …… //调用UPDATE接口API if (!broker.Invoke()) { …… }
最后，获取返回结果。
//获取普通返回值 System.String result = broker.GetReturnValue() as System.String; //获取 out/inout 参数值 …… //结束本次调用，释放API资源 broker.Release();
2.2. API 内容 采购管理 2.2.1 采购管理
功能介绍
为了支持 U8 二次开发对业务单据的开发，本功能提供了实现采购业务单据各种操作功 能的编程接口。使用采购管理的 API 开发接口，可以对库存管理中的采购到货单、采购普通 发票、采购专用发票、采购订单、请购单、采购运费发票等单据进行审核、弃审、获取（或 装载） 、新增、修改、删除。
使用环境
必须安装.NET FrameWork 2.0； 必须安装 U8-872 版本的采购管理产品； 必须安装 API 适配器组件 PUAPIConcrete.dll
接口说明
采购管理二次开发接口说明： 审核单据-ConfirmPO 方法 参数： domHead —— 单据表头，DOM 对象，必输 API 上下文： VoucherType —— 单据类型，具体类型参看 API 上下文描述 bPositive —— 红蓝标识：True,蓝字 ；False,红字 sBillType —— 为空串 sBusType —— 业务类型：普通采购,直运采购,受托代销 弃审单据- CancelconfirmPO 方法 参数： domHead —— 单据表头，DOM 对象，必输 API 上下文： VoucherType —— 单据类型，具体类型参看 API 上下文描述 bPositive —— 红蓝标识：True,蓝字 ；False,红字 sBillType —— 为空串 sBusType —— 业务类型：普通采购,直运采购,受托代销 装载单据-Load 方法
参数： DomHead domBody strWhere varVoucherID strLocateWhere API 上下文： VoucherType bPositive sBillType sBusType 删除单据-Delete 方法 参数： DomHead domBody CurDom API 上下文： VoucherType bPositive sBillType sBusType
—— —— —— —— —— —— —— ——
——
表头 DOM 对象 表体 DOM 对象 过滤条件串 单据主表 ID 定位条件串 单据类型，具体类型参看 API 上下文描述 红蓝标识：True,蓝字 ；False,红字 为空串 业务类型：普通采购,直运采购,受托代销
—— 表头 DOM 对象 —— 表体 DOM 对象 —— 返回 DOM 格式错误信息 —— —— —— —— 单据类型，具体类型参看 API 上下文描述 红蓝标识：True,蓝字 ；False,红字 为空串 业务类型：普通采购,直运采购,受托代销
新增或修改新单据- VoucherSave 方法 参数： DomHead —— 单据表头，DOM 对象，必输 domBody —— 单据表体，DOM 对象，必输 VoucherState —— 保存状态，必输。2 增加；1 修改 ；0 非编辑 curID —— 返回单据头 ID CurDom —— 返回 DOM 格式错误信息 UserMode —— 使用模式，0：CS；1:BS API 上下文： VoucherType —— 单据类型，具体类型参看 API 上下文描述 bPositive —— 红蓝标识：True,蓝字 ；False,红字 sBillType —— 为空串 sBusType —— 业务类型：普通采购,直运采购,受托代销
开发步骤
实现采购单据某一功能，主要有以下七个步骤： 1． 构造 u8login 对象并登陆 声明和创建 u8login 类对象前应该先引用 U8API 类库中的 Interop.U8Login.dll，代码
示例如下：
U8Login.clsLogin u8Login = new U8Login.clsLogin(); String sSubId = "AS"; String sAccID = "(default)@001"; String sYear = "2008"; String sUserID = "demo"; String sPassword = ""; String sDate = "2008-09-30"; String sServer = "localhost"; String sSerial = ""; if(!u8Login.Login(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial)) { Console.WriteLine("登陆失败，原因：" + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login); return; }
//声明 u8login 对象
//登陆
如果当前环境中有 login 对象则可以省去第一步。 2． 构造环境上下文对象，传入 login，并按需设置其它上下文参数
U8EnvContext envContext = new U8EnvContext(); envContext.U8Login = u8Login; //设置上下文参数 envContext.SetApiContext("VoucherType", new int()); //上下文数据类型：int，含义：单据类型 envContext.SetApiContext("bPositive", new bool()); //上下文数据类型：bool，含义：红蓝标 识：True,蓝字 envContext.SetApiContext("sBillType", new string()); //上下文数据类型：string，含义：为空 串 envContext.SetApiContext("sBusType", new string()); //上下文数据类型：string，含义：业务 类型：普通采购,直运采购,受托代销 //构造环境上下文对象 //传入 login
如果是外部事务，则需要传递ADO.Connection对象，并将IsIndependenceTransaction 设置为true：
https://www.doczj.com/doc/2e14113779.html,DbConnection = new ADO.Connection(); envContext.IsIndependenceTransaction = true;
3． 设置 API 地址标识(Url)参数 //如当前A
PI“新增或修改”的地址标识为：U8API/PurchaseOrder/VoucherSave
U8ApiAddress myApiAddress = new U8ApiAddress("U8API/PurchaseOrder/VoucherSave");
4． 构造 APIBroker
U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);
5． API 对象参数赋值 1) 给 BO 表头参数 DomHead 和表体参数 domBody 赋值有两种方法，如下： 方法一是直接传入MSXML2.DOMDocumentClass对象，代码如下
MSXML2.DOMDocumentClass domHead = new MSXML2.DOMDocumentClass(); domHead.load("domHead.xml"); broker.AssignNormalValue("domHead", domHead);
方法二是构造BusinessObject对象，具体方法如下：
//首先通过GetBoParam方法获取表头表体参数 BusinessObject DomHead = broker.GetBoParam("DomHead"); DomHead.RowCount = 10; //设置行数 //其中，给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串 //以下代码示例只设置第一行值。各字段定义详见API服务接口定义 注意：设置行数为某个值，行数并不限定为该最大值，可以一直顺序添加至任意行，但有一个规则： 例如当设置为10时，可以对第0、1、……9行赋值，当对第10行赋值时候，则会顺序添加一个新行，但此时 是不能对第11行赋值的，当添加一个新行（第10行）后，又可以对第11行进行赋值。 /****************************** 以下是必输字段 ****************************/ DomHead[0]["poid"] = ""; //主关键字段，int类型 DomHead[0]["dpodate"] = ""; //日期，DateTime类型 DomHead[0]["cpoid"] = ""; //订单编号，string类型 DomHead[0]["cvenabbname"] = ""; //供货单位，string类型 DomHead[0]["cexch_name"] = ""; //币种，string类型 DomHead[0]["nflat"] = ""; //汇率，double类型 …… /***************************** 以下是非必输字段 ****************************/ DomHead[0]["ipresent"] = ""; //现存量，string类型 DomHead[0]["cmaketime"] = ""; //制单时间，DateTime类型 DomHead[0]["cmodifytime"] = ""; //修改时间，DateTime类型 DomHead[0]["caudittime"] = ""; //审核时间，DateTime类型 DomHead[0]["cauditdate"] = ""; //审核日期，DateTime类型 DomHead[0]["cmodifydate"] = ""; //修改日期，DateTime类型
…… 2) 给普通参数赋值 例如，
//给普通参数VoucherState（参数名）赋值。此参数的数据类型为int，此参数按值传递，具体请参 考服务接口定义 broker.AssignNormalValue("VoucherState", new int());
注意：所有参数名不限大小写。
3) 给“OUT 型”参数赋值 为方便用户使用 U8API，如果参数数据类型为一般值类型，如 String、Integer、Long、 Single、Double、Boolean、Date，则不必传入一个参数变量（传入也可） ；否则，则必须一 个参数变量。 如： ……
//该参数curID为OUT型参数，由于其数据类型为string，为一般值类型，因此不必传入一个参数变量。 在API调用返回时
，可以通过GetResult("curID")获取其值 //该参数CurDom为OUT型参数，由于其数据类型为MSXML2.IXMLDOMDocument2，非一般值类型，因此必 须传入一个参数变量。在API调用返回时，可以直接使用该参数 MSXML2.IXMLDOMDocument2 CurDom = new MSXML2.IXMLDOMDocument2(); broker.AssignNormalValue("CurDom", CurDom);
…… 当不传入一个参数变量时，在API调用返回时，可以通过GetResult(参数名)获取其值； 当不必传入一个参数变量时，在API调用返回时，可以直接引用该参数。 4) 给“INOUT 型”参数赋值 对“INOUT 型”型参数，则不论是否是一般值类型，都需要传入参数变量。其他与“OUT 型”参数一样。 6． 调用 API //示例调用如下：
if (!broker.Invoke()) { //错误处理 Exception apiEx = broker.GetException(); if (apiEx != null) { if (apiEx is MomSysException) { MomSysException sysEx = apiEx as MomSysException; Console.WriteLine("系统异常：" + sysEx.Message); //todo:异常处理 } else if (apiEx is MomBizException) { MomBizException bizEx = apiEx as MomBizException; Console.WriteLine("API异常：" + bizEx.Message); //todo:异常处理 }
} //结束本次调用，释放API资源 broker.Release(); return; } 注意：对调用失败，可以获取出错信息，如果是 API 框架的原因，则报告 MomSysException 异常， 如果是业务组件的原因，则报告 MomBizException 异常。
7． 获取返回结果 1) 获取 BO 对象
在“装载单据”时，通过 GetBoParam 方法获取表头或表体参数 BusinessObject DomHeadRet = broker.GetBoParam("DomHead"); Console.WriteLine("BO对象行数为：" + DomHeadRet.RowCount); //获取BO对象的行数 注意： 如果要取原始的XMLDOM对象结果，请使用GetResult("DomHead") as MSXML2.DOMDocument MSXML2.DOMDocument DomHeadRet = broker. GetResult("DomHead") as MSXML2.DOMDocument; 以上获取的行数是BO对象的实际行数。 //获取 BO 对象各字段的值。以下代码示例只取第一行。字段定义详见 API 服务接口定义 /****************************** 以下是必输字段 ****************************/ int poid = Convert.ToInt32(DomHeadRet[0]["poid"]); //主关键字段，int类型 DateTime dpodate = Convert.ToDateTime(DomHeadRet[0]["dpodate"]); //日期，DateTime类型 string cpoid = Convert.ToString(DomHeadRet[0]["cpoid"]); //订单编号，string类型 …… /***************************** 以下是非必输字段 ****************************/ string ipresent = Convert.ToString(DomHeadRet[0]["ipresent"]); //现存量，string类型 DateTime cmaketime = Convert.ToDateTime(DomHeadRet[0]["cmaketime"]); //制单时间，DateTime类 型 …… 2) 获取普通返回值
代码如下： //获取普通返回值。此返回值数据类型为System.String，此参数按值传递，具体请参考服务接口定义 System.String result = broker.GetReturnValue() as System.String; 3) 获取普通“OUT 型”
或“INOUT 型”返回值
如前所述，对普通“OUT 型”或“INOUT 型”参数，如果是一般值类型，则通过 GetResult 方法获取其 返回值，否则直接使用该引用。 如， //获取普通OUT参数curID。此返回值数据类型为string，在使用该参数之前，请判断是否为空 string curIDRet = broker.GetResult("curID") as string;
//获取普通 OUT 参数 CurDom。此返回值数据类型为 MSXML2.IXMLDOMDocument2，前面已定义该参数，请 直接使用 ……
销售管理 2.2.2 销售管理
功能介绍
为了支持 U8 二次开发对业务单据的开发，本功能提供了实现销售业务单据各种操作功 能的编程接口。使用销售管理 API 开发接口，可以完成销售管理的销售报价单、销售订单、 销售发货单、销售退货单、销售普通发票、销售专用发票、委托代销发货单、委托代销结算 单、销售调拨单等单据的审核、弃审、获取、新增、修改、删除。
使用环境
必须安装.NET FrameWork 2.0； 必须安装 U8-872 版本的销售管理产品； 必须安装 API 适配器组件 SAAPIConcrete.dll；
接口说明
销售管理二次开发接口及参数说明： 审核或弃审单据-Audit 方法 参数： domHead —— 单据表头，DOM 对象，必输 bVerify —— 审核/弃审标志，必输。true 表审核；false 表弃审 API 上下文： VoucherType —— 单据类型，必输。具体类型参看 API 上下文描述 删除单据-Delete 方法 参数： domHead —— 单据表头，DOM 对象，必输 API 上下文： VoucherType —— 单据类型，必输。具体类型参看 API 上下文描述 装载单据-Load 方法 参数： domHead domBody VouchID blnAuth API 上下文： VoucherType
—— —— —— ——
单据表头，DOM 对象，必输 单据表体，DOM 对象，必输 需要装载的单据号，可选 是否控制权限：true
—— 单据类型，必输。具体类型参看 API 上下文描述
新增或修改单据-Save 方法 参数： domHead —— domBody —— VoucherState —— VNewID —— DomConfig —— API 上下文： VoucherType ——
单据表头，DOM 对象，必输 单据表体，DOM 对象，必输 保存状态，必输。0 增加；1 修改 单据的 id，可选 ATO,PTO 选配配置，必输，可设置为 nothing 单据类型，必输。具体类型参看 API 上下文描述
开发步骤
实现销售单据某一功能，主要有以下七个步骤： 1． 构造 u8login 对象并登陆 声明和创建 u8login 类对象前应该先引用 U8API 类库中的 Interop.U8Login.dll，代码 示例如下：
U8Login.clsLogin u8Login = new U8Login.clsLogin(); String sSubId = "AS"; String sAccID = "(default)@001"; String sYear = "2008"; String sUserID = "demo"; String sPassword = ""; String sDate = "2008-09-30"; String sServer = "localhost"; String sSerial = ""; if(!u8Login.Login
(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial)) { Console.WriteLine("登陆失败，原因：" + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login); return; }
//声明 u8login 对象
//登陆
如果当前环境中有 login 对象则可以省去第一步。 2． 构造环境上下文对象，传入 login，并按需设置其它上下文参数
U8EnvContext envContext = new U8EnvContext(); envContext.U8Login = u8Login; //设置上下文参数 envContext.SetApiContext("VoucherType", new int()); //上下文数据类型：int，含义：单据类型 //构造环境上下文对象 //传入login
如果是外部事务，则需要传递ADO.Connection对象，并将IsIndependenceTransaction 设置为true：
https://www.doczj.com/doc/2e14113779.html,DbConnection = new ADO.Connection(); envContext.IsIndependenceTransaction = true;
3． 设置 API 地址标识(Url)参数 //如当前API“新增或修改”的地址标识为：U8API/SaleOrder/Save
U8ApiAddress myApiAddress = new U8ApiAddress("U8API/SaleOrder/Save");
4． 构造 APIBroker
U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);
5． API 对象参数赋值 1) 给 BO 表头参数 DomHead 和表体参数 domBody 赋值有两种方法，如下： 方法一是直接传入MSXML2.DOMDocumentClass对象，代码如下
MSXML2.DOMDocumentClass domHead = new MSXML2.DOMDocumentClass(); domHead.load("domHead.xml"); broker.AssignNormalValue("domHead", domHead);
方法二是构造BusinessObject对象，具体方法如下：
//首先通过GetBoParam方法获取表头表体参数 BusinessObject DomHead = broker.GetBoParam("DomHead"); DomHead.RowCount = 10; //设置行数 //其中，给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串 //以下代码示例只设置第一行值。各字段定义详见API服务接口定义 注意：设置行数为某个值，行数并不限定为该最大值，可以一直顺序添加至任意行，但有一个规则： 例如当设置为10时，可以对第0、1、……9行赋值，当对第10行赋值时候，则会顺序添加一个新行，但此时 是不能对第11行赋值的，当添加一个新行（第10行）后，又可以对第11行进行赋值。 /****************************** 以下是必输字段 ****************************/ domHead[0]["id"] = ""; //主关键字段，int类型 domHead[0]["csocode"] = ""; //订 单 号，string类型 domHead[0]["ddate"] = ""; //订单日期，DateTime类型 domHead[0]["cbustype"] = ""; //业务类型，string类型 …… /***************************** 以下是非必输字段 ****************************/ domHead[0]["fstockquanO"] = ""; //现存件数，double类型
domHead[0]["fcanusequanO"] = ""; //可用件数，double类型 domHead[0]["dpredatebt"] = ""; //预发货日期，DateTime类型 domHead[0]["dpremodatebt"] = ""; //预完工日期，DateTime类型 domHead[0]["dpredatebt"
] = ""; //预发货日期，DateTime类型
…… 2) 给普通参数赋值 例如，
//给普通参数VoucherState（参数名）赋值。此参数的数据类型为int，此参数按值传递，具体请参 考服务接口定义 broker.AssignNormalValue("VoucherState", new int()); 注意：所有参数名不限大小写。
3) 给“OUT 型”参数赋值 为方便用户使用 U8API，如果参数数据类型为一般值类型，如 String、Integer、Long、 Single、Double、Boolean、Date，则不必传入一个参数变量（传入也可） ；否则，则必须一 个参数变量。 如： ……
//该参数curID为OUT型参数，由于其数据类型为string，为一般值类型，因此不必传入一个参数变量。 在API调用返回时，可以通过GetResult("curID")获取其值 //该参数CurDom为OUT型参数，由于其数据类型为MSXML2.IXMLDOMDocument2，非一般值类型，因此必 须传入一个参数变量。在API调用返回时，可以直接使用该参数 MSXML2.IXMLDOMDocument2 CurDom = new MSXML2.IXMLDOMDocument2(); broker.AssignNormalValue("CurDom", CurDom);
…… 当不传入一个参数变量时，在API调用返回时，可以通过GetResult(参数名)获取其值； 当不必传入一个参数变量时，在API调用返回时，可以直接引用该参数。 4) 给“INOUT 型”参数赋值 对“INOUT 型”型参数，则不论是否是一般值类型，都需要传入参数变量。其他与“OUT 型”参数一样。 6． 调用 API //示例调用如下：
if (!broker.Invoke()) { //错误处理 Exception apiEx = broker.GetException(); if (apiEx != null) { if (apiEx is MomSysException)
{ MomSysException sysEx = apiEx as MomSysException; Console.WriteLine("系统异常：" + sysEx.Message); //todo:异常处理 } else if (apiEx is MomBizException) { MomBizException bizEx = apiEx as MomBizException; Console.WriteLine("API异常：" + bizEx.Message); //todo:异常处理 } } //结束本次调用，释放API资源 broker.Release(); return; } 注意：对调用失败，可以获取出错信息，如果是 API 框架的原因，则报告 MomSysException 异常， 如果是业务组件的原因，则报告 MomBizException 异常。
7． 获取返回结果 1) 获取 BO 对象
在“装载单据”时，通过 GetBoParam 方法获取表头或表体参数 BusinessObject DomHeadRet = broker.GetBoParam("DomHead"); Console.WriteLine("BO对象行数为：" + DomHeadRet.RowCount); //获取BO对象的行数 注意： 如果要取原始的XMLDOM对象结果，请使用GetResult("DomHead") as MSXML2.DOMDocument MSXML2.DOMDocument DomHeadRet = broker. GetResult("DomHead") as MSXML2.DOMDocument; 以上获取的行数是BO对象的实际行数。 //获取 BO 对象各字段的值。以下代码示例只取第一行。字段定义详见 API 服务接口定义 /****************************** 以下是必输字段 ****************************/ int id = Convert.ToInt32(domHeadRet[0]["
id"]); //主关键字段，int类型 string ccode = Convert.ToString(domHeadRet[0]["ccode"]); //单据号，string类型 DateTime ddate = Convert.ToDateTime(domHeadRet[0]["ddate"]); //日期，DateTime类型 string cbustype = Convert.ToString(domHeadRet[0]["cbustype"]); //业务类型，string类型 …… /***************************** 以下是非必输字段 ****************************/ string cpayname = Convert.ToString(domHeadRet[0]["cpayname"]); //付款条件，string类型 string cpersonname = Convert.ToString(domHeadRet[0]["cpersonname"]); //业 务 员，string类型 double itaxrate = Convert.ToDouble(domHeadRet[0]["itaxrate"]); //税率，double类型 string cexch_name = Convert.ToString(domHeadRet[0]["cexch_name"]); //币种，string 类型 ……
2)
获取普通返回值
代码如下： //获取普通返回值。此返回值数据类型为System.String，此参数按值传递，具体请参考服务接口定义 System.String result = broker.GetReturnValue() as System.String; 3) 获取普通“OUT 型”或“INOUT 型”返回值
如前所述，对普通“OUT 型”或“INOUT 型”参数，如果是一般值类型，则通过 GetResult 方法获取其 返回值，否则直接使用该引用。 如， //获取普通OUT参数curID。此返回值数据类型为string，在使用该参数之前，请判断是否为空 string curIDRet = broker.GetResult("curID") as string; //获取普通 OUT 参数 CurDom。此返回值数据类型为 MSXML2.IXMLDOMDocument2，前面已定义该参数，请 直接使用 ……
库存管理 2.2.3 库存管理
功能介绍
为了支持 U8 二次开发对业务单据的开发，本功能提供了实现库存业务单据各种操作功 能的编程接口。使用库存管理的 API 开发接口，可以对库存管理中的采购入库单、其他入库 单、其他出库单、产成品入库单、材料出库单、调拨单、组装单、拆卸单、形态转换单、盘 点单、货位调整单、销售出库单、期初结存、不合格品记录单、不合格品处理单、期初不合 格品、调拨申请单等单据进行审核、弃审、获取（或装载） 、新增、修改、删除。
使用环境
必须安装.NET FrameWork 2.0； 必须安装 U8-872 版本的库存管理产品； 必须安装 API 适配器组件 STAPIConcrete.dll
接口说明
库存管理二次开发接口说明： 审核单据-Audit 方法 参数： sVoucherType —— VoucherId —— errMsg —— cnnFrom —— TimeStamp —— domMsg —— bCheck —— bBeforCheckStock —— bList —— MakeWheres —— sWebXml —— oGenVouchIds ——
单据类型：01 单据 ID 错误信息 连接对象(调用方控制事务时需要传入连接对象) 单据时间戳(用于检查单据是否修改， 空串时不检查) 返回 DOM 格式的信息:主要是可用量信息 是否进行业务检查(是否控制可用量) 是否检查可用量 传入 false 传空 传入
空串 获取单据 ID 列表(返回审核时自动生成的单据的 id 列表,传空)
弃审单据-CancelAudit 方法 参数： sVoucherType —— 单据类型：01 VoucherId —— 单据 ID errMsg —— 错误信息
cnnFrom TimeStamp domMsg bCheck bBeforCheckStock bList 装载单据-Load 方法 参数： sVoucherType sWhere DomHead domBody domPos errMsg bGetBlank sBodyWhere_Order
—— —— —— —— —— ——
连接对象(由调用方控制事务时必须传入) 单据时间戳(用于检查单据是否修改， 空串时不检查) 超可用量提示信息 DOM 对象(返回 DOM 格式的信息) 是否进行业务检查 是否检查可用量 传入 false
—— —— —— —— —— —— —— ——
单据类型：01 条件串 表头 DOM 对象 表体 DOM 对象 货位 DOM 对象 错误信息 是否获取空白单据 表体排序方式字段
注意：其中 sWhere 设计为: 如 果 按 单 据 号 加 载 ， 则 语 法 为 ccode=N' 要 加 载 的 单 据 号 ' ， 例 如 broker.AssignNormalValue("sWhere", "ccode = N'0000000001'")； 如 果 按 单 据 ID 加 载 ， 则 语 法 为 id=XXX ， 例 如 broker.AssignNormalValue("sWhere", "id = 1")。 删除单据-Delete 方法 参数： sVoucherType VoucherId errMsg cnnFrom TimeStamp domMsg bCheck BeforCheckStock bList 添加新单据- Add 方法 参数： sVoucherType DomHead domBody domPosition errMsg
—— —— —— —— —— ——
单据类型：01 单据 ID 错误信息 连接对象 （由调用方控制事务时需要传入连接对象） 单据时间戳 返回 DOM 格式的信息：主要是检查可用量和控制可 用量信息 —— 是否进行业务检查 —— 是否检查可用量 —— 传入 false
—— —— —— —— ——
单据类型：01 表头 DOM 对象 表体 DOM 对象 货位 DOM 对象：传空 返回错误信息
cnnFrom VoucherId domMsg bCheck bBeforCheckStock bIsRedVouch sAddedState bReMote
—— 连接对象，如果由调用方控制事务，则需要设置 此连接对象，否则传空 —— 返回单据 ID —— 返回 DOM 格式的信息：主要返回可用量和现存量 的错误信息 —— 是否进行业务检查(是否控制可用量) —— 是否检查可用量(检查可用量) —— 是否红字单据 —— 传空字符串 —— 是否远程
修改单据-Update 方法 参数： sVoucherType DomHead domBody domPosition errMsg cnnFrom domMsg bCheck bBeforCheckStock bIsRedVouch sAddedState bUpdateNeedEas
—— —— —— —— —— —— —— —— —— —— —— ——
单据类型：01 表头 DOM 对象 表体 DOM 对象 货位 DOM 对象 错误信息 连接对象 超可用量提示信息 DOM 对象（返回 DOM 格式的信息） 是否进行业务检查 是否检查可用量 是否红字单据 修改状态 传 true
开发步骤
实现库存单据某一功能，主要有以下七个步骤： 1
． 构造 u8login 对象并登陆 声明和创建 u8login 类对象前应该先引用 U8API 类库中的 Interop.U8Login.dll，代码 示例如下：
U8Login.clsLogin u8Login = new U8Login.clsLogin(); String sSubId = "AS"; String sAccID = "(default)@001"; String sYear = "2008"; String sUserID = "demo"; String sPassword = ""; String sDate = "2008-09-30"; String sServer = "localhost";
//声明 u8login 对象
//登陆
String sSerial = ""; if(!u8Login.Login(ref sSubId, ref sAccID, ref sYear, ref sUserID, ref sPassword, ref sDate, ref sServer, ref sSerial)) { Console.WriteLine("登陆失败，原因：" + u8Login.ShareString); Marshal.FinalReleaseComObject(u8Login); return; }
如果当前环境中有 login 对象则可以省去第一步。 2． 构造环境上下文对象，传入 login
U8EnvContext envContext = new U8EnvContext(); envContext.U8Login = u8Login; //构造环境上下文对象 //传入 login
3． 设置 API 地址标识(Url)参数 //如当前API“新增或修改”的地址标识为：U8API/SaleOrder/Save
U8ApiAddress myApiAddress = new U8ApiAddress("U8API/SaleOrder/Save");
4． 构造 APIBroker
U8ApiBroker broker = new U8ApiBroker(myApiAddress, envContext);
5． API 对象参数赋值 1) 给 BO 表头参数 DomHead 和表体参数 domBody 赋值有两种方法，如下： 方法一是直接传入MSXML2.DOMDocumentClass对象，代码如下
MSXML2.DOMDocumentClass domHead = new MSXML2.DOMDocumentClass(); domHead.load("domHead.xml"); broker.AssignNormalValue("domHead", domHead);
方法二是构造BusinessObject对象，具体方法如下：
//首先通过GetBoParam方法获取表头表体参数 BusinessObject DomHead = broker.GetBoParam("DomHead"); DomHead.RowCount = 10; //设置行数 //其中，给BO对象的字段赋值，值可以是真实类型，也可以是无类型字符串 //以下代码示例只设置第一行值。各字段定义详见API服务接口定义 注意：设置行数为某个值，行数并不限定为该最大值，可以一直顺序添加至任意行，但有一个规则： 例如当设置为10时，可以对第0、1、……9行赋值，当对第10行赋值时候，则会顺序添加一个新行，但此时 是不能对第11行赋值的，当添加一个新行（第10行）后，又可以对第11行进行赋值。 /****************************** 以下是必输字段 ****************************/
DomHead[0]["id"] = ""; //主关键字段，int类型 DomHead[0]["ccvcode"] = ""; //盘点单号，string类型 DomHead[0]["dcvdate"] = ""; //盘点日期，DateTime类型 DomHead[0]["dacdate"] = ""; //账面日期，DateTime类型 DomHead[0]["cwhname"] = ""; //盘点仓库，string类型 …… /***************************** 以下是非必输字段 ****************************/ DomHead[0]["cmodifyperson"] = ""; //修改人，string类型 DomHead[0]["dmodifydate"] = ""; //修改日期，DateTime类型 DomHead[0]["dnmaketime"] = ""; //制单时间
，DateTime类型 DomHead[0]["dnmodifytime"] = ""; //修改时间，DateTime类型 DomHead[0]["dnverifytime"] = ""; //审核时间，DateTime类型
…… 2) 给普通参数赋值 例如，给普通参数 sVouchType（参数名）赋值：
broker.AssignNormalValue("sVouchType", new System.String()); 注意：所有参数名不限大小写。
3) 给“OUT 型”参数赋值 为方便用户使用 U8API，如果参数数据类型为一般值类型，如 String、Integer、Long、 Single、Double、Boolean、Date，则不必传入一个参数变量（传入也可） ；否则，则必须一 个参数变量。 如： ……
// 该参数errMsg为OUT型参数，由于其数据类型为System.String，为一般值类型，因此不必传入一个 参数变量。在API调用返回时，可以通过GetResult("errMsg")获取其值 //该参数domMsg为OUT型参数，由于其数据类型为MSXML2.IXMLDOMDocument2，非一般值类型，因此必 须传入一个参数变量。在API调用返回时，可以直接使用该参数 MSXML2.IXMLDOMDocument2 domMsg = new MSXML2.IXMLDOMDocument2(); broker.AssignNormalValue("domMsg", domMsg);
……
注意：当不传入一个参数变量时，在API调用返回时，可以通过GetResult(参数名)获取其值；当不必 传入一个参数变量时，在API调用返回时，可以直接引用该参数。
4) 给“INOUT 型”参数赋值 对“INOUT 型”型参数，则不论是否是一般值类型，都需要传入参数变量。其他与“OUT 型”参数一样。 6． 调用 API //示例调用如下：
if (!broker.Invoke()) { //错误处理 Exception apiEx = broker.GetException(); if (apiEx != null) { if (apiEx is MomSysException) { MomSysException sysEx = apiEx as MomSysException; Console.WriteLine("系统异常：" + sysEx.Message); //todo:异常处理 } else if (apiEx is MomBizException) { MomBizException bizEx = apiEx as MomBizException; Console.WriteLine("API异常：" + bizEx.Message); //todo:异常处理 } } //结束本次调用，释放API资源 broker.Release(); return; } 注意：对调用失败，可以获取出错信息，如果是 API 框架的原因，则报告 MomSysException 异常， 如果是业务组件的原因，则报告 MomBizException 异常。
7． 获取返回结果 1) 获取 BO 对象
在“装载单据”时，通过 GetBoParam 方法获取表头或表体参数 BusinessObject DomHeadRet = broker.GetBoParam("DomHead"); Console.WriteLine("BO对象行数为：" + DomHeadRet.RowCount); //获取BO对象的行数 注意： 如果要取原始的XMLDOM对象结果，请使用GetResult("DomHead") as MSXML2.DOMDocument MSXML2.DOMDocument DomHeadRet = broker. GetResult("DomHead") as MSXML2.DOMDocument; 以上获取的行数是BO对象的实际行数。 //获取 BO 对象各字段的值。以下代码示例只取第一行。字段定义详见 API 服务接口定义 /****************************** 以下是必输字段 ****************************
/ int id = Convert.ToInt32(DomHeadRet[0]["id"]); //主关键字段，int类型 string ccvcode = Convert.ToString(DomHeadRet[0]["ccvcode"]); //盘点单号，string类型 DateTime dcvdate = Convert.ToDateTime(DomHeadRet[0]["dcvdate"]); //盘点日期，DateTime类型 DateTime dacdate = Convert.ToDateTime(DomHeadRet[0]["dacdate"]); //账面日期，DateTime类型 string cwhname = Convert.ToString(DomHeadRet[0]["cwhname"]); //盘点仓库，string类型
…… /***************************** 以下是非必输字段 ****************************/ string cmodifyperson = Convert.ToString(DomHeadRet[0]["cmodifyperson"]); //修改人，string类型 DateTime dmodifydate = Convert.ToDateTime(DomHeadRet[0]["dmodifydate"]); //修改日期，DateTime 类型 DateTime dnmaketime = Convert.ToDateTime(DomHeadRet[0]["dnmaketime"]); //制单时间，DateTime 类型 DateTime dnmodifytime = Convert.ToDateTime(DomHeadRet[0]["dnmodifytime"]); //修改时间， DateTime 类型 DateTime dnverifytime = Convert.ToDateTime(DomHeadRet[0]["dnverifytime"]); //审核时间， DateTime 类型 …… 2) 获取普通返回值
代码如下： //获取普通返回值。此返回值数据类型为System.String，此参数按值传递，具体请参考服务接口定义 System.String result = broker.GetReturnValue() as System.String; 3) 获取普通“OUT 型”或“INOUT 型”返回值
如前所述，对普通“OUT 型”或“INOUT 型”参数，如果是一般值类型，则通过 GetResult 方法获取其 返回值，否则直接使用该引用。 如， //获取普通OUT参数domPos。此返回值数据类型为MSXML2.IXMLDOMDocument2，前面已定义该参数，请直接 使用 //获取普通OUT参数errMsg。此返回值数据类型为System.String，在使用该参数之前，请判断是否为空 System.String errMsgRet = broker.GetResult("errMsg") as System.String;……