Create App and Connect API

Docs version 2

LOGIN AND INSTALL APPLICATION WORKFLOWS

1. Step 1: Create app

- Follow the link https://developers.haravan.com/apps
(If you haven’t logged in, the system will redirect to sign in https://accounts.haravan.com, and at this page you can sign in or sign up).

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.

Create app

- Screen for create application.

Create app

  • 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.

Create app

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: https://docs.haravan.com/blogs/omni/tutorial-use-scope

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.

Haraweb scopes

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.

Commerce scopes

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/

Use ngrok to test register webhook

3.2 Register webhook:

- Go to Webhooks, select Register button to register webhooks

Register webhook

- 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.

Đăng ký webhook

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

Register webhook

- Reference: Connect Webhooks

3.3 Topics need to subscribe:

3.3.1 Topic shop/update:

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.

Topic shop/update

Topic shop/update

- Some important information of the shop.


Property

Description

1

domain

Domain of the sales page

2

myharavan_domain

Domain of the admin page

3

email

Email

4

customer_email

Customer support email

5

shop_owner

Name of shop owner

3.3.2 Topic app/uninstalled:

Topic shop/update

- 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.

Topic app/uninstalled

Topic app/uninstalled


Property

Description

1

org_id

orgid of the shop uninstall app

2

app_id

App ID was obtained after creating the application in step 1

3

client_id

Client ID was obtained after creating the application in step 1

4

event_type

same as topic in Headers

5

user_id

id of the user who uninstalled the app

6

is_salechannel

Show in sales channel menu
true : show
false: not show

7

is_martketing

Show 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.


Property

Description

1

response_mode

Form method responses

2

url_authorize

Login url of Haravan system

3

url_connect_token

Url get the token for the application

4

grant_type

Type of code level.
Always “authorization_code”

5

nonce

string random at least 1 character

6

response_type

Select the fields you want to receive

7

app_id

App ID was obtained after creating the application in step 1

8

app_secret

App Secret was obtained after creating the application in step 1

9

scope_login

Required scopes when logging into the haravan system
They are: openid, profile, email, org, userinfo

10

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)

11

login_callback_url

declared at step 1 in Url redirect, used to login to the haravan system

12

install_callback_url

declared at step 1 in Url redirect, used to install the application

13

webhook

13.1

hrVerifyToken

Authentication code webhook, declared at step 3 Can get a random string at https://randomkeygen.com/ (CodeIgniter Encryption Keys)

13.2

subscribe

url 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

Method

URL  

GET

https://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



Property

Required

Description

1

response_mode

true

Form method responses

2

response_type

true

Select the fields you want to receive

3

scope

true

scope_login in configuration file

4

client_id

true

App ID was obtained after creating the application in step 1

5

redirect_uri

true

login_callback_url in configuration file

6

nonce

true

string random at least 1 character

7

orgid


may 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

Method

URL  

GET

https://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


Property

Required

Description

1

response_mode

true

Form method responses

2

response_type

true

Select the fields you want to receive

3

scope

true

scope in configuration file

4

client_id

true

App ID was obtained after creating the application in step 1

5

redirect_uri

true

install_callback_url in configuration file

6

nonce

true

string random at least 1 character

7

orgid

true

obtained 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

Decode id_token get sid

Bước 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

Trên môi trường  postman


Property

Required

Description

1

OAuth2

true

Declare OAuth library of nodejs

2

grant_type

true

grant_type in configuration file

3

callback_url

true

install_callback_url in configuration file

4

client_id

true

app_id in configuration file

5

client_secret

true

app_id in configuration file

6

code

true

Code received in step 7

8.2 Response get Access_token

Status

Response

200

params: {
"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 Sử dụng 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

Trên môi trường  postman

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.

Use the application after installation

- 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.

Handle when the user logout

Handle when the user logout

- 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.

Handle when the user logout

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

Handle when the user logout

Handle when the user logout

- 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.