Create App and Connect API
TABLE OF CONTENTS
- LOGIN AND INSTALL APPLICATION WORKFLOWS
- 1. Step 1: Create app
- 2. Step 2: Select scope for the application
- 3. Step 3: Connect webhook
- 4. Step 4: Configuration for the application
- 5. Step 5: Login to get authorization code
- 6. Step 6: Verify information
- 7. Step 7: Install to get authorization code
- 8. Step 8: Lấy Access_token
- 9. Step 9: Use the application after installation
- 10. Step 10: Handle when the user logout
LOGIN AND INSTALL APPLICATION WORKFLOWS
1. Step 1: Create app
- Follow the link https://partners.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).
- 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
- You need to declare at least 2 URLs: login and install
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 to register webhooks
You need to fill in some information
- Callback URL: Webhooks will GET a message with query 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.
GET {YOUR_WEBHOOK_CALLBACK_URL}?hub.mode=subscribe&hub.verify_token={Verify_Token}&hub.challenge=bf54608bf2004fc2a528f9e69f774135
You need to compare hub.verify_token (in object) with verify_token (in your app).
- If not match, response status 401.
- If match, response status 200 and value of hub.challenge
After registered, you need to reload this page to see the list of events that can subscribe to get notifications.
- Reference: Connect Webhooks
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.
| Property | Description |
|---|---|
| domain | Domain of the sales page |
| myharavan_domain | Domain of the admin page |
| customer_email | Customer support email |
| shop_owner | Name 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.
| Property | Description |
|---|---|
| org_id | orgid of the shop uninstall app |
| app_id | App ID was obtained after creating the application in step 1 |
| client_id | Client ID was obtained after creating the application in step 1 |
| event_type | same as topic in Headers |
| user_id | id of the user who uninstalled the app |
| is_salechannel | Show in sales channel menu true : show false: not show |
| is_martketing | Show in marketing menu true : show false: not show |
4. Step 4: Configuration for the application
After basic configuration on https://partners.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 |
|---|---|
| response_mode | Form method responses |
| url_authorize | Login url of Haravan system |
| url_connect_token | Url get the token for the application |
| grant_type | Type of code level. Always “authorization_code” |
| nonce | string random at least 1 character |
| response_type | Select the fields you want to receive |
| app_id | App ID was obtained after creating the application in step 1 |
| app_secret | App Secret was obtained after creating the application in step 1 |
| scope_login | Required 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_url | declared at step 1 in Url redirect, used to login to the haravan system |
| install_callback_url | declared at step 1 in Url redirect, used to install the application |
| webhook | |
| hrVerifyToken | Authentication code webhook, declared at step 3 Can get a random string at https://randomkeygen.com/ (CodeIgniter Encryption Keys) |
| 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://localhost:3000/install/login&nonce=asdfasdgd&orgid=1000198788
| Property | Required | Description |
|---|---|---|
| response_mode | true | Form method responses |
| response_type | true | Select the fields you want to receive |
| scope | true | scope_login in configuration file |
| client_id | true | App ID was obtained after creating the application in step 1 |
| redirect_uri | true | login_callback_url in configuration file |
| nonce | true | string random at least 1 character |
| orgid | may be passed to the request param of login_callback_url or not |
5.2 Response get code
| Status | Response |
| 200 | |
| 401 | Unauthorized |
| 422 | |
| 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://localhost:3000/install/login&nonce=asdfasdgd&orgid=1000198788
| Property | Required | Description |
|---|---|---|
| response_mode | true | Form method responses |
| response_type | true | Select the fields you want to receive |
| scope | true | scope in configuration file |
| client_id | true | App ID was obtained after creating the application in step 1 |
| redirect_uri | true | install_callback_url in configuration file |
| nonce | true | string random at least 1 character |
| orgid | true | obtained when decode id_token from step 6 |
7.2 Response get code
| Status | Response |
| 200 | |
| 401 | Unauthorized |
| 422 | |
| 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
| Property | Required | Description |
|---|---|---|
| OAuth2 | true | Declare OAuth library of nodejs |
| grant_type | true | grant_type in configuration file |
| callback_url | true | install_callback_url in configuration file |
| client_id | true | app_id in configuration file |
| client_secret | true | app_id in configuration file |
| code | true | Code received in step 7 |
8.2 Response get Access_token
| Status | Response |
| 200 | |
| 401 | Unauthorized |
| 422 | |
| 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://partners.haravan.com/apps
- 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.