TUTORIAL FOR USE SCOPE

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
Write Contentsweb.write_contents

blog

/blogs/{blogId}/articles.json

/blogs/{blogId}/articles/{article_id}.json

/blogs.json

/blogs/{blog_id}.json

/blogs/{blog_id}/metafields.json

/blogs/{blog_id}/metafields/{metafield_id}.json

/blogs/{blogId}/articles/{article_id}/metafields.json

comments

/comments.json

/comments/{comment_id}.json

/comments/{comment_id}/spam.json

/comments/{comment_id}/not_spam.json

/comments/{comment_id}/approve.json

/comments/{comment_id}/restore.json

/comments/{comment_id}/remove.json

pages

/pages/{page_id}/metafields.json

/pages/{page_id}/metafields/{metafield_id}.json

/pages.json

/pages/{page_id}.json

redirects

/redirects/{urlredirect_id}.json

/redirects.json

Read Contentsweb.read_contents

blogs

/blogs.json

/blogs/count.json

/blogs/{blog_id}.json

/blogs/{blog_id}/articles.json

/blogs/{blog_id}/articles/{article_id}.json

/blogs/{blog_id}/articles/count.json

/blogs/{blog_id}/articles/tags.json

/blogs/{blog_id}/metafields.json

/blogs/{blog_id}/metafields/count.json

/blogs/{blog_id}/metafields/{metafield_id}.json

/blogs/{blog_id}/articles/{article_id}/metafields.json

/blogs/{blog_id}/articles/{article_id}/metafields/count.json

/blogs/{blog_id}/articles/{article_id}/metafields/{metafieldId}.json

comment

/comments.json

/comments/count.json

/comments/{comment_id}.json

pages

/pages.json

/pages/count.json

/pages/{page_id}.json

/pages/{page_id}/metafields.json

/pages/{page_id}/metafields/count.json

/pages/{page_id}/metafields/{metafieldId}.json

redirect

/redirects.json

/redirects/count.json

/redirects/{urlredirect_id}.json

articles

/articles/authors.json

/articles/tags.json

Write Themesweb.write_themes

/themes.json

/themes/{theme_id}.json

/themes/{theme_id}/assets.json

Read Themesweb.read_themes

/themes.json

/themes/{theme_id}.json

/themes/{theme_id}/assets.json

Write AppProxiesweb.write_app_proxies/apps/{appId}/app_proxy.json
Read AppProxiesweb.read_app_proxies/apps/{appId}/app_proxy.json
Write ScriptTagsweb.write_script_tags

/script_tags.json

/script_tags/{id}.json

/script_tags/count.json

Read ScriptTagsweb.read_script_tags

/script_tags/{id}.json

/script_tags.json

1.2 API List for haraweb scope

- Corresponding to the scope will be the 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 the 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
Write Inventoriescom.write_inventories

/inventories/transfer.json

/inventories/transfer/{transferId}/receive.json

/inventories/adjustorset.json

Read Inventoriescom.read_inventories

/inventories.json

/inventories/adjustments/{adjustmentId}.json

/inventories/adjustments.json

/inventories/adjustments/count.json

/inventories/transfers.json

/inventories/transfers/count.json

/inventories/purchase_orders/{purchaseId}.json

/inventories/purchase_orders.json

/inventorytransaction/count.json

/inventorytransaction/detail/{id}.json

/inventorylocationbalance/count.json

/inventorylocationbalance/listids.json

/inventorylocationbalance/detail/{id}.json

/inventorytransfer/count.json

/inventorytransfer/listids.json

/inventorytransfer/detail/{id}.json

/inventorytransaction/listids.json

Write Shippingscom.write _shippings

/carrier_services.json

/carrier_services/{carrierId}.json

Read Shippingscom.read_shippings

/carrier_services.json

/carrier_services/{carrierId}.json

Write Customerscom.write_customers

/customers.json

/customers/{customerId}/addresses/{addressId}.json

/customers/{customerId}/addresses.json

/customers/{customerId}.json

/customers/{customer_id}/timeline_comments.json

/customers/{customerId}/addresses/set.json

/customers/{customerId}/addresses/{addressId}/default.json

/customers/{customer_id}/metafields.json

/customers/{customer_id}/metafields/{metafield_id}.json

Read Customerscom.read_customers

/customers.json

/customers/groups.json

/customers/search.json

/customers/{customerId}/addresses/{addressId}.json

/customers/{customerId}/addresses.json

/customers/{customerId}.json

/customers/{customer_id}/timeline_comments.json

/customers/{customer_id}/timeline_comments/count.json

/customers/{customer_id}/metafields.json

/customers/{customer_id}/metafields/count.json

/customers/{customer_id}/metafields/{metafield_id}.json

Write Shippings Zonescom.write_shipping_zones
Read Shippings Zonescom.read_shipping_zones
Write Productscom.write_products

products

/products.json

/products/{product_id}.json

/products/{productId}/variants.json

/products/{productId}/variants/{variantId}.json

/products/{productId}/images.json

/products/{productId}/images/{imageId}.json

/products/{ productId }/metafields.json

/products/{productId}/metafields/{metafield_id}.json

smart_collections

/smart_collections/{collection_id}.json

/smart_collections/{collection_id}/metafields/{metafield_id}.json

collects

/collects.json

/collects/{collect_id}.json

custom_collections

/custom_collections.json

/custom_collections/{collection_id}/metafields/{metafield_id}.json

collections

/collections/{collectionId}/metafields/{metafieldId}.json

variants

/variants/{variantId}.json

/variants/{variant_id}/metafields.json

/variants/{variant_id}/metafields/{metafield_id}.json

images

/images/{image_id}/metafields.json

/images/{image_id}/{metafield_id}.json

/images/{image_id}/metafields/{metafield_id}.json

Read Productscom.read_products

products

/products.json

/products/count.json

/products/{product_id}.json

/products/types.json

/products/vendors.json

/products/images/feature.json

/products/images/feature/count.json

/products/{productId}/images/count.json

/products/{productId}/images/{imageId}.json

/products/{productId}/variants.json

/products/{productId}/variants/count.json

/products/{productId}/images.json

/products/{ productId }/metafields.json

/products/{ productId }/metafields/count.json

/products/{ productId }/metafields/{metafield_id}.json

smart_collections

/smart_collections/{collection_id}.json

/smart_collections/count.json

/smart_collections.json

/smart_collections/{collection_id}/metafields.json

/smart_collections/{collection_id}/metafields/count.json

/smart_collections/{collection_id}/metafields/{metafieldId}.json

collects

/collects.json

/collects/count.json

/collects/{collect_id}.json

custom_collections

/custom_collections.json

/custom_collections/count.json

/custom_collections/{collection_id}.json

/custom_collections/{collection_id}/metafields.json

/custom_collections/{collection_id}/metafields/count.json

/custom_collections/{collection_id}/metafields/{metafield_id}.json

variants

/variants/{variantId}.json

/variants/{variant_id}/metafields.json

/variants/{variant_id}/metafields/count.json

/variants/{variant_id}/metafields/{metafield_id}.json

images

/images/{image_id}/metafields.json

/images/{image_id}/metafields/count.json

/images/{image_id}/metafields/{metafield_id}.json

collections

/collections/{collection_id}/product_ids.json

/collections/{collection_id}/metafields.json

/collections/{collection_id}/metafields/count.json

/collections/{collection_id}/metafields/{metafield_id}.json

Write Orderscom.write_orders

/orders.json

/orders/{orderId}.json

/orders/{orderId}/transactions.json

/orders/validatecoupon.json

/orders/{orderId}/confirm.json

/orders/{orderId}/close.json

/orders/{orderId}/open.json

/orders/{orderId}/cancel.json

/orders/{orderId}/fulfillments.json

/orders/{order_id}/metafields.json

/orders/{order_id}/metafields/{metafield_id}.json

/carts/promotions/calculate.json

/carts/calculate.json

/couponcode/validate.json

/promotions/calculate.json

Read Orderscom.read_orders

/orders.json

/orders/{orderId}.json

/orders/count.json

/orders/{orderId}/transactions.json

/orders/{orderId}/transactions/count.json

/orders/{orderId}/transactions/{id}.json

/orders/sum.json

/orders/affiliate.json

/orders/internal/count.json

/orders/listids.json

/orders/{orderId}/fulfillments/{fulfillmentId}/events.json

/orders/{orderId}/fulfillments/{fulfillmentId}/events/count.json

/orders/{orderId}/fulfillments.json

/orders/{orderId}/fulfillments/count.json

/orders/{orderId}/fulfillments/{fulfillmentId}.json

/orders/{order_id}/metafields.json

/orders/{order_id}/metafields/count.json

/orders/{order_id}/metafields/{metafield_id}.json

/setting_payments.json

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 email of 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 email of 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 commerece

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 authorize 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 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 authorize 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, increased 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 appliation only use scopes in haraweb, use this API:
https://apis.haravan.com/web/shop.json

- The appliation 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 seller
  • User authorization on Application (configured on the application)

- Before the user starts the application, 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 starts the application.
  • If the user isn’t the shop owner (role doesn’t contain ‘admin’), We have 3 cases:
    • Case 1: authorization on seller of the user’s account do 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.