0.4DLL接口方式

  DLL接口作用

为了方便对接平台，我们将网络访问和URL协议签名部分封装成了DLL方便对接使用。

这里下载：GuPAPI_DLL.dll

接口DLL文件名：GuoPAPI.dll,最新版本：3.2.2311.2701

最新更新：支持初始化参数clientver,以兼容do-sync

2019-10-17:

1.增加sys-notify消息通知下行推送，用于通知发送

2.多条消息不再等前一条确认接收后再发送，会出现并行发送，请注意处理

2019-10-22

1.增加本地缓存操作函数，cacheGet,cachePut,cacheLen，可用于排重等场景

2019-11-03

1.优化部分http请求返回异常的处理

2.新增本地缓存操作函数

2019-11-20

1.增加自动清除过期数据文件，默认保留7天

2.优化9100服务启动异常进行捕获

3.DLL包文件中默认包含SSL扩展，默认支持https

2019-12-16

1.优化初始化调用成功返回T1.json中增加返回datapath

2020-01-09
1.增加与JuSAPI.dll的兼容性
2.修改JuSApi.dll兼容模式下默认数据文件目录为./Data

2020-01-13
1.优化Init初始化出错时生成返回文件可靠性
2020-02-20
1.在线支付的订单，不推送do-new消息
2020-02-21
1.优化日志文件格式，可用LOG日志查看工具查看

2020-02-24

1.优化自动更新机制

2020-02-26

1.兼容新MQ推送格式

2.优化日志获取方式和自动更新机制

2020-02-27

1.修复DLL所在程序目录名称中有空格时导致初始化失败的问题

2020-04-13

1.增加支持Get参数中增加Seq来跟踪请求和返回

2.优化MQ连接、推送稳定性

2020-06-23

1.优化网络异常重连机制

2.优化订单推送补拉机制

3.优化接口初始化速度

2020-07-01
1.同步时间日志中，增加记录程序已使用内存方便跟踪

2020-07-09
1.MQTT服务独立成BIN进程模式，方便异常时重启

2020-07-22
1.新的更新进程，使用独立Update进程，更新更可靠
2.Gupdate.bin,Gmqtt.bin编译进DLL，方便更新发布

2020-07-28
1.增加打印支持GoDEX标签打印机

2020-07-30
1.增加http请求的UserAgent

2020-08-25
1.修复文件上传时，文件名有中文时上传失败

2020-09-09
1.主程序推送增加回调函数模式

2020-09-16
1.MQTT尝试改用DLL加载方式，避免IPC异常

2020-09-22
1.上传文件时，个别语言生成的文件名前会带上一个\u202a不可见特殊字符，需要兼容过滤

2020-12-26
1.增加订阅商家mc_xxxx推送消息

2021-02-06
1.增加支持使用IP接口地址模式，需要初始化时平台端返回useHostIP=1参数开关

2021-04-20
1.9100上传订单统一到API接口

2021-04-23
1.9100服务端口固定，并可以设置

2021-04-29
1.解决mc_xxx商家消息主题没有订阅的问题

2021-06-07
1.9100上传订单接口协议上传失败修复

2021-06-24
1.修复初始化传参订阅主题多个时丢失的问题

2021-07-15
1.启用四级接口域名，每个门店独立域名

2021-07-16
1.临时增加：cash-pay消息快捷支付并且桌台为空时不向接口推送

2021-11-16
1.增加sys_init调用限制，避免频繁重复调用

2021-11-29
1.修复老板通上传本地排重时返回的账单 列表格式错误问题
2.增加getcfg本地缓存
3.URL中会带上ACTION，方便日志跟踪

2021-12-02
1.Debug模式接口地址由t1.dc78.cn改为 test-debug.dc78.cn
2.初始化sys_init结果缓存key加上msid，避免同时调用两个门店读取脏数据

2021-12-25
1.增加do-sync推送排重，相同桌台60秒内视为重复，丢弃

2021-12-31
1.优化do-sync排重机制，15秒内以相同内容返回，不直接丢弃。

2022-01-04
1.优化do-sync,不再排重

2022-01-05
1.修复MQTT推送超时判断出错，导致超时消息未丢弃问题

2022-08-31

1.增加支持饿了么小票模式数据上传

2023-08-25

1.修复mqtt订阅丢失的问题

注意：这个DLL只适用于静态DLL调用方式，不适用动态调用。（不清楚调用方式的区别，请先联系我们的技术支持）

此DLL，将代替原接口协议中需要轮询方式调用的6.1/1.1/2.1，并且新接口将不再支持轮询接口

https加密通道：

部分商家网络被劫持等原因，导致http请求异常，可以使用https通道进行API请求，DLL支持https请求方式。

  DLL接口基本定义

一、DLL接口调用环节定义如下：

1.果盘平台：是指果盘线上业务平台

2.接口DLL：本文说明的GuoPAPI.dll

3.收银软件接口：收银软件为实现与果盘平台的对接而开发的接口程序，通过调用接口DLL与平台交互数据

二、DLL函数定义：

1.接口初始化函数：int _stdcall apiInit(char* 门店编号, char* ApiKey,int handle, char* extention)，用于初始化接口，接口程序退出前只需要调用一次。

2.业务接口函数：int  _stdcall apiCall(int msgid)，用于所有上行业务接口的调用。

3.接口退出关闭函数：int  _stdcall apiClose()，用于接口程序退出前调用,告知平台接口已退出。 

4.缓存读取函数：int _stdcall cacheGet(char* key,char* value),读取指定缓存内容，内容在value变参中返回，函数返回值为缓存有效期剩余时间(单位秒)

5.缓存保存函数：int _stdcall cachePut(char* key,char* value,int expires),设置缓存内容，expires为缓存有效期（单位秒）

三、数据交换文件定义：

1.数据采用文件交换方式，文件存在DLL同目录下。

2.文件内容数据格式：JSON,UTF-8格式，同时支持xml,ini格式，下面以json举例。

2.数据交换文件名第一部分，R为收银软件生成的文件，T、Tx为接口DLL生成的文件。第二部分为数字编号，一般为1、1001或更大，表示消息序号。文件后缀为.json

3.收银软件生成的文件R1.json，第一位R是固定的，后面的数字编号根据场景不同。

4.接口DLL生成的文件T1.json,第一位T是固定的，后面的数字编号根据场景不同，但一次请求R/T,请求/返回的数字编号是相同的。

5.特殊情况：接口DLL主动推送消息时，生成的文件名为Tx1001.json（其中1001为window消息体中LParam的值，此处以1001示例）。

6.交互文件格式范例：

以取消订单（协议1.7do_cancel为例)，请求R1.json文件内容：

{
"action": {
"action": "do_cancel"
},
"get": {
"id": 3738173,
"op": "user"
}
}

调用apiCall(1);返回的T1.json内容：

{
    "status": 1,
    "info": "提交成功",
    "payid": 6383378,
    "refund_status": 1,
    "refund_info": "退款成功"
}

一个典型的错误返回，T1.json内容

{
"status": 0,
"info": "订单号不存在:55837"
}

  DLL接口初始化函数

用于初始化接口，必须先进行一次初始化，才能调用后续的业务接口。否则会返回错误。

int _stdcall apiInit(char* 门店编号, char* ApiKey,int handle, char* extention)

参数说明：

1.门店编号，果盘后台的商家下的门店编号，参见0.2中的说明。 

2.ApiKey，果盘商家的接口签名密钥，参见0.2中的说明。

3.handle，收银系统接口程序的窗口句柄，用于接收主动推送的消息通知，需要实现消息处理流程。

4.extention,扩展参数，扩展参数目前支持如下：（多个参数项之间用&分隔）(应用id、应用密钥参见0.2说明)

①  应用ID（必填），例如：gpid=gp13************df

②  应用密钥（必填），例如:  gpsecret=30461a27b7b0871c********************1756

③  指定数据文件格式： format=json。可选format=xml,format=ini,默认为json。

④  指定数据文件存放目录： datapath=Data，注意为相对DLL文件所在的目录。另外指定目录后所有Tx/T/R数据交换文件都在此目录下。

⑤ 指定门店API接口协议：clientver=3.2，指定3.2版本表示已经实现do-sync协议对接，需要DLL版本3.2.x.x以上才能支持。

返回值：

返回1表示初始化成功，

返回非1表示初始化失败，具体错误信息在T0.json中。

  DLL工作模式

1.DLL有两种工作模式：

a.网关工作模式，DLL中将启用消息服务（下行接口服务），平台能及时发送消息到接口，用于接收订单、支付的网关的场景(网关模式普通接口也可以正常调用,如：菜品上传接口)。

b.普通接口模式，DLL仅作为主动调用的接口(上行接口)，用于收银系统主动发起调用的场景，如：扫码付、会员接口等。

2.两种模式启动方式：

a.网关工作模式，请在调用初始化接口时传入接收消息的Handle，进入网关工作模式（注意：一个门店只能开一个网关模式接口，多开会导致冲突）

b.普通接口模式，请在调用初始化时handle=0

  下行接口交互流程

接口DLL主动推送消息的情况(如线上订单、支付推送)，收银接口程序收到消息后直接读取文件，并根据文件的内容作相应的处理。

此业务场景下，所有交互文件的数字编号，以首次推送WINDOW消息使用的消息编号，直到这个业务完成。 交互时序图如下：

  推送消息相关定义

1.推送使用发送Window消息给收银软件接口程序的方式。

2.消息ID：WM_GPAPI_PUB=WM_USER+1883（或者直接2907）

3.消息中LParam=1001为一个整数，表示消息流水编号，为自增编号，一定时间内不会重复。

4.当LParam=1001时，对应消息数据文件名为Tx1001.json

5.重要：调用初始化时，DLL会向传入的窗口Handle发送一个握手消息，标志是消息体WParam = 1,请直接返回200即可（或者没有返回值），WParam=0的情况为正常的业务推送消息,请注意判断。

6.window自定义消息接收方式：

Delphi:

const WM_GPAPI_PUB = WM_USER+1883;

procedure onGPAPIMessage(var msg: TMessage): message WM_GPAPI_PUB;

begin

  if(msg.WParam=1) then  //握手消息，返回200，(777表示接收状态日志消息,WM_COPYDATA)
  begin
    msg.Result := 200;
  end
  else if msg.WParam=0 then
  begin
    sFile := 'Tx'+intToStr(msg.LParam)+'.json';
    //todo: 业务处理流程
    msg.Result := 200;  //如果此消息类型不想处理，或是需要异步处理，可以此处直接返回 666，则此消息不再重复推送。
  end;

end;

PB:

在PB中是窗口的OTHER事件里进行消息判断

if message.number = 2907 then
   执行你的处理
   return 1
else
   return 0
end if

C#

public const int WM_GPAPI_PUB =USER+1883;

protected override void DefWndProc ( ref System.Windows.Forms.Message m )
{
            switch(m.Msg)
            {
                case Message.WM_GPAPI_PUB:   

                //处理消息
                break;
                default:
                base.DefWndProc(ref m);   //调用基类函数处理非自定义消息。
　　　　　　　　　break;
            }
}

  上行接口交互流程

收银软件主动调用接口时，生成R1.json，生成文件后调用apiCall(1); 调用返回后，直接读取T1.json。

线下主动调用接口的业务场景，消息文件编号固定是1，请不要设置为其它值！交互时序图如下：

  上行业务接口函数

用于所有业务的接口调用。

int  _stdcall apiCall(int msgid)

参数的说明：

msgid：消息编号，整数值。不同的场景下有不同的值。msgid必须与生成的数据文件R1001.json的编号相符

返回值：

返回值一般等于msgid。具体返回的消息内容在文件中。如msgid=1001时，返回数据文件为T1001.json

  业务调用流程示例

1.线上订单推送流程

2.线上扫码秒付流程

  图片上传

图片上传按如下格式进行上传,以协议3.2上传菜品图片为例，

R1.json文件如下：调用apiCall(1);

{
"action": {
"action": "do_upload_pic"
},
"get": {
"gdsid": "000100276"
},
"post": {
"file": "U:\\20180817111115_79987.jpg"
}
}

  调用示例

Delphi 调用示例：

函数声明

function apiInit(const shopid: pansichar; const ApiKey: pansichar; const Handle: integer=0; const Extention:pansichar=0): integer;stdcall; external 'GuoPAPI.dll';
function apiCall(const MsgId: integer): integer; stdcall; external 'GuoPAPI.dll';

function apiClose(): integer; stdcall; external 'GuoPAPI.dll';

function cacheGet(const key:pansichar;value:pansichar): integer; stdcall; external 'GuoPAPI.dll';

function cachePut(const key:pansichar;const value:pansichar;expires: integer): integer; stdcall; external 'GuoPAPI.dll';

调用：

初始化：

apiInit(PAnsiChar(shopId),PAnsiChar(APiKey),handle,PAnsiChar(format));

接口调用：

apiCall(1001);

PB11 调用示例：

初始化
FUNCTION int  apiInit(ref string  msid, ref string  apikey, long handle, ref string ext) LIBRARY "GuoPAPI.dll"  ALIAS FOR "apiInit;ansi"
FUNCTION int apiCall(int msgid) LIBRARY "GuoPAPI.dll" ALIAS FOR "apiCall;ansi"

PB9 调用示例：

初始化
  
FUNCTION int  apiInit(string  msid, string  apikey, long handle, string ext) LIBRARY "GuoPAPI.dll"
FUNCTION int  apiCall(int msgid) LIBRARY "GuoPAPI.dll"

调用示例：

string ls_no ,ls_apikey  

string ls_temp
long i,h_wnd 

ls_no = sle_1.text 

ls_apikey = sle_2.text

h_wnd = handle(frmMain)

i = apiInit(ls_no, ls_apikey, h_wnd) 

string  str1 ,str2,  s 

BLOB  STR3 ,blob1 , blob2

str1 = sle_3.Text
str2 = sle_4.Text

///todo: save data to R1.json

///

i =  apiCall(1);

////todo: load data from T1.json

VB声明示例：

Public Declare Function apiInit Lib "GuoPAPI.dll" (ByVal msid As String, ByVal apikey As String, ByVal handle As Long, ByVal ext As String) As Integer

Public Declare Function apiCall Lib "GuoPAPI.dll" (ByVal msgid As Integer) As Integer