HTTP API User Guide
1 Introduction
The device works as a HTTP server and provides HTTP API interface. When a client sends a HTTP Post request to a server, the requested parameters will be packaged with XML. When the device receives the request and replies, the results will be packaged with XML, too.
1.1 Protocol Introduction
Fanvil HTTP API supports both HTTP and HTTPS protocol and is specified on server side.
Users can specify the client IP address to enable the server only accept the requests from
specified IP address. Device configuration: “PUSH XML Server IP”
It supports user authentication and server side can verify the web administrator account
1.2 HTTP POST Example
Client packs the request commands in XML and sends HTTP POST request to server:
POST http://ip/xmlService
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes” cmd=”set” >
<Item> sip.line.1.EnableReg = 1</Item>
<Item> sip.line.1.RegisterAddr = 172.16.1.3</Item>
<Item> sip.line.1.RegisterUser = 8218</Item>
<Item> sip.line.1.RegisterPswd = 8218</Item>
The server receives POST and replies, the format of the reply should be:
Server replies after it receives the POST request. The response format should be:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”set”>
<RetCode>0</RetCode>
</ FanvilConfiguration>
Compatible with previous PUSH XML, phones expand their PUSH XML. Therefore, when server sends previous XML, phones can still handle it normally
| The supported PUSH XML type | Function Descriptions | Remark |
| TextScreen | Push text message | |
| Menu | Push menu | |
| Directory | Push contact list | Online view, not saved |
| Execute | Push execute uri | Call, access uri |
| Configuration | Push configuration | |
| Input | Users input message |
2 Interface Introduction
The XML format of POST is as followed:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes”cmd=”set” > ……
</FanvilConfiguration>
New parameters ‘type’ and ‘cmd’ are added based on previous versions.
| New Parameter | Parameter Value Range | Parameter Description |
| Cmd | Get, Set, Del | Specified API type, and supported operations |
The format of server’s response should be:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”set”>
<RetCode>0</RetCode>
<Info> ……
</Info>
</ FanvilConfiguration >
The response parameter descriptions
| Parameter | Parameter Value Range | Parameter Description |
| RetCode | 0, …… | The server’s return code for processing request: 0 stands for
success while others mean abnormal. Please refer to appendix for specific values. |
| Info | When server replies the request, detailed data is packed in Info. Optional. For some requests, Info is needless and server just returns the result code. |
2.1 Config
To operate the system configurations, users can use NC to operate specified parameter. The supported commands are:
| Command | Description |
| GET | GET is used for getting value of specified parameter. Users can get one parameter’s value or the values of all parameters of one same
nodes. For example, getting the value of ‘sip.line.1.’ means all parameters’ value of SIP Line1 will be read. |
| SET | SET is used for configuring the value of specified parameter and all the parameters value are set with nc’s name. |
| DEL | DEL is used for deleting data of dynamic list type. Users can delete data directly with index since ‘.’ means clearing the list. |
2.1.1 GET
Client—->Server request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”get” >
<Item> sip.line.1. </Item>
<Item> tr069.Enabled </Item>
<Item> tr069.ACSURL </Item>
</FanvilConfiguration>
‘Sip.line.1.’ means to getting all values of the parameters of Sip line 1.
‘.’ means the top configuration node, which requires to get all the configuration parameters.
Server—>Client response
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”get” >
<RetCode>0</RetCode>
<info>
<Item> sip.line.1.RegisterAddr = 172.16.1.2 </Item>
<Item> sip.line.1.RegisterUser = 2190 </Item>
<Item> sip.line.1.RegisterPswd = 2190 </Item> ……
<Item> tr069.Enabled = 1 </Item>
<Item> tr069.ACSURL = http://fdms.fanvil.com </Item>
</info>
</FanvilConfiguration>
When there is an error in GET’s parameter, which makes the system unable to deal with it, the result should be returned with the parameter whose value should be emptied and other parameters and their values which are unchanged.
2.1.2 SET
Client—>Server Request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes” cmd=”set” >
<Item> sip.line.1.EnableReg = 1</Item>
<Item> sip.line.1.RegisterAddr = 172.16.1.3</Item>
<Item> sip.line.1.RegisterUser = 8218</Item>
<Item> sip.line.1.RegisterPswd = 8218</Item>
<Item> sip.PNPIP = 224.0.1.75</Item>
<Item> call.port.1.EnableDND = 1</Item>
</FanvilConfiguration>
Server—>Client Response:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”set”>
<RetCode>0</RetCode>
</ FanvilConfiguration >
For Set operations, only return code is replied without Info added. If there is an error in Set’s parameter, server side will reply Error and stop handling it
2.1.3 DEL
Client—>Server Request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes” cmd=”del” >
<Item> mmifilter.1 </Item>
</FanvilConfiguration>
The example shown above indicates deleting the first record of the mmifilter List. When there is no index value and the List name is ended with only “.”, it means the whole mmifilter list will be
cleared.
Server—>Client response:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”del”>
<RetCode>0</RetCode>
</ FanvilConfiguration >
2.1.4 Example of adding data via List
Reuse set command to add records to List.
Client—>Server Request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes” cmd=”set” >
<Item> mmifilter.1.StartIP = 172.16.7.1</Item>
<Item> mmifilter.1.EndIP = 172.16.7.255</Item>
<Item> mmifilter.2.StartIP = 172.16.6.1</Item>
<Item> mmifilter.2.EndIP = 172.16.6.255</Item>
</FanvilConfiguration>
Index is used to define the sequence of inserting the records. When a phone analyzes the request, if the value of Index is valid, server will insert data at the location specified by Index; otherwise, data will be inserted after List.
Server—>Client response:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”set”>
<RetCode>0</RetCode>
</ FanvilConfiguration >
2.2 Information Query
Users can reuse Configuration interface to get current information of device. Only Get operation is supported.
| Parameter | Value | Parameter Description |
| info. dev.Model | Openvox | Device Model |
| info. dev.Vendor | Brand | |
| info.dev.Mac | Mac Address | |
| Info. dev.SN | Sequence Number | |
| info.sys.MemFree | Remaining Memory | |
| info.sys.FlashFree | Remaining Flash | |
| info.sys.UpTime | Running time | |
| info.sys.FwVersion | Software version | |
| info.sys.HwVersion | Hardware version | |
| info.sip.line.$N.regist erCode |
SIP line registration status |
The format of the parameters’ names above should conincide to that of config file’s parameter name.
The format of the parameters’ names above should conincide to that of config file’s parameter name.
Client—>Server request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”get” >
<Item> info.dev.Model </Item>
<Item> info.dev.Mac </Item>
<Item> info.sys.MemFree </Item>
</FanvilConfiguration>
Server—>Client response
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”get” >
<RetCode>0</RetCode>
<info>
<Item> info. dev.Model = X6 </Item>
<Item> info. dev.Mac = 00a859c60102 </Item>
<Item> info.sys.MemFree = 1.6M </Item>
</info>
</FanvilConfiguration>
2.3 System Calls Interface Execute
Execute interface is used to call system functions to complete corresponding applications. the format is:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilPhoneExecute beep=”yes” >
<ExecuteItem>URI="Type:Param"</ExecuteItem> ……
</ FanvilPhoneExecute >
| Supported | Sub Function | Description | Remark |
| Led | |||
| Key | |||
| Cmd | reboot, reset | XML Browser newly added | |
| Dial | XML Browser newly added | ||
| Shell | Expand to support original shell command; server executes the command directly | HTTP API interface newly added |
Shell type is expanded based on current basis. System-supported shell command can be used and the system will directly execute it.
2.3.1 Shell Command Format
Client—>Server request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilPhoneExecute beep=”yes” >
<ExecuteItem>URI="Shell:Param"</ExecuteItem>
</FanvilPhoneExecute>
Server—>Client response:
<?xml version="1.0" encoding="UTF-8" ?>
< FanvilPhoneExecute >
<RetCode>0</RetCode>
<info>
<len> 100 </len>
<![CDATA[file content，file format]]>
</info>
</ FanvilPhoneExecute>
Note: When server replies shell request, it is allowed to add Info message whose content should be the result of shell command execution.
3 Detailed Parameter Description
3.1 Supported dynamic List type
| List Type | Description | Remark |
| Dial Plan | ||
| MMI Filter | ||
| Access List | ||
| In Access | ||
| Out Access |
4 Usage Instruction
4.1 Modify the configurations with HTTP API
Before changing the configurations, users can export or view NC configuration file: go to SystemConfigurationsExport configurations file, select the second option to view or export the configuration file and find the parameter you need to modify.
To get the NC configuration file of Industry products like door phones or intercoms and OpenVox entry level IP phones, please go to http://IP/ncConfig.txt page.
For example, set a SIP account.
Client—>Server Request:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration Beep=“yes” cmd=”set” >
<Item> sip.line.1.EnableReg = 1</Item>
<Item> sip.line.1.RegisterAddr = 172.16.1.3</Item>
<Item> sip.line.1.RegisterUser = 8218</Item>
<Item> sip.line.1.RegisterPswd = 8218</Item>
</FanvilConfiguration>
Server—>Client response:
<?xml version="1.0" encoding="UTF-8" ?>
<FanvilConfiguration cmd=”set”>
<RetCode>0</RetCode>
</ FanvilConfiguration >
Authentication can be controlled by configuring Enable Push XML Auth. If it is enabled, only administrator account is authorized to verify client side by using the username and password of Web server. By default, authentification is disabled.
New type of Action URL: Web API Auth Changed: enable using parameter $api_user and $api_password to report username and password. If username or password is changed, please report new username or password.