滿記 第三方POS數(shù)據(jù)收集WebService方式開發(fā)指南-esales接口版本0826

銷售數(shù)據(jù)采集接口開發(fā)指南 WebService文檔名稱(title)銷售數(shù)據(jù)采集接口開發(fā)指南作者(Author)華北科傳項目組審批者 (To Be Approved By)科傳項目經(jīng)理：TECH-TRANS說明 (Comments)旨在對第三方POS銷售數(shù)據(jù)采集接口開發(fā)指南定義方案書；前言在承租方與租賃方雙方簽署的XXXXXX 號商鋪（下稱“該商鋪”）的XXXXXXXX商鋪租賃合同（下稱“租賃合同”）規(guī)定的租賃期（下稱“租賃期”）內(nèi)，承租方有義務(wù)按照租賃合同內(nèi)要求將每日每筆銷售交易數(shù)據(jù)通過軟件接口的方式，每日按時傳送給租賃方（業(yè)主）的管理系統(tǒng)內(nèi)。承租方同意使用租賃方（業(yè)主）提供的銷售數(shù)據(jù)上傳的形式，并協(xié)助租賃方（業(yè)主）在商鋪開業(yè)前，完成數(shù)據(jù)接口調(diào)試與上傳工作。為配合此次項目銷售數(shù)據(jù)實時采集項目的要求；現(xiàn)將數(shù)據(jù)接口技術(shù)方案通過此文給予發(fā)布，以便承租方POS軟件開發(fā)者（供應(yīng)商）研讀制作相應(yīng)銷售數(shù)據(jù)接口。技術(shù)方案業(yè)務(wù)業(yè)務(wù)邏輯架構(gòu)圖租戶自帶POS系統(tǒng)通訊層 C接口調(diào)用層 A項目零售管理系統(tǒng)POS ServerWebService ClientpostesalescreateWebServer發(fā)布應(yīng)用層 B存儲交易產(chǎn)生交易報文1. Web Service交易函數(shù)說明Postesalescreate()：上傳正常銷售交易數(shù)據(jù)、退貨交易數(shù)據(jù)函數(shù)。2. Web Service交易函數(shù)結(jié)構(gòu)說明軟件開發(fā)商每筆銷售（退貨）數(shù)據(jù)完結(jié)需要調(diào)用上傳交易Web Service函數(shù)，每次只上傳一筆交易數(shù)據(jù)。每一筆交易數(shù)據(jù)均需包含以下內(nèi)容： Header信息包括許可證，用戶名，密碼等等信息 交易匯總信息包括該筆銷售的交易日期，交易時間，店鋪號，收銀機號，交易流水號，總金額，總貨品數(shù)，付款方式數(shù)量（共有幾種付款方式）等等信息。每筆銷售數(shù)據(jù)，只會有一條匯總信息。 貨品信息包括貨品編號，貨品單價，貨品數(shù)量，實際銷售交易，等等信息。每筆銷售數(shù)據(jù)，可有多條貨品信息。 付款方式信息包括付款方式編號，付款金額（找零后金額）等等信息。每筆銷售數(shù)據(jù)，可有多條付款方式信息。3. 函數(shù)調(diào)用示例說明以下提供XML文件格式，緊接著是以表格的形式對文件格式進行詳細解釋。Postesalescreate()請求數(shù)據(jù)格式：以下是 SOAP 1.2 請求和響應(yīng)示例。所顯示的占位符需替換為實際值。占位符示例：POST /eSales/esales.asmx HTTP/1.1Host: 0Content-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 string int string decimal decimal decimal decimal string string int string decimal decimal decimal decimal string string int string decimal decimal decimal string string int string decimal decimal decimal string string 填寫數(shù)據(jù)示例：（為非本項目測試用戶信息） GYHTC00001 123456 1 1 1 SALESDATA 332 V332M 20160329 170723 01 GYHTCL1000080001 01 10000791 01 1 0.99 2 1100008001 1 0 0.99 0 2 CH 0.99 0.99 0 備注：1）以上示例中tendercode付款方式代號解釋：CH-現(xiàn)金。（測試時，請只以CH現(xiàn)金進行測試即可），正式系統(tǒng)內(nèi)的各個付款方式如需要一一對應(yīng)，在交付正式地址及貴司的用戶信息時會連帶附上正式環(huán)境下付款方式代碼及定義。接口數(shù)據(jù)應(yīng)在TenderCode付款方式中填寫對應(yīng)方式付款實際金額，無對應(yīng)付款方式時在其他付款方式字段填寫剩余付款方式金額的合計。Postesalescreate()返回信息：HTTP/1.1 200 OKContent-Type: application/soap+xml; charset=utf-8Content-Length: length short string int int int int int string string string Rtn Code:-1:失敗0:成功1:數(shù)據(jù)庫報錯2:原始數(shù)據(jù)錯誤3:SQL語句錯誤5:貨號不存在6:VIP Code不存在11:用戶名/密碼錯誤14:無效日期15:無效時間1000:單據(jù)已存在(重復上傳)1001:原單據(jù)不存在1002:銷售貨號為空1003:付款信息為空1005:積分補錄的銷售單不存在1006:積分補錄的銷售單已是VIP銷售單 1007:積分補錄的銷售金額與系統(tǒng)中對應(yīng)銷售單的銷售金額不匹配4. XML數(shù)據(jù)文件內(nèi)容詳細解釋 傳入?yún)?shù)：Postesalescreate 返回值：PostesalescreateResponse 舉例PostesalescreateRequest:銷售開單請求序號字段名描述數(shù)據(jù)類型允許空值說明1.header標頭requestheader否2.salestotal銷售開單主表SalesTotal否3.salesitems銷售開單明細表SalesItem否4.salestenders銷售開單付款明細表SalesTender否PostesalescreateResponse:銷售開單響應(yīng)序號字段名描述數(shù)據(jù)類型允許空值說明1.header標頭responseheader否2.salestotal銷售開單主表SalesTotal否Header標頭信息序號字段名描述數(shù)據(jù)類型允許空值說明1.username用戶名string否商場提供每個租戶單位一個2.password密碼string否商場提供每個租戶單位一個3.messagetype消息類型string否固定值：SALESDATA4.messageid消息IDstring否固定值：3325.version版本編號string否固定值：V332MSalesTotal:銷售單主表序號字段名描述數(shù)據(jù)類型允許空值說明1.txdate_yyyymmdd交易日期string否長度:8固定格式：YYYYMMDD2.txtime_hhmmss交易時間string否長度:6固定格式：HHMMSS3.Mallid商城編號string否長度:2 4.storecode店鋪號string否長度:20Web服務(wù)系統(tǒng)需要校驗該店鋪的有效性5.tillid收銀機號string否可用01或者02表示如果專柜只有一臺收銀機就用01表示，如果有兩臺則第二臺用02表示，依次類推Web服務(wù)系統(tǒng)需要校驗該收銀機編號的有效性6.txdocno銷售單號string否長度:30（不超過）專柜銷售單號，必須唯一Web服務(wù)系統(tǒng)如果判斷到此單號的記錄已經(jīng)存在，返回錯誤信息7.cashier收銀員編號string否長度:108.salesman銷售員string是保留9.vipcodeVIP號string是固定留空10.netqty數(shù)量decimal 4 否長度:1固定值：111.netamount銷售凈金額decimal 4 否當金額是負數(shù)時，則被認為是退貨12.extendparam預(yù)留字段string是后期擴展預(yù)留，留空即可SalesItem:銷售單貨品明細表序號字段名描述數(shù)據(jù)類型允許空值說明1.lineno商品行號string否長度:12.itemcode商品編號string否長度:30Web服務(wù)系統(tǒng)校驗貨號是否有效3.qty數(shù)量decimal 4 否長度:1固定值：1退貨為負數(shù)4.discountamount折扣金額decimal 4 否固定值：05.netamount凈金額decimal 4 否當金額是負數(shù)時，則被認為是退貨6.bonusearn獲得的積分decimal 4 否固定值：07.extendparam預(yù)留字段string是后期擴展使用，留空即可8.salesitemremark貨品備注string是固定空值SalesTender:銷售單付款明細表序號字段名描述數(shù)據(jù)類型允許空值說明1.lineno行號string否長度:12.tendercode付款代碼string否長度:2CH-現(xiàn)金接口數(shù)據(jù)應(yīng)在TenderCode付款方式中填寫對應(yīng)方式付款實際金額，無對應(yīng)付款方式時在其他付款方式字段填寫剩余付款方式金額的合計Web服務(wù)系統(tǒng)需要校驗付款方式編號有效性3.payamount付款金額decimal 4 否付款金額4.baseamount本位幣金額decimal 4 否同payamount5.excessamount找零金額decimal 4 否固定為 0 6.extendparam預(yù)留字段string是后期擴展使用，留空即可7.remark備注信息string是固定空值5. 返回碼解釋Postesalescreate()返回碼解釋返回碼（short）為【0】，表示調(diào)用Web Service成功。交易被完整接納。返回碼（short）為非【0】，表示調(diào)用Web Service不成功。軟件開發(fā)商收到此返回信息清除重傳交易隊列銷售資料。其他返回碼表示不成功，不成功信息從（string）獲取。軟件開發(fā)商收到其他返回碼請將未成功傳送的交易放入重傳交易隊列。并且截取responsemessage在程序界面做相應(yīng)的提示。請開發(fā)方保存好response，以此作為上傳成功的記錄。6. 異常情況說明 連接Web Service無法連通的情況下，租戶POS系統(tǒng)產(chǎn)生的交易應(yīng)該保存在POS機器本地磁盤或者數(shù)據(jù)庫中。租戶POS系統(tǒng)應(yīng)當在網(wǎng)絡(luò)正常的前提下，在適當?shù)墓δ苣K里給出提示信息，提示租戶POS系統(tǒng)操作人員連接Web Service發(fā)送交易數(shù)據(jù)。 連接Web Service無法連通的情況下，租戶POS系統(tǒng)應(yīng)當嘗試幾次（建議三次）連接。如果還無法連通，建議POS系統(tǒng)能編寫代碼停止發(fā)送數(shù)據(jù)，并間隔一定的時間后再連接Web Service（建議設(shè)定每一小時），從而避免不斷連接，影響租戶POS系統(tǒng)機器的性能。 已經(jīng)發(fā)送成功的銷售數(shù)據(jù)租戶POS系統(tǒng)要保證不再重復發(fā)送，這樣才能保證Web服務(wù)器不會過多處理異常數(shù)據(jù)。生產(chǎn)環(huán)境軟件開發(fā)商可以通過以下網(wǎng)址進行本次項目的Web Service測試：服務(wù)端具體地址：開發(fā)商可通過以下網(wǎng)址進行本次項目的WebService接口測試：(內(nèi)網(wǎng))外網(wǎng)URL: 5:30001/esales.asmx?WSDLWebservice服務(wù)器。測試賬號信息商場編號（mallid