W-MBUS meter reading platform data exchange
interface specification
（Version 1.1）
Contents
1. Interface technology solution ........................................................................................................ 4
1.1 Web Service interface description ..................................................................................... 4
1.2 Interface parameter description......................................................................................... 4
1.3 Interface return value description ..................................................................................... 4
2. Interface Content and Protocol (Format) ........................................................................................ 6
2.1 Get device information ..................................................................................................... 6
2.1.1 Request parameter ................................................................................................. 6
2.1.2 Response result ...................................................................................................... 6
2.2 Get current device data ..................................................................................................... 7
2.2.1 Request parameter ................................................................................................. 7
2.2.2 Response result ...................................................................................................... 7
2.3 Issue control commands ................................................................................................... 8
2.3.1 Request parameter ................................................................................................. 8
2.3.2 Response result ...................................................................................................... 8
3. Web Interface Test Instructions ...................................................................................................... 9
3.1 Address ............................................................................................................................. 9
3.2 Parameters and return values ............................................................................................ 9
4. Appendix ..................................................................................................................................... 10
4.1 Appendix 1 (Encryption Algorithm) ............................................................................... 10
4.2 Appendix 2 ..................................................................................................................... 10
1. Interface technology solution
According to the relevant technical environment involved in the interface and the
characteristics of the application system, the system adopts standard protocols such as HTTP, soap,
FTP and SMTP based on TCP / IP network, and realizes data exchange between application
systems based on technical routes such as HTML, XML, web services or file transmission
The data exchange interface between the HAC Telecom NB meter reading platform and the
systems of other manufacturers is implemented using Web Service technology and based on the
SOAP over HTTP protocol.
This specification does not specify the service endpoint of the web service. According to the
final deployment, during the implementation of the service endpoint of web service, each
manufacturer's system shall be specified when applying for an account from NB meter reading
platform, and shall not be changed at will. In case of changes due to deployment or network
adjustment, HAC Telecom will notify each system to adjust in time.
1.1 Web Service interface description
Web Services uses Web Services Description Language (WSDL) to provide detailed
specifications of all messages supported by the service.
WSDL combines messages into operations. Operation is the logical unit of interaction with the
service, which is defined as a request message and any response messages related to it. This chapter
defines the data exchange Web Service interface and call parameters and return values. In addition
to specifying the operations associated with the service, the WSDL service specification also records
the communication channel-specific address of the service. The address information of the relevant
communication channel in the attached [Link] file is not a real service endpoint, please
refer to the description at the beginning of this chapter.
This specification specifies that each function operation of the data exchange interface of the
NB meter reading platform is synchronously called and processed. The data receiver will process
the request in time after receiving the requested operation, and feed back the specified response
message to the caller.
Encryption is used to verify the password information in the Web Service interface to ensure
login privacy.
1.2 Interface parameter description
In each interface called, the parameters include loginName and loginPassword, which are the
same as the login account and password of the NB meter reading platform (at this time, the password
is the string encrypted by the original password when logging in to the platform by the encryption
algorithm, see Appendix 1 for details). When the interface will get multiple pieces of data, the
parameters pageSize and pageIndex need to be passed in, which represent the number of data items
per page and the current page number, otherwise the default value will be used. When there is an
imei number in the parameter, if the description can be empty, and the user passes in a null value, it
means that all imei related data under the account is obtained.
1.3 Interface return value description
In each interface called, the return value is a Json string, and the internal unified format is:
{
"resultCode": "",
"resultMessage": "",
"data": "",
"rows": "",
"total": ""
}
Part of the key value may be empty. Among them, resultCode/resultMessage must have a value.
The content of resultCode is an integer, indicating a success or failure code. 1=success 0=failure;
resultMessage indicates the description of the returned result. If it is abnormal, then there will be a
corresponding exception message description. If the processing fails, the FAILED flag will be
returned. If the processing is successful, the SUCCESSFUL flag will be returned. If there is no
special description, all interfaces are common.
2. Interface Content and Protocol (Format)
2.1 Get device information
Query device information according to the requested conditions. Web Service interface method
name: getDeviceInfo
2.1.1 Request parameter
No. Field name Type Description
1 loginName String Login account name
2 loginPasswor String login password
d
3 startDate 8-digit date Installation start date, format: YYYYMMDD, default:
system date
4 endDate 8-digit date Installation deadline, format: YYYYMMDD, default:
system date
5 imei String IMEI number can be empty
6 pageSize Integer The number of data items per page, the default value is 50
7 pageIndex Integer The current page number, the default value is 1
Note: The interface will determine the system authority of the LoRA platform where it is based
on the incoming account and password, and return the relevant device information within the
authority. If the imei number is empty, it means to query all imei-related data under the account. If
pageSize/pageIndex is not passed, it means to use the platform default value.
2.1.2 Response result
Follow the return value description in 1.3.
No. Field
Key name Type Description
name
resultCode 1 Integer Success failure code, 1=success 0=failure
resultMessa 1 Description of the result returned this time
String
ge
1 imei String IMEI number
2 The platform code generated by the Telecom
platfor IoT. If it is empty, it means that the
String
mId registration on the Telecom IoT platform
has failed.
3 deviceI The equipment number is input by the List
String
data d operator on the NB meter reading platform may be
4 locatio Installation address empty
String
n
5 The name of the equipment shall be entered
name String by the operator on the Nb meter reading
platform
6 create 8-digit Installation date, format: YYYYMMDD
Time date
1 Number of response data May be
rows Integer
empty
1 Total number of records May be
total Integer
empty
2.2 Get current device data
Query the current (latest) data of the device according to the requested conditions. Web Service
interface method name: getDeviceCurrentData
2.2.1 Request parameter
No. Field name Type Description
1 loginName String Login account name
2 loginPasswor String login password
d
3 imei String IIMEI number can be empty
4 pageSize Integer The number of data items per page, the default value is 50
5 pageIndex Integer The current page number, the default value is 1
Note: The interface will determine the system authority of the LoRa platform where it is based
on the incoming account and password, and return the relevant device information within the
authority. If the imei number is empty, it means to query all imei-related data under the account. If
pageSize/pageIndex is not passed, it means to use the platform default value.
2.2.2 Response result
Follow the return value description in 1.3.
Key name No. Field name Type Description
1 Success failure code, 1=success
resultCode Integer
0=failure
resultMessa 1 Description of the result returned this
String
ge time
1 imei String IMEI number
2 Device number which may be
deviceId String changed after the device uploads
data
List may
data Data content, detailed parameters
returnComma Json be empty
3 please see appendix 3
nd String
4 Data receiving time, format:
reciveTime String
YYYYMMDDhhmmss
1 Number of response data May be
rows Integer
empty
1 Total number of records May be
total Integer
empty
Remarks: The interface provides all the data of related protocols, and users can choose what
they need and obtain them selectively.
2.3 Issue control commands
According to the specific instructions in the table, issue the control commands of the
corresponding equipment. Web Service interface method name: sentCommand
2.3.1 Request parameter
No. Field name Type Description
1 loginName String Login account name
2 loginPasswor String login password
d
3 imei String IMEI number
4 cmdType Integer Command type, 31=control valve, 50=set the bottom
number of the water meter
5 cmd String cmdType=31, then 0=open valve, 1=close valve;
cmdType=50, set the water meter reading, the minimum is
0, the maximum is 99999, which are integers;
6 pnVal Integer PN value, 0=0.5L/P, 1=1L/P, 2=10L/P, 3=100L/P,
4=1000L/P, 5=10000L/P; This item can be left blank when
controlling the valve
7 maxValue String Maximum number of digits, optional 9999999, 99999999,
9999999999.
This item can be left blank when controlling the valve
Remarks: The imei number cannot be empty. When waiting for the corresponding device to
report data, it will be issued one by one. If the same type of instruction is issued to the same device
(the switch valve counts as the same type of instruction), the LoRA platform will only cache the
latest one.
2.3.2 Response result
Follow the return value description in 1.3.
Key name No. Field name Type Description
1 Success failure code, 1=success
resultCode Integer
0=failure
resultMessa 1 Description of the result returned this
String
ge time
1 List is
data
empty
rows 1 empty
total 1 empty
3. Web Interface Test Instructions
3.1 Address
Each interface will provide a web page for testing, which is convenient for users to quickly
understand and obtain the validity of the data. The IP and port in the following address are not fixed
and should be valued according to the actual scenario.
Test address：[Link]
3.2 Parameters and return values
Each parameter of the interface on the web page needs to follow the documentation, and the
return value is displayed in Json string format.
4. Appendix
4.1 Appendix 1 (Encryption Algorithm)
WebService interface encryption algorithm file [Link]/[Link].
The login password of each interface is encrypted using the CBCEncrypt function. The
shared key of the encryption algorithm is the user name when the user logs in. The user name needs
to be in English or numbers. Other forms of characters are forbidden, such as Chinese. The length
of the shared key must be at least 4 characters. If it is less than 4, it will be the character "1" is added
until the length reaches 4 characters.
For example: the account and password when the original login platform is "abcd", "1111",
when calling the interface, the input should be "abcd", "QW0QI4Rxis0=".
4.2 Appendix 2
The IP and port in the access address of the WebService interface description language
are not fixed and should be selected according to the actual scenario.
Test address ：[Link]
Call instance (get device information):
Url : [Link]
Method: Post
Content-Type: application/xml
Raw:
<soapenv:Envelope
xmlns:soapenv="[Link]
xmlns:dat="[Link]
<soapenv:Header/>
<soapenv:Body>
<dat:getDeviceInfo>
<loginName>cqw</loginName>
<loginPassword>YdFEX5mgtd0==</loginPassword>
<startDate>20200101</startDate>
<endDate>20211018</endDate>
</dat:getDeviceInfo>
</soapenv:Body>
</soapenv:Envelope>