HOQU platform API in action
image by The Digital Trends
HOQU is designed as an agile and flexible platform. For our team, it means any affiliate program could fit well to the platform environment. Also, the platform meets any of the affiliate program’s requirements. Moreover, any applications working in the platform environment could easily communicate with each other, as well as with the blockchain. To get this done, our development team designed and developed an Ethereum Geth API to provide a convenient RESTful interface. To see how the platform will work in a real environment, let’s have a closer look at a simple example affiliate program — HOQU Sale. A merchant (HOQU.io) wants to buy Ether from clients and pays in HQX (as the main HOQU platform currency). An affiliate (HOQU Sale) wants to promote a merchant’s offer (selling HQX) and provides a website (Investor’s Hub) with many marketing tools (ads of a sale in social media). Each action of buying (CPA lead) should be paid to the affiliate’s account address (sale of smart-contracts) from the platform’s bank address (HQX pool created during initial token creation). Later, an affiliate will distribute all purchased HQX during the claiming stage. Merchants have several trackers to track and add incoming leads (actions of buying). To track buying HQX by ETH, the tracker’s software listens for Ethereum events using REST API and adds appropriate leads to the blockchain using the REST API as well. To track buying HQX by BTC and LTC, the tracker’s software generates appropriate BTC or LTC addresses for client and adds leads to the blockchain, whenever the balance of a generated address is updated. Let’s assume a platform’s smart contract already has following data:
- merchant’s user has id 3212;
- affiliate’s user has id 6389;
- sale offer has id 652 and belongs to merchant’s company with id 231;
- ETH and BTC/LTC trackers have ids 34 and 47 respectively;
In that case, to add a lead of buying HQX by ETH, the tracker’s software can send the following request to the REST API:
POST https://geth-api.hoqu.io/platform/lead/addContent-Type: application/json
X-Sign: very-secret-hash{
"id":523424,
"ownerId":6389,
"trackerId":34,
"offerId":652,
"beneficiaryAddress":"0x778ae314498791f8c0211618181093f8e74e9908",
"meta":"{\"type\":\"CPA\", \"source\":\"ETH\", \"volume\":32.00, \"amount\":210000.00}",
"dataUrl":"https://account.hoqu.io/tx/f57655d7f76e557a7bb6",
"price":"210000000000000000000000"
}In response, the API will provide the ID of a transaction created in the blockchain:
{
"data": {
"tx": "0x7a48d9a9873f255881728a1a0c109e7ee50b11eda3133f78c6640aeff9d903a5"
},
"error": {
"code": "NO_ERROR",
"message": null
}
}As a sale’s offer has no approval stage, we can execute the process of paying for an added lead by sending the request:
POST https://geth-api.hoqu.io/platform/lead/sellContent-Type: application/json
X-Sign: very-secret-hash{
"id":523424
}In response, the platform’s smart-contract will withdraw 210000 HQX from the merchant’s address and distribute it among all intermediaries of the lead (in our case it was the affiliate and client’s referrer).The tracker and other platform’s software can get a lead’s data via a simple request to the API:
GET https://geth-api.hoqu.io/platform/lead/523424{
"data": {
"Lead": {
"createdAt": "1512140236",
"ownerId": 6389,
"trackerId": 34,
"offerId": 652,
"beneficiaryAddress": "0x778Ae314498791F8c0211618181093f8E74e9908",
"meta": {
"type": "CPA",
"source": "ETH",
"volume": 32.00,
"amount": 210000.00
},
"dataUrl": "https://account.hoqu.io/tx/f57655d7f76e557a7bb6",
"price": "210000000000000000000000",
"intermediaries": {
0x2aD0a91C6e8199Aa4B264e417521eA6bb1636f53: 0.05
},
"status": 1
}
},
"error": {
"code": "NO_ERROR",
"message": null
}
}The detailed offer data is available upon request:
GET https://geth-api.hoqu.io/platform/offer/652{
"data": {
"Offer": {
"createdAt": "1512139726",
"companyId": 231,
"payerAddress": "0x8Ab533C50cFcE7D25Dd3cC311B0e40080Bf71bef",
"name": "HOQU Sale stage 1",
"dataUrl": "https://tokensale.hoqu.io",
"cost": "6000",
"status": 1
}
},
"error": {
"code": "NO_ERROR",
"message": null
}
}And, for example, the detailed data of a merchant can be fetched by request:
GET https://geth-api.hoqu.io/platform/user/3212{
"data": {
"user": {
"createdAt": "1512138181",
"addresses": {
0: "0x8Ab533C50cFcE7D25Dd3cC311B0e40080Bf71bef"
},
"role": "merchant",
"kycLevel": 4,
"kycReports": {
0: {
"createdAt": "1512138691",
"reportId": 23745,
"kycLevel": 2,
"dataUrl": "https://kyc.hoqu.io/report/2384f897e998a98798b796"
},
1: {
"createdAt": "1512138721",
"reportId": 42364,
"kycLevel": 4,
"dataUrl": "https://kyc.hoqu.io/report/423647e998a98798b796"
}
},
"pubKey": "MCQBGoiuSoSjafUhV7i1cEGpb88h5NBYZzWXGZ37sJ5QsW+sJyoNde3xH8vdXhzU7eT82D6X/scw9RZz+/6rCJ4p0=",
"status": 1
}
},
"error": {
"code": "NO_ERROR",
"message": null
}
}The platform is not limited to such simple cases, but it is a good example that shows the platform is ready to handle all affiliate programs in a flexible and reliable way. Of course, the questions of security and access of trackers to the API stays outside the scope of this article, but you can be sure that security is one of our top priorities. The source code of the API can be found on GitHub. The example deployed contract handled by the API with all related data can be found on the Rinkeby network.