ZK SOAP SDK Manual
ZK SOAP SDK Manual
Version: 2.0
2006 .12
ZK SOAP interface development manual
2. Function ...........................................................................................................................7
2.1 Download Attendance log ...................................................................................................7
2.2 Download User information................................................................................................7
2.3 Download User Fingerprint Template .................................................................................8
2.4 Upload User Information ....................................................................................................8
2.5 Upload User Fingerprint Template......................................................................................8
2.6 Delete User..........................................................................................................................8
2.7 Get MachineTime................................................................................................................9
2.8 Setting Time to Machine .....................................................................................................9
2.9 Setting Parameter to Machine .............................................................................................9
2.10 Communication Password (security code).....................................................................9
2.11 Upgrade firmware .............................................................................................................9
2.12 Clear data ........................................................................................................................10
2.13 Refresh device’s database ...............................................................................................10
2.14 Reboot device..................................................................................................................10
1
! "#! $ % &
ZK SOAP interface development manual
Release history
Date Revision Change
1.1Summarize
1 SOAP Summary
SOAP is a lightweight protocol intended for exchanging structured information in a decentralized, distributed
environment. SOAP uses XML technologies to define an extensible messaging framework, which provides a
message construct that can be exchanged over a variety of underlying protocols. The framework has been
designed to be independent of any particular programming model and other implementation specific semantics.
Second, SOAP can be used over any from transport message and RPC all kind of system
• SOAP envelope structure has defined an whole framework that may express any content which the message
contain, who process these contents, and these contents may be optional or necessary.
• SOAP encoding rule define a series of mechanisms that exchange data type of the application.
• SOAP RPC defines an agreement that express the remote procedure call and the respond.
Although these three parts all together are described as a SOAP part, but their function are in intersection.
Special, the encapsulation and coding rule are defined in the different namespace, this module definition method
increased the simplicity to the SOAP envelope, beside of the SOAP encoding rule and the SOAPRPC agreement,
this standard also defined two binding agreements, which describes how to transmit the SOAP message which is
contained in the HTTP message whether there are HTTP extension the framework or not.
all SOAP message base on XML (more information please refer to the documents which related XML), for a
SOAP application message, the SOAP definition attribute and the attribute must include the correct namespace .
The SOAP application must be able to process SOAP namespace of the message which it received, and it may
process SOAP message that is without the SOAP namespace, they are same as result, just like it own the correct
namespace. SOAP defined two namespace (more related XML namespace information please t refer to related
XML documents)
2
! "#! $ % &
ZK SOAP interface development manual
SOAP message cannot contain the documents type statement, also cannot include the message handling
instruction. SOAP uses The " ID" Type " Id" attribute to assign only sign to attribute, simultaneously this
attribute is partial and do not need to verify. SOAP uses The " Uri-reference" Type " Href" attribute to assign
this value citation, simultaneously this attribute is partial and do not need to verify. So it comply with the
XML standard, the XMLSchema standard and the XML connection language standard style. Besides of SOAP
the mustUnderstand attribute and the SOAPactor attribute, generally allow the attribute and their value appears
in the XML documents example or Schema (two effects is same). In other words, the default value or the fix
value is stated by DTD or Schema, and set its value in the XML documents example is in semantic affinity.
3 SOAP envelopes
SOAP message is a XML document; include an essential SOAP envelope, optional header and an mandatory
SOAP body. In residual part of this standard, when mention SOAP message that refer to this XML documents.
In this defined attribute and attribute namespace sign is: “Http://schemas.xmlsoap.org/soap/envelope/"
1. In the XML documents to express this message, the envelope is the top layer attribute.
2. All quarters which use SOAP exchange information is dispersible and without prearrange, SOAP header has
provided with the mechanism that add certain essential element which is about this SOAP message (feature) to
the SOAP message. SOAP defines a few attribute that indicate this essential element (feature) whether could be
optional or who processes it.
3. SOAP body is a generic container in that it can contain the message finally the receiver wants. SAOP defines
an element named Fault for representing errors within the Body element when things go wrong. This is
essential because without a standard error representation.
Envelopes
SOAP Header
3
! "#! $ % &
ZK SOAP interface development manual
SOAP body
ZK fingerprint machine’s SOAP interface base on the built-in WebServer foundation, realized a lightweight
simple, extensible, and rich XML messaging framework for defining higher-level application protocols.
Note
1. Character set
This SOAP interface supports the character set that is the ISO8859-X series character coding, also the single
byte character set, simultaneously also supports partial double byte character coding ,like Chinese and so on
(Chinese and so on double byte character set possibly not to support in MS SOAP SDK, when use Chinese and
so on double byte character set, please refer to relative MS SOAP SDK technology documents which about
Chinese solution)
2. XML Formats
this SOAP interface support XML the standard WELL FORMAT formats, namely do not support high-level
XML the characteristic, like DTD data verification mode, regarding the SOAP " Header " in SOAP any content
will be neglected. this SOAP XML code format produces by the attribute value form,
$UJ9DOXH ā[[[[ā!$UJ!
$UJ!9DOXH![[[[9DOXH!$UJ!
cannot write is: xxxx the wrong code
1.2Agreement
If the format provided by SOAP-XML is different with WELL FORMAT or the name of visiting way does not
exist, the system will return 500 universality server faults.
✂ E.g The 404 error occur when visiting name make
mistake took HTTP head to return 404
Serve Name iWsService This Serve Name indicate that Web Server supply SAOP server
✂
HTTP Head Pursuant the SOAP-HTTP head rule, the description is follow
POST /iWsService HTTP/1.0 ‘Need SOAP sever
4
! "#! $ % &
ZK SOAP interface development manual
Content-Type: text/xml ‘Need to indicate that the XML is SOAP resolution format”.
Content-Length: nnnnn “Need to point out the size of SAOP request”. SOAPAction:”uri:someuri” ‘ Extension
HTTP protocol” show SOAP function field.
✂
There is a built-in WevServer in the equipment with the SOAP interface. Therefore only needs to develop the
SOAP client end communication.
1. May login the Microsoft official website to download the newest SDK, install the SDK, how to use the
Microsoft SDK, please refer to Microsoft help.
2. download to the data structure and read the function descriptions, such as, reads the T&A record
following form, may very clear see, the XML header, the XML structure body, and conclusion part.
<?xml version="1.0" standalone="no"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Body>
i. <GetAttLogResponse>
ii. …….
iii. …….
</GetAttLogResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
3. Please understood the sending and receiving of the SOAP request, its essential is the TCP/IP connection
request, and receive data.
4. Please understood XML DOM object use, the Microsoft SOAP SDK provided the object function to
process, contain the XML resolution, analyze and read in the node and so on.
5. the development flow chart as follow, please refer:
5
! "#! $ % &
ZK SOAP interface development manual
Do Other
Read data
Read DOM
Data handle
6. Term explanation:
Element, refers to XML some row, node. May regard the database operation the record volume as the some
corresponding row, please refer to understood.
Value: Up to corresponding attribute value. Like as Microsoft SOAP SDK SoapSerializer has the function
WriteString to be allowed to give some attribute to read in a value, please refer understood.
6
! "#! $ % &
ZK SOAP interface development manual
7. Development flow
no matter is the transmission or receive, all its essential is TCP\IP (or the HTTP request) transmits. The
middle transmission data all is the XML character data. The service end and the client process XML flow t, the
client end may depend on the SOAP SDK to produce the XML transmission request, to receive XML, analyzes
the XML node, simply completes communication, for the application, only needs to understand the SOAP the
simple application method.
2. Function
Order GetAttLog ✄
✄
✄
✄
Element PIN ✄
✄
✄
✄
Value Transfer “ALL” in, return all Attendance Log. Otherwise, return the user’s attendance logs which
✄
✄
✄
✄
Note:All Download function,if hava data,it result data,else,it result null note in xml.
Order GetUserInfo ✄
✄
✄
✄
Element PIN ✄
✄
✄
✄
Value Transfer “ALL” in, return all user information. Otherwise, return the user’s user information which
✄
✄
✄
✄
Password Password ✄
✄
✄
✄
Privilege Privilege ✄
✄
✄
✄
7
! "#! $ % &
ZK SOAP interface development manual
Order GetUserTemplate ✄
✄
✄
✄
Element PIN ✄
✄
✄
Value Transfer “ALL” in, return all user template,Transfer user No. in return the user’s fingerprint template
✄
✄
✄
✄
Valid The fingerprint template whether take effect, 1 is valid, 0 is not invalid.
✄
✄
✄
✄
Order SetUserInfo ✄
✄
✄
✄
Value Transfer user No. name etc in, the Node is same configure and sequence as Get User Info return node
✄
✄
✄
✄
Note:All SOAP request successfully and execute successfully or fail.it will return a note,include error
code,content,the content will tell you what about it.
When you upload user successfully,please use command of RefreshDB to resfresh the device’s
database.please refer the describe the command RefreshDB.
Order SetUserTemplate ✄
✄
✄
Note:
When you upload user successfully,please use command of RefreshDB to resfresh the device’s
database.please refer the describe the command RefreshDB.
Order DeleteUser ✄
✄
✄
✄
Element PIN ✄
✄
✄
✄
☎
Note:
8
! "#! $ % &
ZK SOAP interface development manual
When you upload user successfully,please use command of RefreshDB to resfresh the device’s
database.please refer the describe the command RefreshDB.
Order GetDate ✄
✄
✄
✄
Element Nothing ✄
✄
✄
Order SetDate ✄
✄
✄
✄
Order SetOption ✄
✄
✄
✄
✂
Note:
The parameter name are open by zksoftware.if you need,please contract with us,we will confirm and
open for you.
use the SOAP service to obtain data from the equipment, should first establish the connection password, each
time requestment all needs to verify password. .
Method key ✄
✄
✄
✄
Element Value ✄
✄
✄
✄
Note this method work in other way to request, this method must add in the SOAP request every time, the data
✄
✄
✄
✄
do not be returned until verify security code successfully, otherwise fail to return data.
Method: Update
9
! "#! $ % &