TABLE OF CONTENTS

1. SCOPE HARAWEB

1.1 Scope

- These are scopes in “Haraweb” of https://developers.haravan.com

- Once selected here, you must pass the corresponding scopes when you install the application.

- For the API use at the sales page.

- The way to declare haraweb scope: web. {scope_name}.
Ex: web.read_script_tags.

Scope

NameScopeAPI
Contentsweb.read_contents
web.write_contens

Blog

Comment

Page

Redirect

Article

Themesweb.read_themes
web.write_themes

Theme

ScriptTagsweb.read_script_tags
web.write_script_tags

ScriptTag

1.2 API List for haraweb scope

- Corresponding to the scope will be access to the corresponding API.

- The write scope will include read permissions and use the methods: GET, POST, PUT, DELETE.

- The Read scope only uses the GET method.

- API prefix: https://apis.haravan.com/web

- Call the API with the syntax: https://apis.haravan.com/web/{api}.
EX: Call API get scriptTags: https://apis.haravan.com/web/script_tags.json (GET).

2. SCOPE COMMERCE

2.1 Scope

- These are scopes in “Commerce” of https://developers.haravan.com

- Once selected here, you must pass the corresponding scopes when you install the application.

- For the API use at the admin page.

- The way to declare commerce scope: com.{scope_name}.
Ex: com.write_products

SCOPE COMMERCE

2.2 API List for commerce scope

- Corresponding to the scope will be access to the corresponding API.

- The write scope will include read permissions and use the methods: GET, POST, PUT, DELETE.

- The Read scope only uses the GET method

- API prefix: https://apis.haravan.com/com

- Call the API with the syntax: https://apis.haravan.com/com/{api}.
EX: Call API products: https://apis.haravan.com/com/products.json (GET).

NameScopeAPI
Inventoriescom.read_inventories
com.write_inventories

Inventory adjustment



Inventory transfer
Purchase order
Inventory location
Shippingscom.read_shippings
com.write_shippings

Carrier service

Customerscom.read_customers
com.write_customers

Customer

Customer address

Productscom.read_products
com.write_products

Product

Smart_collection

Collect

Custom_collections

Product variant

Product Image

Write Orderscom.read_orders
com.write_orders

Order

Transaction

Fulfillment

3. SCOPE WEBHOOK

- This is a scope to using webhooks for the application. Only shop owner (role contains ‘admin’) can use it.

- When using webhooks, this scope is required.

- You need to register webhook on https://developers.haravan.com before using this scope.

ScopeDescription
wh_apiScope use webhook

4. SCOPE LOGIN

- These are the required scopes to log in and get user information

- Also you can add more scope from haraweb and commerce

 ScopeDescription
1openid 
2profile 
3emailGet an email of the login user
4orgGet org information (org_id , org_name)
5userinfoGet information of login user

5. SCOPE INSTALL

- These are the scopes used to install the application.

- These are the scopes include:

+ Required scopes.

 ScopeDescription
1openid 
2profile 
3emailGet an email of the login user
4orgGet org information (org_id , org_name)
5userinfoGet information of login user
6grant_serviceThis is the scope that only the shop owner (role contains ‘admin’) can use.
function:
+ Get long-lived access_token
+ Install the application on the Seller application list

+ Scope use webhook (optional)

+ Scopes are selected at haraweb and commerce

6. HOW TO USE SCOPE WHEN INSTALLING THE APP

- When installing, you need to focus on the scope login and scope install.

- As you can see, the scope login and install are mostly the same and both are used to pass to the authorized URL to get the code and id_token. So, depending on how to use the scope, you can install the app in two options.

- Note:

6.1 Option 1: Use scope login to install the app

6.1.1 How it works

- As mentioned, login and install are both call URL authorize but the different scope is passed (scope login or install).

- So, we can pass the selected scope at haraweb and commerce with the scope login right from the first call to the authorized URL.

- You still have the code corresponding to the scope passed, using the OAuth 2 library to render access_token.

6.1.2 Features

- call the authorization URL once.

- This access_token is called access_token user, and it’s short-lived access_token

- The application can only be used by users who install it.

- Does not appear on the seller app list.

- Unable to use webhook.

6.2 Option 2: Use scope login and scope install to install the app
(Recommended)

6.2.1 How it works

- First, call the authorization URL with scope login to get id_token.

- Use JWT to decode this id_token to get an object including user information, role users, shop information.

- You need to verify the role of the logged-in user:

  • If the user is the shop owner (role contains ‘admin’) then call URL authorize with scope install (because webhook scope and grant_service scope are only used by the shop owner)
  • If the user isn’t the shop owner (role doesn’t contain ‘admin’) then show the error message.

- You have the code corresponding to the scope passed, using the OAuth 2 library to render access_token.

6.2.2 Features

- Can verify user and shop information twice, increase security, and ability to manage users.

- Access_token is a long-lived access_token.

- Install the application on the Seller application list.

7. GET SHOP INFORMATION AFTER INSTALLING THE APP.

- The application only use scopes in haraweb, use this API:
https://apis.haravan.com/web/shop.json

- The application only use scopes in commerce, use this API
https://apis.haravan.com/com/shop.json

- Note: If you use both the scope in haraweb and commerce, you can use one of the APIs above.

8. HOW TO USE SCOPE LOGIN WHEN USING THE APP

- When the application was installed, we need to verify that the logged-in user has access to the application

- There are 2 types of user authorization:

  • User authorization on the seller
  • User authorization on Application (configured on the application)

- Before the user starts the application, call the authorization URL with scope login to get the id_token

- Use JWT to decode this id_token to get an object including user information, role users, shop information.

- You need to verify the role of the logged-in user:

  • If the user is the shop owner (role contains ‘admin’) then start the application.
  • If the user isn’t the shop owner (role doesn’t contain ‘admin’), We have 3 cases:
    • Case 1: authorization on the seller of the user’s account does not accept to use the scope of the application, show messages “you are not authorized to use the application”.
    • Case 2: That user has permission to use the application's scopes but the user is not authorized to use the app (if the application has its own authorization system), show messages “you are not authorized to use the application”.
    • Case 3: That user does not have permission to use the application's scopes, but the user is allowed to use the application (if the application has its own authorization system), starts the application.