摘要

Push协议是基于超文本传输协议（HTTP）的基础上定义的数据协议，建立在TCP/IP连接上，主要应用于中控考勤设备与服务器的数据交互，定义了数据（用户信息、生物识别模板、考勤记录等）的传输格式、控制设备的命令格式；

特点

新数据主动上传
断点续传
所有行为都由客户端发起，比如上传数据、服务器下发的命令等

编码

协议中传输的数据大部分都是ASCII字符，但是个别的字段也涉及到编码的问题，比如用户姓名，所以对该类型数据做如下规定

为中文时，使用GB2312编码
为其他语言时，使用UTF-8编码

目前涉及到该编码的数据如下：

用户信息表的用户姓名

HTTP协议简介

Push协议是基于HTTP协议的基础上定义的数据协议，这里简单介绍下什么是HTTP协议，如果已经熟悉可跳过此部分。

HTTP协议是一种请求/响应型的协议。客户端给服务器发送请求的格式是一个请求方法（request method），URI，协议版本号，然后紧接着一个包含请求修饰符（modifiers），客户端信息，和可能的消息主体的类MIME（MIME-like）消息。服务器对请求端发送响应的格式是以一个状态行（status line），其后跟随一个包含服务器信息、实体元信息和可能的实体主体内容的类MIME（MIME-like）的消息。其中状态行（status line）包含消息的协议版本号和一个成功或错误码。如下例子

客户端请求：
GET http://113.108.97.187:8081/iclock/accounts/login/?next=/iclock/data/iclock/ HTTP/1.1
User-Agent: Fiddler
Host: 113.108.97.187:8081

服务器响应：
HTTP/1.1 200 OK
Server: nginx/0.8.12
Date: Fri, 10 Jul 2015 03:53:16 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: close
Content-Language: en
Expires: Fri, 10 Jul 2015 03:53:16 GMT
Vary: Cookie, Accept-Language
Last-Modified: Fri, 10 Jul 2015 03:53:16 GMT
ETag: "c487be9e924810a8c2e293dd7f5b0ab4"
Pragma: no-cache
Cache-Control: no-store
Set-Cookie: csrftoken=60fb55cedf203c197765688ca2d7bf9e; Max-Age=31449600; Path=/
Set-Cookie: sessionid=06d37fdc8f36490c701af2253af79f4a; Path=/

0

HTTP通信通常发生在TCP/IP连接上。默认端口是TCP 80，不过其它端口也可以使用。但并不排除HTTP协议会在其它协议之上被实现。HTTP仅仅期望的是一个可靠的传输（译注：HTTP一般建立在传输层协议之上）；所以任何提供这种保证的协议都可以被使用

定义

文档中引用定义使用格式为：${ServerIP}

ServerIP：服务器IP地址
ServerPort：服务器端口
XXX：未知值
Value1\Value2\Value3……\Valuen：值1\值2\值3……值n
Required：必须存在
Optional：可选
SerialNumber：系列号(可以为字母、数字、字母+数字组合)
NUL：null（\0）
SP：空格
LF：换行符（\n）
HT：制表符（\t）
DataRecord：数据记录
CmdRecord：命令记录
CmdID：命令编号
CmdDesc：命令描述
Pin：工号
Time：考勤时间
Status：考勤状态
Verify：验证方式
Workcode：workcode编码
Reserved：预留字段
OpType：操作类型
OpWho：操作者
OpTime：操作时间
BinaryData：二进制数据流
TableName：数据表名
SystemCmd：系统命令
Key：键
Value：值
FilePath：文件路径
URL：资源位置

功能

从客户端的角度来描述Push协议支持的功能

初始化信息交互
上传更新信息
上传数据
获取命令
命令回复

流程

使用Push协议的客户端和服务器，必须由客户端先发起“初始化信息交互”请求成功之后，才能使用其他功能，比如上传数据、获取服务器命令、上传更新信息、回复服务器命令等，其中这些功能并没有先后顺序，取决于客户端应用程序的开发，如下图

初始化信息交互

客户端发起请求，将相应的配置信息发送给服务器，服务器接收到该请求，将相应的配置信息回复给客户端，只有当客户端获取到相应的配置信息，才能算交互成功；配置信息交互是按照规定好的格式进行的，具体如下

客户端请求消息

GET /iclock/cdata?SN=${SerialNumber}&options=all&pushver=${XXX}&language=${XXX}&pushcommkey=${XXX} HTTP/1.1
Host: ${ServerIP}:${ServerPort}
……

注释：

HTTP请求方法使用：GET方法
URI使用：/iclock/cdata
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    options：${Required}表示获取服务器配置参数，目前值只有all
    pushver：${Optional}表示设备当前最新的push协议版本。
    language：${Optional}表示客户端支持的语言，新开发的客户端最好支持，服务端可通过该参数知道目前设备是什么语言，见“附录2”
    pushcommkey：${Optional}表示客户端与服务器绑定的密文信息，软件通过此密文判断设备是否经过授权，不同设备值一般是不一样的，该参数需要服务器支持之后，客户端才需支持
Host头域：${Required}
其他头域：${Optional}

服务器正常响应

HTTP/1.1 200 OK
Date: ${XXX}
Content-Length: ${XXX}
……

GET OPTION FROM: ${SerialNumber}${LF}${XXX}Stamp=${XXX}${LF}ErrorDelay=${XXX}${LF}Delay=${XXX}${LF}TransTimes=${XXX}${LF}TransInterval=${XXX}${LF}TransFlag=${XXX}${LF}TimeZone=${XXX}${LF}Realtime=${XXX}${LF}Encrypt=${XXX}${LF}ServerVer=${XXX}${LF}PushProtVer=${XXX}${LF}PushOptionsFlag=${XXX}${LF}PushOptions=${XXX}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Date头域：${Required}使用该头域来同步服务器时间，并且时间格式使用GMT格式，如Date: Fri, 03 Jul 2015 06:53:01 GMT
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
服务器端配置信息：
    第1行必须为该描述：GET OPTION FROM: ${SerialNumber}并且使用${LF}间隔配置信息，
    其中${SerialNumber}为客户端发起请求的系列号，配置信息是使用键值对的形式（key=value）并且不同配置之间使用${LF}间隔
    ${XXX}Stamp：各种数据类型的时间戳，目前支持如下
                            ${XXX}      数据类型
                            ATTLOG      考勤记录
                            OPERLOG     操作日志

            时间戳标记设计目的：客户端上传数据时会同时上传相应的时间戳标记，服务器负责记录该标记，当设备重启时，客户端发起初始化信息交互请求，
                服务器会将一系列的标记下发给客户端，从而达到客户端断点续传的功能
            时间戳标记缺陷：由于修改时间是被允许的，并且时间产生变化的不确定性因素也是可能存在的，会造成客户端无法正确判断出哪些数据已经上传到服务器，
                哪些数据未被上传，从而导致服务器数据丢失
            服务器对时间戳的应用：目前服务器对时间戳标记只有1个应用，当服务器需要重新上传所有相应的数据时，就会将相应的时间戳标记设置为0，功能参见“获取命令--控制命令--检查数据更新”
            客户端废弃时间戳：新架构固件Push设计上不使用时间戳来标记数据上传截点，但是为了兼容老的服务器，对时间戳标记也做了发送，实际过程中也只是应用了当标记被设置为0时，
                重新上传数据的功能，所以服务器并不需要区分客户端是否废弃时间戳

    ErrorDelay：联网失败后客户端重新联接服务器的间隔时间（秒），建议设置30~300秒
    Delay：正常联网时客户端联接服务器的间隔时间（秒） ，即客户端请求“获取命令”功能，建议设置2~60秒，需要快速响应时可设置小点，但是对服务器的压力会变大
    TransTimes：客户端定时检查并传送新数据时间（时:分，24小时格式），多个时间用分号分开，最多支持10个时间，如TransTimes=00:00;14:00
    TransInterval：客户端检查并传送新数据间隔时间（分钟），当设置为0时，不检查，如TransInterval=1
    TransFlag：客户端向服务器自动上传哪些数据的标识，设置的值支持两种格式
                格式一：TransFlag=1111000000……，每一位代表一种数据类型，0—表示禁止该数据类型自动上传，1—表示允许该数据类型自动上传
                            第几位     数据类型
                            1           考勤记录
                            2           操作日志//暂不支持
                            3           考勤照片//暂不支持
                            4           登记新指纹//暂不支持
                            5           登记新用户
                            6           指纹图片//暂不支持
                            7           修改用户信息
                            8           修改指纹//暂不支持
                            9           新登记人脸
                            10          用户照片
                            11          工作号码
                            12          比对照片
                格式二：TransFlag=TransData AttLog${HT}OpLog${HT}AttPhoto……
                            字符串标示       数据类型
                            AttLog          考勤记录
                            OpLog           操作日志//暂不支持
                            AttPhoto        考勤照片//暂不支持
                            EnrollUser      登记新用户
                            ChgUser         修改用户信息
                            EnrollFP        登记新指纹//暂不支持
                            ChgFP           修改指纹//暂不支持//暂不支持
                            FPImag          指纹图片//暂不支持
                            FACE            新登记人脸
                            UserPic         用户照片
                            WORKCODE        工作号码
                            BioPhoto        比对照片
                客户端新开发时：请同时支持两种格式，并且当服务器使用格式一下发，并且设置的值全部为0（TransFlag=0000000000）时，表示仅支持上传考勤照片
                服务端新开发时：支持格式二即可
    TimeZone：指定服务器所在时区，主要为了同步服务器时间使用，参见[获取命令](#downloadcmd)的Date头域
            取值为整数值，该值设计成支持整时区、半时区、1/4时区
            当 -12 < TimeZone < 12时，表示整时区，单位为小时，如TimeZone=4，表示东4区
            当 TimeZone > 60或TimeZone < -60时，可表示半时区、1/4时区，单位为分钟，如TimeZone=330，表示东5半区
    Realtime：客户端是否实时传送新记录。 为1表示有新数据就传送到服务器，为0表示按照 TransTimes 和 TransInterval 规定的时间传送 
    Encrypt：是否加密传送数据。
    EncryptFlag：数据加密的标识。
            举例：EncryptFlag=10000000
                    第几位     数据类型
                      1         考勤记录
            目前仅本协议2.3.0版本支持，并且只支持考勤记录加密。加密方式使用的是rc4。
    ServerVer：服务器版本。
    PushProtVer：服务端依据哪个协议版本开发的。
    PushOptionsFlag：软件是否支持设备推送配置参数请求，0不支持，1支持，未设置时默认不支持，参见
    PushOptions：软件需要设备推送的参数列表，格式：PushOptions=key1,key2,key3,……,keyN，如PushOptions=FaceFunOn

示例

客户端请求：
GET /iclock/cdata?SN=0316144680030&options=all&pushver=2.2.14&language=83&pushcommkey=4a9594af164f2b9779b59e8554b5df26 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*

服务器响应：
HTTP/1.1 200 OK 
Server: nginx/1.6.0
Date: Fri, 03 Jul 2015 06:53:01 GMT
Content-Type: text/plain
Content-Length: 190
Connection: close
Pragma: no-cache
Cache-Control: no-store

GET OPTION FROM: 0316144680030
ATTLOGStamp=None
OPERLOGStamp=9999
ATTPHOTOStamp=None
ErrorDelay=30
Delay=10
TransTimes=00:00;14:05
TransInterval=1
TransFlag=TransData AttLog  OpLog   AttPhoto    EnrollUser  ChgUser EnrollFP    ChgFP   UserPic
TimeZone=8
Realtime=1
Encrypt=None

上传更新信息

该功能复用获取命令请求，在其URL上加入参数，主要上传客户端的固件版本号、登记用户数、考勤记录数、设备IP地址、人脸算法版本、注册人脸所需人脸个数、登记人脸数、设备支持功能标示信息

客户端请求消息

Get /iclock/getrequest?SN=${SerialNumber}&INFO=${Value1},${Value2},${Value3},${Value4},${Value5},${Value6},${Value7},${Value8},${Value9},${Value10}
Host: ${ServerIP}:${ServerPort}
……

注释：

HTTP请求方法使用：GET方法
URI使用：/iclock/getrequest
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    ${Value1}：固件版本号
    ${Value2}：登记用户数
    ${Value3}：登记指纹数//暂不支持
    ${Value4}：考勤记录数
    ${Value5}：设备IP地址
    ${Value6}：指纹算法版本//暂不支持
    ${Value7}：人脸算法版本
    ${Value8}：注册人脸所需人脸个数
    ${Value9}：登记人脸数
    ${Value10}：设备支持功能标示，格式：1011，每一位代表一种功能，0—表示不支持该功能，1—表示支持该功能
                第几位     功能描述
                1           指纹功能llllll//暂不支持
                2           人脸功能
                3           用户照片功能
                4           比对照片功能
Host头域：${Required}
其他头域：${Optional}

服务器响应参见获取命令

示例

客户端请求：
GET /iclock/getrequest?SN=0316144680030&INFO=Ver%202.0.12-20150625,0,0,0,192.168.16.27,10,7,15,0,111 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*

服务器响应：
HTTP/1.1 200 OK 
Server: nginx/1.6.0
Date: Tue, 30 Jun 2015 01:24:26 GMT
Content-Type: text/plain
Content-Length: 2
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK

上传数据

具体哪些数据需要自动上传，服务器是可以控制的(详细见“初始化信息交互”的“TransFlag”参数)

上传的方式

    实时上传
    间隔上传
    定时上传

实时\间隔\定时三种上传方式，若支持实时，则间隔\定时方式不起作用
实时上传，设备本身默认支持，服务器是可以控制的(详细见“初始化信息交互”的“Realtime”参数)
间隔上传，具体的间隔时间服务器是可以控制的(详细见“初始化信息交互”的“TransInterval”参数)
定时上传，具体的上传时间点服务器是可以控制的(详细见“初始化信息交互”的“TransTimes”参数)

上传考勤记录

客户端请求消息

POST /iclock/cdata?SN=${SerialNumber}&table=ATTLOG&Stamp=${XXX} HTTP/1.1
Host: ${ServerIP}:${ServerPort}
Content-Length: ${XXX}
……

${DataRecord}

注释：

HTTP请求方法使用：POST方法
URI使用：/iclock/cdata
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    table=ATTLOG：${Required}表示上传的数据为考勤记录
    Stamp：${Optional}表示考勤记录上传到服务器的最新时间戳(详细见“初始化信息交互”的“Stamp”或者“ATTLOGStamp”参数)
Host头域：${Required}
Content-Length头域：${Required}
其他头域：${Optional}
请求实体：${DataRecord}，考勤记录数据，数据格式如下
    ${Pin}${HT}${Time}${HT}${Status}${HT}${Verify}${HT}${Workcode}${HT}${Reserved}${HT}${Reserved}
    注：
    ${Time}：验证时间，格式为XXXX-XX-XX XX:XX:XX，如2015-07-29 11:11:11
    多条记录之间使用${LF}连接

服务器正常响应消息

HTTP/1.1 200 OK
Content-Length: ${XXX}
……

OK:${XXX}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
响应实体：当服务器接收数据正常并处理成功时回复OK:${XXX}，其中${XXX}表示成功处理的记录条数，当出错时，回复错误描述即可

示例

客户端请求：
POST /iclock/cdata?SN=0316144680030&table=ATTLOG&Stamp=9999 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*
Content-Length: 315

1452    2015-07-30 15:16:28 0   1   0   0   0
1452    2015-07-30 15:16:29 0   1   0   0   0
1452    2015-07-30 15:16:30 0   1   0   0   0
1452    2015-07-30 15:16:31 0   1   0   0   0
1452    2015-07-30 15:16:33 0   1   0   0   0
1452    2015-07-30 15:16:34 0   1   0   0   0
1452    2015-07-30 15:16:35 0   1   0   0   0
8965    2015-07-30 15:16:36 0   1   0   0   0
8965    2015-07-30 15:16:37 0   1   0   0   0

服务器响应：
HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Thu, 30 Jul 2015 07:25:38 GMT
Content-Type: text/plain
Content-Length: 4
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK:9

上传用户信息

初始化信息交换服务器下发的配置PushProtVer参数大于等于2.2.14版本

客户端请求消息

POST /iclock/cdata?SN=${SerialNumber}&table=OPERLOG&Stamp=${XXX} HTTP/1.1
Host: ${ServerIP}:${ServerPort}
Content-Length: ${XXX}
……

${DataRecord}

注释：

HTTP请求方法使用：POST方法
URI使用：/iclock/cdata
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    table=OPERLOG：${Required}
    Stamp：${Optional}表示用户信息到服务器的最新时间戳(详细见“初始化信息交互”的“OPERLOGStamp”参数)
Host头域：${Required}
Content-Length头域：${Required}
其他头域：${Optional}
请求实体：${DataRecord}，用户信息数据，数据格式如下
    USER${SP}PIN=${XXX}${HT}Name=${XXX}${HT}Pri=${XXX}${HT}Passwd=${XXX}${HT}Card=${XXX}${HT}Grp=${XXX}${HT}TZ=${XXX}${HT}Verify=${XXX}${HT}ViceCard=${XXX}
    注：
    Name=${XXX}：用户姓名，当设备为中文时，使用的是GB2312编码，其他语言时，使用UTF-8编码
    Card=${XXX}：用户卡号（主卡），值支持两种格式
        a、十六进制数据，格式为[%02x%02x%02x%02x]，从左到右表示第1、2、3、4个字节，如卡号为123456789，则为：Card=[15CD5B07]
        b、字符串数据，如卡号为123456789，则为：Card=123456789
    TZ=${XXX}：用户使用的时间段编号信息，值格式为
        XXXXXXXXXXXXXXXX，1到4字符描述是否使用组时间段，5到8字符描述使用个人时间段1，9到12字符描述使用个人时间段2，13到16字符描述使用个人时间段3
        如：0000000000000000，表示使用组时间段
           0001000200000000，表示使用个人时间段，且个人时间段1使用时间段编号2的时间信息
           0001000200010000，表示使用个人时间段，且个人时间段1使用时间段编号2的时间信息，个人时间段2使用时间段编号1的时间信息
    Verify=${XXX}：用户验证方式, 不包含该字段、值为空时或者设置为-1(使用组验证方式，如果没有门禁组，组验证方式为0)，否则见【附录7】
    ViceCard=${XXX}：用户卡号(副卡)，字符串数据，如卡号为123456789，则为：ViceCard=123456789
    多条记录之间使用${LF}连接

服务器正常响应消息

HTTP/1.1 200 OK
Content-Length: ${XXX}
……

OK:${XXX}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
响应实体：当服务器接收数据正常并处理成功时回复OK:${XXX}，其中${XXX}表示成功处理的记录条数，当出错时，回复错误描述即可

示例

客户端请求：
POST /iclock/cdata?SN=0316144680030&table=OPERLOG&Stamp=9999 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*
Content-Length: 166

USER PIN=36234  Name=36234  Pri=0   Passwd= Card=133440 Grp=1   TZ=0001000000000000
USER PIN=36235  Name=36235  Pri=0   Passwd= Card=133441 Grp=1   TZ=0001000000000000

服务器响应：
HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Thu, 30 Jul 2015 07:25:38 GMT
Content-Type: text/plain
Content-Length: 4
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK:2

上传用户照片

初始化信息交换服务器下发的配置PushProtVer参数大于等于2.2.14版本

客户端请求消息

POST /iclock/cdata?SN=${SerialNumber}&table=OPERLOG&Stamp=${XXX} HTTP/1.1
Host: ${ServerIP}:${ServerPort}
Content-Length: ${XXX}
……

${DataRecord}

注释：

HTTP请求方法使用：POST方法
URI使用：/iclock/cdata
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    table=OPERLOG：${Required}
    Stamp：${Optional}表示用户照片到服务器的最新时间戳(详细见“初始化信息交互”的“OPERLOGStamp”参数)
Host头域：${Required}
Content-Length头域：${Required}
其他头域：${Optional}
请求实体：${DataRecord}，用户照片数据，数据格式如下
    USERPIC${SP}PIN=${XXX}${HT}FileName=${XXX}${HT}Size=${XXX}${HT}Content=${XXX}
    注：
    FileName=${XXX}：用户照片的文件名，目前只支持jpg格式
    Content=${XXX}：传输用户照片时，需要对原始二进制用户照片进行base64编码
    Size=${XXX}：用户照片base64编码之后的长度
    多条记录之间使用${LF}连接

服务器正常响应消息

HTTP/1.1 200 OK
Content-Length: ${XXX}
……

OK:${XXX}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
响应实体：当服务器接收数据正常并处理成功时回复OK:${XXX}，其中${XXX}表示成功处理的记录条数，当出错时，回复错误描述即可

示例

客户端请求：
POST /iclock/cdata?SN=0316144680030&table=OPERLOG&Stamp=9999 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*
Content-Length: 1684

USERPIC PIN=123 FileName=123.jpg    Size=10 Content=AAAAAAAAAA……


服务器响应：
HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Thu, 30 Jul 2015 07:25:38 GMT
Content-Type: text/plain
Content-Length: 4
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK:1

上传比对照片

初始化信息交换服务器下发的配置PushProtVer参数大于等于2.2.14版本

客户端请求消息

POST /iclock/cdata?SN=${SerialNumber}&table=OPERLOG&Stamp=${XXX} HTTP/1.1
Host: ${ServerIP}:${ServerPort}
Content-Length: ${XXX}
……

${DataRecord}

注释：

HTTP请求方法使用：POST方法
URI使用：/iclock/cdata
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
    table=OPERLOG：${Required}
    Stamp：${Optional}表示用户照片到服务器的最新时间戳(详细见“初始化信息交互”的“OPERLOGStamp”参数)
Host头域：${Required}
Content-Length头域：${Required}
其他头域：${Optional}
请求实体：${DataRecord}，用户照片数据，数据格式如下
    BIOPHOTO${SP}PIN=${XXX}${HT}FileName=${XXX}${HT}Type=${XXX}${HT}Size=${XXX}${HT}Content=${XXX}
    注：
    FileName=${XXX}：生物特征图片的文件名，目前只支持jpg 格式
    值 意义
    0 通用的
    1 指纹
    2 面部
    3 声纹
    4 虹膜
    5 视网膜
    6 掌纹
    7 指静脉
    8 手掌
    Size=${XXX}：生物特征图片base64 编码之后的长度
    Content=${XXX}：传输时，需要对原始二进制生物特征图片进行base64 编码

服务器正常响应消息

HTTP/1.1 200 OK
Content-Length: ${XXX}
……

OK:${XXX}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
响应实体：当服务器接收数据正常并处理成功时回复OK:${XXX}，其中${XXX}表示成功处理的记录条数，当出错时，回复错误描述即可

示例

客户端请求：
POST /iclock/cdata?SN=0316144680030&table=OPERLOG&Stamp=9999 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*
Content-Length: 1684

BIOPHOTO PIN=123    FileName=123.jpg    Type=2  Size=95040  Content=AAAA........


服务器响应：
HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Thu, 30 Jul 2015 07:25:38 GMT
Content-Type: text/plain
Content-Length: 4
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK:1

获取命令

如果服务器需要对设备进行操作，需先生成命令格式，等待设备发起请求时，再将命令发送到设备，对于命令的执行结果见回复命令

客户端请求消息

Get /iclock/getrequest?SN=${SerialNumber}
Host: ${ServerIP}:${ServerPort}
……

注释：

HTTP请求方法使用：GET方法
URI使用：/iclock/getrequest
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
Host头域：${Required}
其他头域：${Optional}

服务器正常响应消息

当无命令时，回复信息如下：
HTTP/1.1 200 OK
Date: ${XXX}
Content-Length: 2
……

OK

当有命令时，回复信息如下：
HTTP/1.1 200 OK
Date: ${XXX}
Content-Length: ${XXX}
……

${CmdRecord}

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Date头域：${Required}使用该头域来同步服务器时间，并且时间格式使用GMT格式，如Date: Fri, 03 Jul 2015 06:53:01 GMT
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述
响应实体：${CmdRecord}，下发的命令记录，数据格式如下
    C:${CmdID}:${CmdDesc}${SP}${XXX}
    注：
    ${CmdID}：该命令编号是由服务器随机生成的，支持数字、字母，长度不超过16，客户端回复命令时需带上该命令编号，详细见下面“回复命令”功能
    ${CmdDesc}：命令描述分为数据命令和控制命令，数据命令统一为“DATA”描述，详细见下面“数据命令”功能，各种控制命令为各种不同的描述
    多条记录之间使用${LF}连接

DATA 命令

当服务器下发的命令中${CmdDesc}为“DATA”时，就认为该命令为数据命令，可以对客户端的数据进行增、删、改、查操作，但是具体的不同的业务数据可支持的操作是不一样的，下面将详述

UPDATE 子命令

新增或修改数据，是新增还是修改取决于客户端是否存在相应的数据，服务器无需关心，命令格式如下

C:${CmdID}:DATA${SP}UPDATE${SP}${TableName}${SP}${DataRecord}
说明：
UPDATE：使用该描述表示新增或修改数据操作
${TableName}：不同的业务数据表名，比如用户信息为USERINFO，具体支持的数据如下描述
${DataRecord}：业务数据记录，使用key=value的形式，不同业务数据，key描述是不一样的，具体如下描述

用户信息

命令格式如下

C:${CmdID}:DATA${SP}UPDATE${SP}USERINFO${SP}PIN=${XXX}${HT}Name=${XXX}${HT}Pri=${XXX}${HT}Passwd=${XXX}${HT}Card=${XXX}${HT}Grp=${XXX}${HT}TZ=${XXX}${HT}Verify=${XXX}${HT}ViceCard=${XXX}
说明：
PIN=${XXX}：用户工号
Name=${XXX}：用户姓名，当设备为中文时，使用的是GB2312编码，其他语言时，使用UTF-8编码
Pri=${XXX}：用户权限值，值意义如下
    值       描述
    0       普通用户
    2       登记员
    6       管理员
    10      用户自定义
    14      超级管理员
Passwd=${XXX}：密码
Card=${XXX}：卡号，值支持两种格式
    a、十六进制数据，格式为[%02x%02x%02x%02x]，从左到右表示第1、2、3、4个字节，如卡号为123456789，则为：Card=[15CD5B07]
    b、字符串数据，如卡号为123456789，则为：Card=123456789
Grp=${XXX}：用户所属组，默认属于1组
TZ=${XXX}：用户使用的时间段编号信息，值格式为
    XXXXXXXXXXXXXXXX，1到4字符描述是否使用组时间段，5到8字符描述使用个人时间段1，9到12字符描述使用个人时间段2，13到16字符描述使用个人时间段3
    如：0000000000000000，表示使用组时间段
       0001000200000000，表示使用个人时间段，且个人时间段1使用时间段编号2的时间信息
       0001000200010000，表示使用个人时间段，且个人时间段1使用时间段编号2的时间信息，个人时间段2使用时间段编号1的时间信息

Verify=${XXX}：用户验证方式, 不包含该字段、值为空时或者设置为-1(使用组验证方式，如果没有门禁组，组验证方式为0)，否则见【附录7】
ViceCard=${XXX}：用户卡号(副卡)，字符串数据，如卡号为123456789，则为：ViceCard=123456789

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

会议信息

命令格式如下

C:${CmdID}:DATA${SP}UPDATE${SP}MEETINFO${SP}MetName=${XXX}${HT}MetStarSignTm=${XXX}${HT}MetLatSignTm=${XXX}${HT}EarRetTm=${XXX}${HT}LatRetTm={XXX}${HT}Code=${XXX}${HT}MetStrTm=${XXX}${HT}MetEndTm=${XXX}
说明：
MetName=${XXX}：会议名称
MetStarSignTm=${XXX}：会议开始签到时间       时间格式：YYYY-MM-DDThh:mm:ss
MetLatSignTm=${XXX}：最迟签到时间          时间格式：YYYY-MM-DDThh:mm:ss
EarRetTm=${XXX}：最早签退时间              时间格式：YYYY-MM-DDThh:mm:ss
LatRetTm={XXX}：最晚签退时间               时间格式：YYYY-MM-DDThh:mm:ss
Code=${XXX}：会议ID，此为会议信息唯一值      时间格式：YYYY-MM-DDThh:mm:ss
MetStrTm=${XXX}：会议开始时间              时间格式：YYYY-MM-DDThh:mm:ss
MetEndTm=${XXX}：会议结束时间              时间格式：YYYY-MM-DDThh:mm:ss

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

会议人员信息

命令格式如下

C:${CmdID}:DATA${SP}UPDATE${SP}PERSMEET${SP}Code=${XXX}${HT}Pin=${XXX}
说明：
Code=${XXX}：会议ID，此为会议信息唯一值
Pin=${XXX}：用户工号

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

比对照片

命令格式如下

C:${CmdID}:DATA${SP}UPDATE${SP}BIOPHOTO${SP}PIN=${XXX}${HT}Type=${XXX}${HT}Size=${XXX}${HT}Content=${XXX}
说明：
PIN=${XXX}：用户工号
Type=${XXX}：生物特征图片类型：
    值 意义
    0 通用的
    1 指纹
    2 面部
    3 声纹
    4 虹膜
    5 视网膜
    6 掌纹
    7 指静脉
    8 手掌
Size=${XXX}：生物特征图片二进制数据经过base64 编码之后的长度
Content=${XXX}：传输生物特征图片时，需要对原始二进制生物特征图片进行base64 编码

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

DELETE 子命令

删除数据，命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}${TableName}${SP}${DataRecord}
说明：
DELETE：使用该描述表示删除数据操作
${TableName}：不同的业务数据表名，比如用户信息为USERINFO，具体支持的数据如下描述
${DataRecord}：删除数据的条件，不同业务数据，支持的条件不一样，具体如下描述

用户信息

命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}USERINFO${SP}PIN=${XXX}
说明：
PIN=${XXX}：用户工号
删除指定的用户信息，包括指纹模版、面部模版、用户照片、比对照片等相关信息

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

会议信息

命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}MEETINFO${SP}Code=${XXX}
说明：
Code=${XXX}：会议ID，此为会议信息唯一值

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

会议人员信息

命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}PERS_MEET${SP}Code=${XXX}
C:${CmdID}:DATA${SP}DELETE${SP}PERS_MEET${SP}Pin=${XXX}
C:${CmdID}:DATA${SP}DELETE${SP}PERS_MEET${SP}Code=${XXX}${HT}Pin=${XXX}

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

用户照片

命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}USERPIC${SP}PIN=${XXX}
说明：
PIN=${XXX}：用户工号
删除指定用户的用户照片

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

比对照片

命令格式如下

C:${CmdID}:DATA${SP}DELETE${SP}BIOPHOTO${SP}PIN=${XXX}
说明：
PIN=${XXX}：用户工号
删除指定用户的比对照片

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

QUERY 子命令

查询数据，命令格式如下

C:${CmdID}:DATA${SP}QUERY${SP}${TableName}${SP}${DataRecord}
说明：
QUERY：使用该描述表示查询数据操作
${TableName}：不同的业务数据表名，比如用户信息为USERINFO，具体支持的数据如下描述
${DataRecord}：查询数据的条件，不同业务数据，支持的条件不一样，具体如下描述

用户信息

命令格式如下

C:${CmdID}:DATA${SP}QUERY${SP}USERINFO${SP}PIN=${XXX}
说明：
PIN=${XXX}：用户工号

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DATA

查询指定用户的基本信息，如何上传详见“上传用户信息”

CLEAR 命令

清除会议信息

清除客户端的会议信息，命令格式如下

C:${CmdID}:CLEAR${SP}MEETINFO
说明：
使用CLEAR${SP}MEETINFO描述该命令

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=CLEAR_MEETINFO
说明：
CMD=CLEAR_MEETINFO：使用CLEAR_MEETINFO描述该命令

清除会议人员信息

清除客户端的考勤记录，命令格式如下

C:${CmdID}:CLEAR${SP}PERSMEET
说明：
使用CLEAR${SP}PERSMEET描述该命令

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=CLEAR_PERSMEET
说明：
CMD=CLEAR_PERSMEET：使用CLEAR_PERSMEET描述该命令

清除全部数据

清除客户端的全部数据，命令格式如下

C:${CmdID}:CLEAR${SP}DATA
说明：
使用CLEAR${SP}DATA描述该命令

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=CLEAR_DATA
说明：
CMD=CLEAR_DATA：使用CLEAR_DATA描述该命令

检查命令

检查数据更新

要求客户端从服务器读取配置信息，详见"初始化信息交换"，并根据时间戳重新上传对应的数据到服务器，目前只支持服务器将时间戳重置为0，比如设置参数Stamp=0，客户端读取配置参数之后将重新上传考勤记录，命令格式如下

C:${CmdID}:CHECK
说明：
使用CHECK描述该命令

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=CHECK

发送客户端的信息到服务器

服务器获取客户端配置等信息，命令格式如下

C:${CmdID}:INFO
说明：
使用INFO描述该命令

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=INFO${LF}${Key}=${Value}${LF}${Key}=${Value}${LF}${Key}=${Value}${LF}${Key}=${Value}……
说明：
CMD=INFO后面跟着具体的客户端配置信息，以键值对的形式组成

下发广告命令

功能1

服务器将指定的广告文件发送到设备上，命令格式如下

C:${CmdID}:PutAdvFile${SP}Type=${XXX}${HT}Url=${XXX}
说明：
Type=${XXX}：类型：1， 照片  2，  视频  
Url=${XXX}：服务器文件存放地址。

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下： ID=${XXX}&Return=${XXX}&CMD=PutAdvFile

功能2

服务器删除设备上的广告

C:${CmdID}:DelAdvFile${SP}Type=${XXX}${HT}FileName=${XXX}
说明：
Type=${XXX}：广告类型：1 照片  2  视频
FileName=${XXX}：文件名
如果没有FileName，Type = 1，删除全部广告照片，Type = 2，删除全部广告视频

命令执行结果如何回复见回复命令功能，Return返回值见附录1，返回内容格式如下：

ID=${XXX}&Return=${XXX}&CMD=DelAdvFile

命令回复

客户端在获取到服务器下发的命令后，需要对相应的命令进行回复

客户端请求消息

POST /iclock/devicecmd?SN=${SerialNumber}
Host: ${ServerIP}:${ServerPort}
Content-Length: ${XXX}
……

${CmdRecord}

注释：

HTTP请求方法使用：GET方法
URI使用：/iclock/devicecmd
HTTP协议版本使用：1.1
客户端配置信息：
    SN：${Required}表示客户端的序列号
Host头域：${Required}
Content-Length头域：${Required}
其他头域：${Optional}
响应实体：${CmdRecord}，回复的命令记录，回复的内容都会包含ID\Return\CMD信息，含义如下
    ID：服务器下发命令的命令编号
    Return：客户端执行命令之后的返回结果
    CMD：服务器下发命令的命令描述
    少部分回复会包含其他信息，具体回复内容格式请看各个命令的说明
    多条命令回复记录之间使用${LF}连接

服务器正常响应消息

HTTP/1.1 200 OK
Date: ${XXX}
Content-Length: 2
……

OK

注释：

HTTP状态行：使用标准的HTTP协议定义
HTTP响应头域：
    Date头域：${Required}使用该头域来同步服务器时间，并且时间格式使用GMT格式，如Date: Fri, 03 Jul 2015 06:53:01 GMT
    Content-Length头域：根据HTTP 1.1协议，一般使用该头域指定响应实体的数据长度，如果是在不确定响应实体的大小时，也支持Transfer-Encoding: chunked，Content-Length及Transfer-Encoding头域均是HTTP协议的标准定义，这里就不在详述

示例

客户端请求：
POST /iclock/devicecmd?SN=0316144680030 HTTP/1.1
Host: 58.250.50.81:8011
User-Agent: iClock Proxy/1.09
Connection: close
Accept: */*
Content-Length: 143

ID=info8487&Return=0&CMD=DATA
ID=info8488&Return=0&CMD=DATA
ID=info8489&Return=0&CMD=DATA
ID=info7464&Return=0&CMD=DATA
ID=fp7464&Return=0&CMD=DATA

服务器响应：
HTTP/1.1 200 OK
Server: nginx/1.6.0
Date: Tue, 30 Jun 2015 01:24:48 GMT
Content-Type: text/plain
Content-Length: 2
Connection: close
Pragma: no-cache
Cache-Control: no-store

OK

附录1

通用错误码	描述
0	成功
-1	参数错误
-2	传输用户照片数据与给定的Size不匹配
-3	读写错误
-9	传输的模板数据与给定的Size不匹配
-10	设备中不存在PIN所指定的用户
-11	非法的指纹模板格式
-12	非法的指纹模板
-1001	容量限制
-1002	设备不支持
-1003	命令执行超时
-1004	数据与设备配置不一致
-1005	设备忙
-1006	数据太长
-1007	内存错误
-1008	获取服务器数据失败

Enroll_FP/Enroll_BIO错误码	描述
2	登记用户指纹，对应用户的指纹已经存在
4	登记用户指纹，登记失败，通常由于指纹质量太差，或者三次按的指纹不一致
5	登记用户指纹，登记的指纹已经在指纹库中存在
6	登记用户指纹，取消登记
7	登记用户指纹，设备忙，无法登记

PutFile（Action=SyncData）错误码	描述
n > 0	同步数据，成功处理n条指令

附录2

语言编号	意义
83	简体中文
69	英文
97	西班牙语
70	法语
66	阿拉伯语
80	葡萄牙语
82	俄语
71	德语
65	波斯语
76	泰语
73	印尼语
74	日本语
75	韩语
86	越南语
116	土耳其语
72	希伯来语
90	捷克语
68	荷兰语
105	意大利语
89	斯洛伐克语
103	希腊语
112	波兰语
84	繁体

附录3 验证方式码描述

验证方式	描述
0	指静脉或人脸或指纹或卡或密码 (自动识别)
1	仅指纹
2	工号验证
3	仅密码
4	仅卡
5	指纹或密码
6	指纹或卡
7	卡或密码
8	工号加指纹
9	指纹加密码
10	卡加指纹
11	卡加密码
12	指纹加密码加卡
13	工号加指纹加密码
14	工号加指纹或卡加指纹
15	人脸
16	人脸加指纹
17	人脸加密码
18	人脸加卡
19	人脸加指纹加卡
20	人脸加指纹加密码
21	指静脉
22	指静脉加密码
23	指静脉加卡
24	指静脉加密码加卡
25	掌纹
26	掌纹加卡
27	掌纹加面部
28	掌纹加指纹
29	掌纹加指纹加面部
200	其他

考勤Push协议文档

company: ZKTeco Inc

web: www.zkteco.com

author: yangt

mail: thomas.yan@zkteco.com

date: 2018-05-11