MQLLOCK API2 with PHP
Update from API1
This documentation is made for API2. This API2 has been released 19.Nov.2013. API which was released before this date is called API1 and this documentation does not support API1. We recommend you to upgrade to API2, we will only support API2 from now. Some of functions are behaving same but some important ones are changed. Most important change is that methods such as getClient, removeClient accepts so called UserID instead of index! Also Date outputs are different. Dates are now unixtime and all input/out values are GMT. These are very essential difference between API1 and API2.
You need a PROFESSIONAL MQLLock account in order to work with API Feature. API Feature is for vendors they want to integrate their platform with MQLLock in order to automate everything. API can be used to integrate MQLLOCK into your existing application seamlessly. Please make sure you are confident with PHP5.x and Object Oriented Programming with PHP. If you are not familiar with OOP you better outsource this project. To outsource it, you may still need to read whole documentation in order to understand main points what to outsource, why to outsource and what to take care of.
Itâ€™s important that you read this documentation systematical and do not jump randomly from topic to topic. We have tried to build a full description which covers everything. To do this we have to explain in an order.
API Calls are expensive!
API Calls are â€˜expensiveâ€™, means every function you call goes over dozens of internet routers and it takes a lot time. Its hundreds of time slower than calling local functions. Itâ€™s important that you know this fact while coding. Your coding style may decide about our and your resources. Its not only our resources used by using API. Itâ€™s also your resources because we integrate your system and our system using API. If you donâ€™t use API Calls wisely, your clients will see how slow things run. Please make sure you understand all facts and make optimized API calls in order to save resources for both of parties.
In case you want to outsource the API integration, you will need to explain your coder how MQLLock mechanism works. We advise you to create a screencast how https://mqllock.com/login/ panel works and let them understand how you manage your users. Almost 99% of all PHP Coders will be able to manage this integration if they read this documentation but they may not understand the concept of MQLLock because most of coders are non-traders and not familiar with mt4 at all. So the only thing you have to do is to make sure they understand the mqllock.com/login and read this documentation.
While searching a coder please use a text like this:
Searching a PHP5 coder who is familiar with basic OOP. I do have an API with full documentation to be implemented to my existing system. The API is fully described and there are demonstration files how to implement. I will introduce you how it the system should work at the end.
As you see itâ€™s very easy to outsource MQLLock API because we give very detailed description. It should be enough to give them the URL from this documentation along with api2.php which you will download from Downloads area and apidemo.php. At the end we recommend to look over delivered code to make sure a) error handling inside code has been done properly (see our notes below) b) API calls are done optimized way (see previous subject).
Understanding API Settings
Itâ€™s essential that you understand the API Settings. Very detailed explanation can be obtained from https://mqllock.com/ml/vendor/?p=api please read this page very carefully. We also recommend to read https://mqllock.com/support/api-access/ before you get started.
To install the MQLLock API you will need to download ‘api2.php’ from https://mqllock.com/ml/vendor/?p=api. Save api2.php inside your project folder. Please make sure you keep updating API versions. We update API and improve with new features from time to time. You can track API changes here: https://mqllock.com/ml/files/api_changes.log.
Getting started is easy as adding one include statement as seen here:
Authentication in Detail
API has access to all your client base! API can delete, modify, add new clients or settings. Thatâ€™s why authentication from API is very serious thing to understand. We do offer two levels of authentication. First is IP Level authentication. This has been explained in detailed here. You may provide us up to 3 IP addresses which may access our API SERVER. This is for those people they have static webserver address (most of hosting companies do have static ips, you must ask your hosting-support to give you the IP Address from hosting). You can input up to 3 IP addresses and we will allow API Access only from those IPS. Changes are effective immediately, no need to wait.
Second level is the Password based authentication. By Default API Auth is same as Admin Auth. Some of our vendors may not want to use same Auth due to security reasons. They may not want that Admin Auth is known by their coders. If you need to outsource the API integration you may use API Auth generate button like seen here:
Click to Generate and click to Update button and you will have an screen like:
You can give this new API Auth to outsourcing coder or use it yourself to isolate your Admin access. API Auth does not have access to login panel not to your source code. This API Auth is exclusively for API Calls. Always use this recommended method to keep your source code secure.
Only parameter needed by mlApi class is AUTH Code:
Created new object $api from mlApi class.
Understanding Error Codes is essential
API calls throw different error codes per operation. Almost every operation sets an Error code if responded value is FALSE. Error codes and their meaning can be found inside api2.php file, they may vary or be extended by newer API Versions. Make sure you study api2.php before upgrading. Api2.php contains all possible codes. Here is latest list from API version 0.9:
For example: In case you have wrong AUTH you get error code -1. If you get a server error code, make sure you double check your server settings inside https://mqllock.com/login/. Server settings can only changed by admin. If you are coder, contact admin to make sure all settings are correct. Almost every function call (methods) returns a value or â€˜FALSEâ€™. If returned â€˜FALSEâ€™ you have to check for error with $api->getError(); getError() returns last error happened as integer. Error management is essential in order to have proper working backend. Make sure you check error from every API call if it returned â€˜falseâ€™. Some functions does not return an error code, in this case returned value is â€˜FALSEâ€™ but $api->getError() returns -50. Initializing API with new mlApi($auth) does not hit the server. Error codes are thrown after first method used.
Date Format of API2
In API2 all date formats are in unixtime format and they will be accepted as GMT. Our clients are all over the world. The dates you pass or get from our functions indicate the time in GMT Format.
Read Account/Project Details programmatically
getProjectId() is an essential ID to identify your project revision uniquely. This Id will be changed by every new reprocess. This ID is normally revision id. Everytime you submit new project you will get new ProjectId assigned. Only getShartId() is constant per account.
getProjectName() returns human-readable-name for your project. This Name may change from time to time.
getSharpId() returns an ID which indicates your account uniquely. You can use this value to identify the account.
To understand getSharpId(),getProjectName(),getProjectId() review this screenshoot from vendor panel:
Lets make an example for all functions:
MQLLock supports different licensing methods. You can view them here.Itâ€™s possible to retrieve the license type programmatically. Here is the demonstration:
As you see its straight-forward OOP enum method to find out which license type this account is set. mlApi::getTypeText() is a static method to return enum as string as its only there to help you. We recommend to compare $projectType by enum constants like demonstrated to determine current license type.
Setting License Type: its possible to set License Type programmatically but this is not a recommended function. Use $api->setLicenseType($NewType) function to set current license type to new one. Please use this function only if you know what you are doing.
Reading Project URL
Detailed information about Project URL can be read from here. To retrieve current Project URL you can use:
Variable $projectUrl contains current setting of ProjectUrl or ProductUrl, they are both synonyms. This function may return an empty string. By default ProductURL is empty. If ProductURL is empty then we donâ€™t display any mqllock lock symbol on chart corner. This url can be set only manually from https://mqllock.com/login/ and requires admin access. For more information about Product Url: https://mqllock.com/support/product-url/
Reading Subscription Type and Subscription Expiration Date
Every Account has a subscription type and subscription expiration date because MQLLock is operating month-to-month subscription based. Some of our old clients may have lifetime accounts and they return -1 to indicate lifetime account.
Currently we do have 3 different Subscription Types:
0 – TRIAL
1 – PREMIUM
0 – PROFESSIONAL
Here is the snippet to query API server for these information:
Hint: You may build your own crontab to check Subscription Expiration Date and mail you before it expires. getSubscriptionExpDate() returns the expiration date of your membership/account in unixtime format. We do have clients their account never expires, they will return -1. Generally -1 indicates lifetime account but everything else is valid. getSubscriptionType() returns an integer between 0..2, 0 means your account is Trial, 2 means your account is Professional.
Licensing type facts you need to know
Please read and understand licensing types here https://mqllock.com/support/licence-types/ . We do support different license types. Programmatically enumeration is:
|mlApi::LICENSE_OPEN||Open Licensing (default)|
|mlApi::LICENSE_ACCOUNT||Account Number Licensing|
|mlApi::LICENSE_RECEIPT||Receipt Number Licensing|
|mlApi::LICENSE_LOGIN||Login & Password Licensing|
Every License Type has its own clients because different types require different client property information to be inserted. For example Receipt licensing requires a receipt code but Login & Password Licensing requires login & password properties. Technically we do not delete users if you switch between licensing types. You can use 1 month Account Number Licensing and switch to Receipt later and back. Of course if you switch, your client base is not copied from one type to another because every type has own client base.
We recommend you as Admin to define a particular license type to avoid double work inserting all your clients. Theoretically itâ€™s possible to copy all your clients between different licensing types. LICENSE_OPEN does not maintain any client information because OPEN licensing does not authenticate at all, your Project is free for everyone.
Reading number of Clients
We can start reading number of clients per licensing type. Number of clients may vary per license type, thatâ€™s why calling getClientsCount($Type) return different numbers based on $Type. Lets make an example:
LICENSE_OPEN will always return 0 because open license type does not have any clients. Itâ€™s open for everyone.
Determine available updates
We do regularly release new updates for your project. Those updates are not only API Updates. They are updates for MQLLock itself. Releasing a new update for MQLLock does not mean you have to update your project. The decision to update your project can be made by project admin. But you still need a programmatically way to detect new updates. This snippet demonstrates everything you need to know:
If the returned value is not â€˜falseâ€™ then itâ€™s a 1 or 0. Where 1 indicates new update is available.
Understand UserID property
Since API2 we have added new property per User. This property is called UserID and identified as â€˜idâ€™ by returning array. Itâ€™s an INDEX for every single user unique Project-Wide per License. This ID is auto incremented automatically whenever a new User will be inserted to system manually or from API2.
First user you insert to system gets the ID 1, if you delete this user and add new one, second user ever added will get the ID 2. This Unique Index system has been introduced by API2. With UserID you can be sure that a particular user has a fixed id. Starting from API2 you can sync your local clients with ours. Starting from API2 functions such as getClient,updateClient, removeClient requires the UserID as one of the parameters to identify user. In API1 these functions were responding over Index and not over ID. You may have two users with same UserID among other license types! UserID is unique per Account and License Type. LICENCE_ACCOUNT may have UserID 5 and also LICENCE_RECEIPT may have a UserID 5. This is important to understand.
Understand â€œtagâ€ property
We have inserted new user property â€œtagâ€ with API2 concept. This field can be used to store information from your script. Fields like comment are read and writeable from web, but tag can be only used from API2 scripts. You may use tag to store unique information about that particular user, to group users or even to store information about user. The format of tag is free definable if you store JSON (or similar) open formats, since we internally process it as string. Maximum limit of tag is 512 bytes and you are not allowed to use some escaping characters.
Retrieving All Clients
Function findClients($type) retrieves all clients as ordered array.In example above we retrieve all Clients from type mlApi:LICENSE_ACCOUNT. Every License type has different User Base:
Every User is an associative array with following properties:
|account_no||Contains Account Number. LICENCE_ACCOUNT licensing only.|
|real_demo||2 = Demo Only Account, 1 = Real Only Account, 0 = Demo or Real Accounts allowed. LICENCE_ACCOUNT licensing only.|
|id||UserID. Explained above.|
|expiration||Unixtime gmt format of expiration. -1 indicates no-expiration-date, lifetime account.|
|comment||Comments about user.|
|cid||CID (ComputerID) for CID Licensed clients.|
|login||Login for Login & Password licensed clients.|
|pass||Password for Login & Password licensed clients.|
|receipt||Receipt for Receipt licensed clients.|
|tag||Free definable tag per client.|
|client_email||email from licensed client|
|send_activation_email||indicates if system should send email to client when licence has been activated (does not work with API)|
Retrieving Client(s) selectively
We do have following methods to retrieve client information:
findClients($type,array $data) is used to far more than fetching all available clients. This method can also fetch clients with filtered properties like seen on following examples. Generally getClient is used to fetch one specific user with known UserID and findClients is used to get multiple clients with similar properties. Example:
getClient($type,$UserID) method can retrieve a client by using UserID property. Please read the description of UserID to make sure you know what you are doing. Best way to learn is making examples:
findClient($type,$uniqueData) method is used to select 1 particular user with its unique and mandatory user property. Unique property depends on license type, here is a good example for every license type:
Method removeClient($type,$UserID) is the function which can remove any User by their UserID. This operation is not reversible. Please handle with care. Here is simple example how to use this method:
Adding New Client
To add a new Client you can use addClient($type,$data) method. Based on $type different user properties are required to be passed minimum with $data which is an associative array.
Error checking is ESSENTIAL especially by this function. Under normal circumstances this function should return a valid >=0 which is new UserID we have added. Please always check like seen in this example for error:
At first attempt we get return value >0 but on second try we get -54 because a user with same â€œaccount_noâ€ already exists in system! All properties are case-sensitive inside $NewClient associative array. Here is an overview about user properties and their usage based on license type:
If you donâ€™t insert â€œloginâ€ and â€œpassâ€ with LICENSE_LOGIN you will get -2 error.
To get started here are more examples:
If you want to insert a user with expiration date, you must simply add â€œexpirationâ€ key with unixtime GMT format expiration. If you want to add a new user without expiration then you dont need to insert ‘expiration’ property. By updating you can put -1 value to expiration to make sure, this user does not have any expiration.
Of course itâ€™s one of the most important operations, to update clients. $api->updateClient($type,$UserId,$data) is the method to update clients:
updateClient returns either TRUE or FALSE depending on Result. TRUE if operation was successful otherwise something went wrong.
Please contact us for API2 support. Please always mention a) your account details b) your name c) include your demonstration code d) screenshoots of bugs to demonstrate. We cannot accept big project files to study. You have to understand your project, thats why its waste of time to study your project in order to solve bugs. Please always send us isolated source codes to demonstrate your problem. Please be verbose and only english, german or turkish language. Support email: firstname.lastname@example.org