Skip to main content

Create App and Connect API

Version 1.0.0

TABLE OF CONTENTS

LOGIN AND INSTALL APPLICATION WORKFLOWS

1. Step 1: Create app

  • After sign in/sign up successful, the system will show a list of your applications, click "Create App" button to create a new application.

  • Screen for create application.

  • Name: application name.
  • Description: application description.
  • Redirect Url: application domain, the system will redirect to this url when starting application.
    • You need to declare at least 2 URLs: login and install
      • Login url with recommended syntax: https://{domain_app}/install/login
      • install url with recommended syntax: https://{domain_app}/install/grandservice
    • You need to configure these URLs in your app's configuration file

Create success.

  • Some field need to save in configuration file to use: App Id, App Secret, Redirect Url.

2. Step 2: Select scope for the application

  • Select scope to request permission to edit or read data.

  • The scope is divided into two categories

  • Note:

    • When choosing a scope, you must save that scope to the application's configuration file to use when installing the application.
    • When using write permission must include read permission.
    • When only using read permission, there is no need to write permission.
    • Ex :
      • com.write_products com.read_products (Use both write and read products for the application)
      • com.read_products (Only use read products for the application)
  • Reference: APIs & References

2.1 Haraweb scopes

  • For the API use at the sales page.

  • The way to declare haraweb scope: web.{scope_name}.

    Ex: web.read_script_tags.

2.2 Commerce scopes

  • For the API use at the admin page.

  • The way to declare commerce scope: com.{scope_name}.

    Ex: com.write_products.

3. Step 3: Connect webhook

3.1 Use ngrok to test register webhook

  • Ngrok (https://ngrok.com/) creates a secure tunnel on your local machine along with a public URL you can use for browsing your local site.

  • If you’re running your local web server on port 3000, in terminal, you’d type in: ngrok http 3000.

  • Note:

    • A url can be available for 8 hours
    • Only use https://
    • Use ngrok's web inspection interface to understand the HTTP request and response traffic over your tunnel: http://localhost:4040
    • Similar tool: https://requestcatcher.com/

3.2 Register webhook:

  • Go to Webhooks, select Register button to register webhooks

  • You need to fill in some information

    • Callback URL: Webhooks will POST a message with data to this URL when certain things happen. Make sure the URL is configured on your application to receive webhooks.
    • Verify Token: is random string and has at least 1 character, because it’s used for authenticating with the application, make sure this token matches the string configured on your application.

  • After registered, you need to reload this page to see the list of events that can subscribe to get notifications.

3.3 Topics need to subscribe:

3.3.1 Topic shop/update:

  • Subscribe this topic will help the app to receive notifications when shops have something updated.

  • Webhook will send a request to the URL you used to register with the POST method.

  • The request will include an object containing the latest shop information after updating such as using the ngrok example below.

  • Some important information of the shop.
PropertyDescription
domainDomain of the sales page
myharavan_domainDomain of the admin page
emailEmail
customer_emailCustomer support email
shop_ownerName of shop owner

3.3.2 Topic app/uninstalled:

  • Subscribe this topic will help the app to receive notifications when your application is uninstalled.

  • Webhook will send a request to the URL you used to register with the POST method.

  • The request will include an object containing information of the shop that uninstalled the application such as using the ngrok example below.

PropertyDescription
org_idorgid of the shop uninstall app
app_idApp ID was obtained after creating the application in step 1
client_idClient ID was obtained after creating the application in step 1
event_typesame as topic in Headers
user_idid of the user who uninstalled the app
is_salechannelShow in sales channel menu
true : show
false: not show
is_martketingShow in marketing menu
true : show
false: not show

4. Step 4: Configuration for the application

  • After basic configuration on https://developers.haravan.com/apps

  • You will get information like: App id, App secret, scope, webhook…

  • Save that information into your application.

  • Ex: Save to an object named config.

PropertyDescription
response_modeForm method responses
url_authorizeLogin url of Haravan system
url_connect_tokenUrl get the token for the application
grant_typeType of code level. Always “authorization_code”
noncestring random at least 1 character
response_typeSelect the fields you want to receive
app_idApp ID was obtained after creating the application in step 1
app_secretApp Secret was obtained after creating the application in step 1
scope_loginRequired scopes when logging into the haravan system
They are: openid, profile, email, org, userinfo
scope- Scopes include the required and the optional used to install the application
+ The required: openid, profile, email, org, userinfo, grant_service
+ Scope using webhook : wh_api (the optional)
+ Other scopes must correspond to the scopes selected in step 2
Note :
+ When using write permission must include read permission.
+ When only using read permission, there is no need to write permission.
+ Ex :
com.write_products com.read_products (Use both write and read products for the application)
com.read_products (Only use read products for the application)
login_callback_urldeclared at step 1 in Url redirect, used to login to the haravan system
install_callback_urldeclared at step 1 in Url redirect, used to install the application
webhook
hrVerifyTokenAuthentication code webhook, declared at step 3 Can get a random string at https://randomkeygen.com/ (CodeIgniter Encryption Keys)
subscribeurl post subscribe webhook
const config = {
response_mode: 'form_post',
url_authorize: 'https://accounts.haravan.com/connect/authorize',
url_connect_token: 'https://accounts.haravan.com/connect/token',
grant_type: 'authorization_code',
nonce: 'asdfasdgd',
response_type: 'code id_token',
app_id: '0e86d3653f580f07358865a0b6cda6de',
app_secret: '24302376155dd82a92f4d9d0b1d573c5a232d30ab5fe4a79069e4435bad7e200',
scope_login: 'openid profile email org userinfo',
scope: 'openid profile email org userinfo com.write_products com.read_products web.read_script_tags grant_service',
login_callback_url: 'http://localhost:3000/install/login',
install_callback_url: 'http://localhost:3000/install/grandservice',
webhook: {
hrVerifyToken: 'bOL3XFfZabhKe6dnJfCJuTAfi37dFchQ',
subscribe: 'https://webhook.haravan.com/api/subscribe'
},
};

5. Step 5: Login to get authorization code

  • First, login to Haravan's system to check shop and user information

  • When using login_callback_url:

    • If have orgid in request params of login_callback_url, add orgid to request params of url_authorize and redirect to it with the GET method to login.
    • If don’t have orgid in request params of login_callback_url, redirect to url_authorize with the GET method to login.
  • After redirecting to url_authorize if not already logged in to Haravan, the system will require login to get user information, if logged in, the system will skip the login step and get the used login information.

  • After successful login, the system will redirect to the redirect_uri link that you have added to the request parameter of url_authorize the POST method, along with the code and id_token .

5.1 Request get code

MethodURL
GEThttps://accounts.haravan.com/connect/authorize
Request params:
response_mode
response_type
scope_login
client_id (app_id)
redirect_uri (login_callback_url)
nonce
// All are saved in the configuration file
orgid
Parameter passing syntax:
https://accounts.haravan.com/connect/authorize?response_mode={response_mode}&response_type={response_type}&scope={scope_login}&client_id={app_id}&redirect_uri={login_callback_url}&nonce={nonce}&orgid={orgid}
Ex:
https://accounts.haravan.com/connect/authorize?response_mode=form_post&response_type=code id_token&scope=openid profile email org userinfo&client_id=0e86d3653f580f07358865a0b6cda6de&redirect_uri=http://locahost:3000/install/login&nonce=asdfasdgd&orgid=1000198788
PropertyRequiredDescription
response_modetrueForm method responses
response_typetrueSelect the fields you want to receive
scopetruescope_login in configuration file
client_idtrueApp ID was obtained after creating the application in step 1
redirect_uritruelogin_callback_url in configuration file
noncetruestring random at least 1 character
orgidmay be passed to the request param of login_callback_url or not

5.2 Response get code

Status Response
200
{ 
"code": "c309cc6a97e7da821975d2440645892a95f13ce8e06af81ecffe5ed9db8fe7a3",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NzA3Njk4MjAsImV4cCI6MTU3MDc3MDEyMCwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOGJkOWExNDc1NTI4NTJlNTFlYTU3MTExMDQ3NGZlNjMiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU3MDc2OTgyMCwiY19oYXNoIjoiRm9XSFRLUU50SWFRVndFSlg5bVBMQSIsInNpZCI6Ijc5NDgyZGExZGE5ZmZlZjJmMjY2NjVjOWE2Yjc4MmIzIiwic3ViIjoiMjAwMDAwMDIwMzMyIiwiYXV0aF90aW1lIjoxNTcwNjgwMDU2LCJpZHAiOiJsb2NhbCIsInJvbGUiOiJhZG1pbiIsIm9yZ2lkIjoiMTAwMDExMzc2MyIsIm1pZGRsZV9uYW1lIjoidGVzdCIsIm5hbWUiOiJ0ZXN0IiwiZW1haWwiOiI4YmQ5YTE0NzU1Mjg1MmU1MWVhNTcxMTEwNDc0ZmU2MyIsIm9yZ25hbWUiOiJob2FpbmFtMDlfMTExIiwib3JnY2F0IjoiT3RoZXIiLCJhbXIiOlsicHdkIl19.Q8I9ezKY6r22exDkqBjXbHHirFFg7HRc33DFRHP0ID6E1XyPsry2zgsyVpP4EVtOs0jl0fEzaLvpKLabFDlqNAwMnnRbPqECazMJ5OTDKGTJsEO9Xj-v-TwqMDWPEwV_Abemj8_deovPCw_3wAxxB3mta1GLqz12iBD7m9jlIWFEzqEvIULhdrQ_isMQwjBaxA2r8oQHqQlxVuUAOPKOgP-mCCUa8kGGAFPtd3dfl4C7EezgNE2xtdjv1ItE4_SCdvaF6-hTMrE5smildtgRp3gGv2_QmgGnU1IV8rPGcT3OyaOtywaaQDBSyGcCkF6OXT30-Ez1guJvllVYJ9AIqg",
"scope":"openid profile email org userinfo",
"session_state": "cE63E1b725ke5g329GmRQLnEydXpuQanSCG_DF8AbKM.15223afbde03d10d258e85b1be797e41"
}
401 Unauthorized
422
{
"error": "Unprocessable Entity"
}
500 Something went wrong. Please try again later.

6. Step 6: Verify information

  • After login successfully, the application will receive the code and id_token.

  • Use jsonwebtoken library: https://www.npmjs.com/package/jsonwebtoken to decode id_token get user, role and orgid information.

  • Check before installing the application :

    • First, use the user information to query the shop in the database.

    • If shop has installed the application, grant access_token stored in the database to the user who is currently logged in using the application.

    • If shop hasn’t installed the application, You need to verify the role of the user:

      Case 1: If the user is logged in as an admin, install the application.

      Case 2: If the user is logged in not an admin, then show the message is not authorized.

7. Step 7: Install to get authorization code

  • After verifying the information, we begin to install the application.

  • Call to install_callback_url, add the orgid you obtained when decode id_token from step 6 to request params of url_authorize and redirect to it with the GET method.

  • Adding orgid is to avoid errors when a user logs in to multiple accounts and you will be selected account when log in step 5 so don’t need to select again.

  • When user agrees to the installation, the system will redirect to the redirect_uri link that you have added to the request parameter of url_authorize the POST method, along with the code and id_token.

  • Use the code received to get access_token for the application.

  • Then, using the jwt library to decode the received id_token, you will have sid of the account used to install the application.

  • Save sid along with session to database and use that data to handle when logout.

  • Note: Login and install both redirect to url_authorize but will use different redirect_uri and scope.

7.1 Request get code

MethodURL
GEThttps://accounts.haravan.com/connect/authorize
Request params:
response_mode
response_type
scope
client_id (app_id)
redirect_uri (install_callback_url)
nonce
// All are saved in the configuration file
orgid
Parameter passing syntax:
https://accounts.haravan.com/connect/authorize?response_mode={response_mode}&response_type={response_type}&scope={scope}&client_id={app_id}&redirect_uri={install_callback_url}&nonce={nonce}&orgid={orgid}
Ex:
https://accounts.haravan.com/connect/authorize?response_mode=form_post&response_type=code id_token&scope=openid profile email org userinfo com.write_products com.read_products web.read_script_tags grant_service&client_id=0e86d3653f580f07358865a0b6cda6de&redirect_uri=http://locahost:3000/install/login&nonce=asdfasdgd&orgid=1000198788
PropertyRequiredDescription
response_modetrueForm method responses
response_typetrueSelect the fields you want to receive
scopetruescope in configuration file
client_idtrueApp ID was obtained after creating the application in step 1
redirect_uritrueinstall_callback_url in configuration file
noncetruestring random at least 1 character
orgidtrueobtained when decode id_token from step 6

7.2 Response get code

Status Response
200
{ 
"code": "c309cc6a97e7da821975ecffe5ed9db8fe7a3d2440645892a95f13ce8e06af81",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NzA3Njk4MjAsImV4cCI6MTU3MDc3MDEyMCwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOGJkOWExNDc1NTI4NTJlNTFlYTU3MTExMDQ3NGZlNjMiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU3MDc2OTgyMCwiY19oYXNoIjoiRm9XSFRLUU50SWFRVndFSlg5bVBMQSIsInNpZCI6Ijc5NDgyZGExZGE5ZmZlZjJmMjY2NjVjOWE2Yjc4MmIzIiwic3ViIjoiMjAwMDAwMDIwMzMyIiwiYXV0aF90aW1lIjoxNTcwNjgwMDU2LCJpZHAiOiJsb2NhbCIsInJvbGUiOiJhZG1pbiIsIm9yZ2lkIjoiMTAwMDExMzc2MyIsIm1pZGRsZV9uYW1lIjoidGVzdCIsIm5hbWUiOiJ0ZXN0IiwiZW1haWwiOiI4YmQ5YTE0NzU1Mjg1MmU1MWVhNTcxMTEwNDc0ZmU2MyIsIm9yZ25hbWUiOiJob2FpbmFtMDlfMTExIiwib3JnY2F0IjoiT3RoZXIiLCJhbXIiOlsicHdkIl19.Q8I9ezKY6r22exDkqBjXbHHirFFg7HRc33DFRHP0ID6E1XyPsry2zgsyVpP4EVtOs0jl0fEzaLvpKLabFDlqNAwMnnRbPqECazMJ5OTDKGTJsEO9Xj-v-TwqMDWPEwV_Abemj8_deovPCw_3wAxxB3mta1GLqz12iBD7m9jlIWFEzqEvIULhdrQ_isMQwjBaxA2r8oQHqQlxVuUAOPKOgP-mCCUa8kGGAFPtd3dfl4C7EezgNE2xtdjv1ItE4_SCdvaF6-hTMrE5smildtgRp3gGv2_QmgGnU1IV8rPGcT3OyaOtywaaQDBSyGcCkF6OXT30-Ez1guJvllVYJ9AIqg",
"scope":"'openid profile email org userinfo com.write_products com.read_products web.read_script_tags grant_service",
"session_state": "cE63E1b725ke5g329GmRQLnEydXpuQanSCG_DF8AbKM.15223afbde03d10d258e85b1be797e41"
}
401 Unauthorized
422
{
"error": "Unprocessable Entity"
}
500 Something went wrong. Please try again later.

7.3 Decode id_token get sid

8. Step 8: Lấy Access_token

  • Use the oauth library https://www.npmjs.com/package/oauth to get access_token.

  • After installing the application successfully, you will receive a token, save the token for long term use.

8.1 Demo code to get access_token:

  • NodeJS
var OAuth2 = require('oauth').OAuth2;

let grant_type = 'authorization_code';
let callback_url = 'http://localhost:3000/install/grandservice';
let client_id = '9f83ffc930129e2f4d11af0fc60bd251';
let client_secret = '618e198b891317f02c545e9fe078f8a72e8f57424ee471ac409a8c0d05bfe8f4';
let url_authorize = 'https://accounts.haravan.com/connect/authorize';
let url_connect_token = 'https://accounts.haravan.com/connect/token';
let code = '6a83f22d3363d270b7c18042e6c2db6571df0b8236b708f5d08778d303a85884';

let params = {};
params.grant_type = grant_type;
params.redirect_uri = callback_url;

let _oauth2 = new OAuth2(client_id,client_secret,'',url_authorize,url_connect_token, ''
);
_oauth2.getOAuthAccessToken(code, params, (err, accessToken, refreshToken, params) => {
if (err) {let parseErrData = JSON.parse(err.data);
console.log('error', parseErrData);
} else {
console.log('accessToken', accessToken);
}});
  • Postman

PropertyRequiredDescription
OAuth2trueDeclare OAuth library of nodejs
grant_typetruegrant_type in configuration file
callback_urltrueinstall_callback_url in configuration file
client_idtrueapp_id in configuration file
client_secrettrueapp_id in configuration file
codetrueCode received in step 7

8.2 Response get Access_token

Status Response
200
{
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImUyZTFkZDM4ODJkNTE4YTk2OGQ5MWVlYTU3NmQxNzdhIiwidHlwIjoiSldUIn0.eyJuYmYiOjE1NTk4MDUyNTUsImV4cCI6MTU1OTgwNTU1NSwiaXNzIjoiaHR0cHM6Ly9hY2NvdW50cy5oYXJhLnZuIiwiYXVkIjoiOWY4M2ZmYzkzMDEyOWUyZjRkMTFhZjBmYzYwYmQyNTEiLCJub25jZSI6ImtjanFoZGx0ZCIsImlhdCI6MTU1OTgwNTI1NSwiYXRfaGFzaCI6InlVcHBoaE15bnZUSUpWV0tzSkMtS3ciLCJzaWQiOiJhMzhkN2M5YWM0ODZiZjBhOTM2OWI4ZjRiZjk2NDcxZCIsInN1YiI6IjEwMDAxMTQ5OTAiLCJhdXRoX3RpbWUiOjE1NTk4MDUwODAsImlkcCI6ImxvY2FsIiwicm9sZSI6WyJjb21fYXBpLmFkbWluIiwiYWRtaW4iXSwib3JnaWQiOiIxMDAwMTEzNzYzIiwibWlkZGxlX25hbWUiOiJCw7lpIMSQaW5oIEhvw6BpIE5hbSIsIm5hbWUiOiJCw7lpIMSQaW5oIEhvw6BpIE5hbSIsImVtYWlsIjoiYnVpZGluaGhvYWluYW1AZ21haWwuY29tIiwib3JnbmFtZSI6ImhvYWluYW0wOSIsIm9yZ2NhdCI6Ik90aGVyIiwiYW1yIjpbInB3ZCJdfQ.P7xXf0ftuiADd5I8v7uQfJk6Xm839z4RFt_Q9RfpMg_MsqIFgnmpJ4lgB2Zcsjw_SwSasEpszXQ2Dwy8-kt0C5YYvAjKPdTk8DNNZidav9FqtM-53rR-DMbyyoDes8-pWed2J_cTFHEhlayf1jYowAsUo6n3snJAwlHdpnRaHVGyFOi56N6Y8eSA84GNrKRPlBpjfhKY8Pk0pmY_0XOfO7aInPt0RPK42sf0gRVWJR2hSksJaOBL5P6pSDq5A_uT2o-YsE8nZ0OASKzE4aQ0Qeqo-Rx9LaJIzwuJKnyVmFSgl2gJHJUVgTZ0slD5fMmtRuZOSFlDibp8J6wtTnb_MQ",
"access_token": "86f6ab839b301903cc6223dbe236aaa874fa5aa882b8d3d121ba91f8ce660f35",
"expires_in": 86400,
"token_type": "Bearer"
}
401 Unauthorized
422
{
"error": "Unprocessable Entity"
}
500 Something went wrong. Please try again later.

8.3 Use access_token:

  • After retrieving access_token, you can use that token to query data from the api

  • Ex: use access_token to get the shop information by postman.

      Headers : Content-Type : application/json    
    Authorization : Bearer + access_token

9. Step 9: Use the application after installation

  • Once installed, the application will appear above the application list.

  • When the user starts the application, you need to run step 5 again to get that user's id_token.

  • Using the jwt library to decode id_token, you get sid and some other user information like the example below.

  • You can verify the user based on these information if the application need it.

  • Save sid along with session to database and use that data to handle when logout.

  • Finally, show the view app.

10. Step 10: Handle when the user logout

  • When the user logout of the system, it may be from the seller or https://accounts.haravan.com/, the system will send a request to your application.

  • The request will be sent to the URL in Front Channel Logout URL with the GET method.

  • This URL is obtained when you create the app successfully at https://developers.haravan.com.

  • This request will include the sid of the logged out account in the query.

  • Once you have sid of the logout account, use it to query the corresponding session in database and delete that session.

  • This helps the application to check which user has been logged in and logged out via the session and sid.