Purpose
This document space use to describe the use contain access details and method on how to use EHORS' APIs.
Purpose of EHORS' APIs by is to let customer' third party supplier to access customer EHORS system outside the customer premises.
This serve the purpose for the third party allow to retrieve limited data and sending data to EHORS system with EHORS required format from existing system.EHORS' APIs allow third party to access customer EHORS' APIs by calling particular URL by providing specific variables / parameters and gain data from Customer's EHORS system
Basic Flow
| draw.io Diagram | ||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
The flow is simple, guest from third party supplier needed to retrieve information from EHORS system, third party can just call a URL by providing several mandatory parameters/variables.
Basic Requirement
| API Service URL | https://api.ehors.com/ |
| Data Request Method | POST |
| Data Format Charset | UTF-8 (General) |
| Data Respond Format from EHORS | XML Generic |
MUST have Parameters/Variables
| Variable Name | Data Type | Sample | Explaination |
|---|---|---|---|
| accessID | String (255) | ABC123 | Unique key per customer' property, it'll link to particular site of the customer' property EHORS system, Meaning 1 property will need 1 accessID |
| accessKey | String (255) | ABC123 | Combination of accessID to allow access to the EHORS system, its like a "username" and "password" |
| moduleCode | String (255) | ModuleABC | A code from EHORS' APIs authorized module access, this can be combined with the different property have different access of modules. Read more |
| command | String (255) | G_ABC_AA | Command designed in EHORS' APIs to map function or script called in customer' EHORS system |
EHORS APIs Respond XML Format
In General EHORS API will reply / respond with XML generic format as follow:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="utf-8"?>
<SCRIPT_RESULT>
<RESULT>
... RESULTS WILL SHOWN HERE ...
</RESULT>
<SCRIPT_STATUS>SUCCESS</SCRIPT_STATUS>
</SCRIPT_RESULT>
|
| Code Block | ||||
|---|---|---|---|---|
| ||||
<?xml version="1.0" encoding="utf-8"?>
<SCRIPT_RESULT>
<SCRIPT_STATUS>FAILED</SCRIPT_STATUS>
<ERROR_MESSAGE> ~ FAILED MESSAGE HERE ~ </ERROR_MESSAGE>
</SCRIPT_RESULT> |
XML Format Explain
EHORS XML are generic format, you may also refer to following reference. We have a generic header which always start as following
| Code Block | ||
|---|---|---|
| ||
<?xml version="1.0" encoding="utf-8"?> |
Follow by default Node, and each node or sub node element can also contain 1 or more attributes.
| Node/Element/Attributes | Explain |
|---|---|
#SCRIPT_RESULT | Root XML node |
#SCRIPT_RESULT/RESULT | Result of the API call respond data retrieved by API from customer EHORS system |
#SCRIPT_RESULT/SCRIPT_STATUS | General Status of SUCCESS transactions or NON-SUCCESS transactions, refer to NON-SUCCESS reference |
#SCRIPT_RESULT/ERROR_MESSAGE | Only show when the #SCRIPT_RESULT/SCRIPT_STATUS is NON-SUCCESS, and it may contain RAW URL ENCODED format of message |
Limitations / Throttle Control
EHORS' API do have a simple limitations by NOT calling the URL from same IP address within 2 seconds. Thus third party script MUST have control of the resting period of at least 1 second before calling next command.
EHORS system are running on Linux based environment, thus variable name / parameter name are case-sensitive, please take careful note.