柳州万象城数据接驳WebService开发说明文档

柳州万象城销售数据采集接口开发指南WebService根据贵司与我司签署的合同POS专用收银系统相关约定，贵司于柳州万象城店铺的收银系统需与我司内网中的系统进行接驳，实时准确上传营业数据，请按照以下要求准备硬件设备（局域网上传需双网卡，或外置USB转网卡）和软件接驳程序开发。一、技术方案业务逻辑架构图正式系统为通过内网上传租户自带POS系统通讯层 C接口调用层 A商场零售管理系统POS ServerWebService ClientpostsalescreateWebServer发布应用层 B存储交易产生交易报文 二、收银接驳布线说明贵司则需要从商场预留的弱电交接箱布六条超五类以上网线至收银台处。其中四条网线用于上传销售数据（连接贵司收银服务器）。六条网线两头需按B类打上水晶头，一头插入弱电交接箱中最上面的四个模块，另一头插在上传数据的服务器（可以是收银机）。其中一条网线为上传主线，其余为备用线路，另外两条网线用作店铺宽带及电话线路。三、接驳程序功能要求1. 当一笔交易（包括退货）完成后，把生成的销售数据写成标准的XML文件格式，然后连接web service server端，把XML文件发送到web service server端。交易发送不成功形成提醒式回馈信息告知,譬如”交易上传至商场不成功,请检查网络联系管理员”。2. 如果连接web service server端不成功，把该笔交易的销售数据的唯一标示保存到本地文件，以便在连接web service server端正常的情况下，可以通过该唯一标示提取数据库中的原始销售数据，重新生成XML文件并发送到web service server端。成功发送后，把本地文件对应该笔的销售数据的唯一标示删除。即接口程序在断开的网络恢复后，需要将之前未上传的数据上传。3. 如果返回xml文件显示的状态为不成功，把该笔交易的销售数据的唯一标示保存到本地文件，以便在数据校验成功后，可以通过该唯一标示提取数据库中的原始销售数据，重新生成XML文件并发送到web service server端。成功发送后，把本地文件对应该笔的销售数据的唯一标示删除。4. 若收银员因操作失误、客人更改付款方式等原因需要修改已上传的记录，接口程序则需要生成一笔负的交易与错误的那笔冲正，然后再上传正确的数据，其中销售单号需要满足唯一性。5. 万象城的正式环境为内网环境。租户数据需通过内网上传到商场的管理系统。四、账号信息说明1临时外网环境测试（只供开发测试用）以下外网接口只限于开发商开发测试之用，如软件开发完成，店内条件不满足可先进行外网测试。URL：4:30001/eSales/esales.asmx?WSDL（外网，店铺装修期开发测试）URL：52:30001/eSales/esales.asmx?WSDL（内网，店铺开业上线测试）商场编号（mallid）：01交易店铺号（storecode）： 见邮件交易货号（itemcode）：见邮件收银机号（tillid）：01 测试用户帐号：见邮件测试用户密码：00003正式内网环境（待测试环境正常上传一个月数据后切换到正式环境）URL： 待定商场编号（mallid）：01交易店铺号（storecode）： 待定交易货号（itemcode）：待定收银机号（tillid）：01测试用户帐号：待定测试用户密码：待定五、软件数据结构说明:1Requestheader: 请求表头信息序号字段名描述数据类型允许空值说明1.Licensekey许可证书string是商场提供固定值2.Username用户名string是商场提供固定值3.Password密码string是商场提供固定值4.Lang语言string是5.pagerecords每页记录数integer否固定值：16.pageno页数integer否固定值：17.updatecount每次更新记录数integer否固定值：18.messagetype消息类型string否固定值：SALESDATA9.messageid消息IDstring否固定值：33210.version版本编号string否固定值：V332M2ESalesHdr:销售单汇总信息序号字段名描述数据类型允许空值说明1.txdate_yyyymmdd交易日期String否长度:8固定格式：YYYYMMDD2.txtime_hhmmss交易时间String否长度:6固定格式：HHMMSS3.mallid商场编号string否长度:4商场提供固定值4.storecode店铺号string否长度:20Web服务系统需要校验该店铺的有效性5.tillid收银机号string否可用01或者02表示如果专柜只有一台收银机就用01表示，如果有两台则第二台用02表示，依次类推Web服务系统需要校验该收银机编号的有效性6.txdocno销售单号string否长度:30专柜销售单号Web服务系统如果判断到此单号的记录已经存在，返回错误信息7.cashier收银员编号string否长度:108.vipcodeVIP卡号string是保留9.salesman销售员string是保留10.netqty净数量decimal 4 否销售总数量11.netamount净金额decimal 4 否销售净金额12.extendparam扩展参数string是保留3ESalesItem:销售单货品明细表序号字段名描述数据类型允许空值说明1.lineno行号long否1,2,3,4.2.itemcode商品编号String否长度:30商场提供的商品编号货号Web服务系统校验货号是否有效3.qty数量decimal 4 否4.discountamount折扣金额decimal 4 否Default: 0此行商品的折扣金额5.netamount净金额decimal 4 否6.bonusearn获得积分decimal 4 否Default: 07.extendparam扩展参数string是保留8.salesitemremark备注string是保留4ESalesTender:销售单付款明细表序号字段名描述数据类型允许空值说明1.lineno行号long否1,2,3,4.2.tendercode付款代码string否长度:2需填写TT系统中存在的付款方式代码.Web服务系统需要校验付款方式编号有效性导入时不管此付款方式在系统中是否设为转折扣，都按正常（不转折扣）方式导入CH-现金、CI-国内银行卡、CO-国外银行卡、OT-其它，其它付款方式为非免费赠送而需要购买或其他方式获得的现金替代品。包含会员卡（有储值功能）、储值卡、提货卡（一次性购买的）、有价礼券等。3.payamount付款金额decimal 4 否4.baseamount本位币金额decimal 4 否同payamount5.excessamount超额金额decimal 4 是保留Default: 06.extendparam扩展参数string是保留7.remark备注string是保留付款方式说明：CH-现金、CI-国内银行卡、WP-微信支付、AP-支付宝支付、OT-其它 其中，其它付款方式为非免费赠送而需购买或其他方式获得的现金替代品，如会员卡（有储值功能）、储值卡等。5PostESalesRreateRequest:销售上传请求结构序号字段名描述数据类型说明8.header请求表头信息requestheader9.esalestotal销售单汇总信息esaleshdr10.esalesitems货品信息esalesitem11.esalestenders付款信息esalestender6Responseheader: 请求处理返回信息序号字段名描述数据类型允许空值说明12.responsecode返回代码integer否服务器返回13.responsemessage返回信息string是服务器返回14.pagerecords每页记录数integer否15.pageno页数integer否16.updatecount更新记录数integer否17.maxrecords最大记录数integer否18.maxpageno最大页数integer否19.messagetype消息类型string是20.messageid消息IDstring是21.version版本编号string是7PostESalesRreateResponse:销售上传返回信息结构序号字段名描述数据类型说明22.header返回信息结构变量responseheader六、Web Service交易函数说明：1PostESalesCreatePostesalescreate(postesalescreaterequest astr_request) returns postesalescreateresponse：上传正常销售交易数据、退货交易数据函数。软件开发商每笔销售（包括退货）数据完结需要调用上传交易Web Service函数，每次只上传一笔交易数据。每一笔交易数据均需包含以下内容：1. Header信息包括许可证，用户名，密码等等信息2. 销售单汇总信息包括该笔销售的交易日期，交易时间，店铺号，收银机号，交易流水号，总金额，总货品数，付款方式数量（共有几种付款方式）等等信息。每笔销售数据，只会有一条汇总信息。3. 货品信息包括货品编号，货品单价，货品数量，实际销售交易，等等信息。每笔销售数据，可有多条货品信息。4. 付款方式信息包括付款方式编号，付款金额（找零后金额）等等信息。每笔销售数据，可有多条付款方式信息。2函数请求数据格式:SOAP 1.2以下是 SOAP 1.2 请求和响应示例。所显示的占位符需替换为实际值。POST /TTPOS/sales.asmx HTTP/1.1Host: 6Content-Type: application/soap+xml; charset=utf-8Content-Length: length string string string string int int int string string string string string string string string string string string string decimal decimal decimal string int string decimal decimal decimal string string int string decimal decimal decimal string string int string decimal decimal decimal string string int string decimal decimal decimal string string int string decimal decimal decimal string string int string decimal decimal decimal string string HTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-Length: length short string int int int int int string string string 3 返回码解释:1）返回码（short）为【0】，表示调用Web Service成功。交易被完整接纳。2）返回码（short）为非【0】，表示调用Web Service不成功，不成功信息从（string）获取。4 例子XML数据:000SALESDATA332V332M2013060212000001B1280101T0000000040010011100101280101010001CH1001000七、注意事项1. 据租赁合同，租户有义务在租赁期内，将每日的营业数据完整、真实和准确的按时传送至万象城的收银系统内，并协助我司在店铺开业前，完成此接驳工作。 2. 接驳产生的费用，如软件开发、实施等，由租户自己承担。 3. 租户必须确保接口数据上传成功。 如未成功，租户须及时进行数据重传。 4. 租户系统应保留生成的接口数据，以便日后对账及查核数据使用。 5. 如上传的营业数据有误或不全，必须重新生成并上传营业数据。 6. 租户POS机必须配备双网卡，以实现与万象城内网接口服务器的通讯。 7. 租户系统接口程序需预留数据库及表名配置项，方便以后修改。 8. 为避免单号重复导致上传数据无法被处理，租户系统接口程序需预留交易单号配置项，以便租户系统故障后设臵单号的起始值（或采取每一笔单据号从万象城数据库取最大单据号后加1的方式实现） 9. 如遇到故障（如网络中断、租户系统故障、万象城服务器故障等）导致实时销售数据上传中断，在故障排除后租户系统接口程序需实现从未成功上传的第一条数据重新上传