Hướng Dẫn dùng Scope

Các mục liên quan

1. SCOPE HARAWEB

1.1 Scope

- Scope trong mục Haraweb của https://developers.haravan.com

- Khi đã chọn ở đây thì phải truyền các scope tương ứng vào khi cài app.

- Dành cho các api dùng ngoài website bán hàng.

- Cách khai báo scope ở mục Haraweb : web.{tên_scope}
VD : web.read_script_tags

Chọn scope cho app

TênScopeAPI
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 Các đầu api tương ứng với scope

- Ứng với các scope sẽ là quyền truy cập đến các đầu api tương ứng.

- Các scope Write sẽ bao gồm quyền read và sử dụng được các method : GET, POST, PUT, DELETE

- Các scope chỉ sử dụng được menthod GET

- Đầu api là: https://apis.haravan.com/web

- Gọi các api theo cú pháp : https://apis.hara.vn/web/{api}
VD : gọi api lấy scriptTags : https://apis.hara.vn/web/script_tags.json (GET)

2. SCOPE COMMERCE

2.1 Scope

- Scope trong mục Commerce của https://developers.haravan.com

- Khi đã chọn ở đây thì phải truyền các scope tương ứng vào khi cài app.

- Dành cho các api dùng trong trang quản trị bán hàng.

- Các khai báo scope ở mục Commerce : com.{tên_scope}
VD : com.write_products

SCOPE COMMERCE

2.2 Các đầu api tương ứng với scope

- Ứng với các scope sẽ là quyền truy cập đến các đầu api tương ứng.

- Các scope Write sẽ bao gồm quyền read và sử dụng được các method : GET, POST, PUT, DELETE

- Các scope chỉ sử dụng được menthod GET

- Đầu api là: https://apis.haravan.com/com

- Gọi các api theo cú pháp : https://apis.hara.vn/com/{api}
VD : gọi api lấy products : https://apis.hara.vn/com/products.json (GET)

TênScopeAPI
Write Inventoriescom.write_inventorie

/inventories/transfer.json

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

/inventories/adjustorset.json

Read Inventoriescom.read_inventorie

/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

- Là scope để sử dụng webhook cho app và chỉ chủ shop (role là admin) mới có thể dùng được

- Khi sử dụng webhook thì bắt buộc phải truyền scope

- Cần phải register webhook trên https://developers.haravan.com trước khi truyền scope này vào.

ScopeMô tả
wh_apiScope dùng webhook

4. SCOPE LOGIN

- Là những scope tối thiểu để login lấy thông tin user khi cài app.

- Ngoài ra còn có thể truyền kèm các scope đã chọn ở harawebcommerece

STTScopeMô tả
1openid
2profile
3emailLấy email user đang đăng nhập
4orgLấy thông tin org (org_id , org_name)
5userinfoLấy thông tin user đang đăng nhập

5. SCOPE INSTALL

- Là những scope dùng để cài app.

- Gồm:
+ Những scope bắt buộc phải có.

STTScopeMô tả
1openid
2profile

+ Scope sử dụng webhook

+ Những scope đã chọn ở harawebcommerece

6. CÁCH SỬ DỤNG SCOPE KHI CÀI APP

- Khi cài app, ta cần lưu ý đến những scope login và scope install.

- Như ta thấy, scope login và install đa phần giống nhau và đều được dùng để truyền đến url authorize để lấy code và id_token. Vì vậy, tùy theo các truyền scope mà ta có thể cài app theo hai cách.

Lưu ý: ở đây chỉ mô tả cách hoạt động của việc truyền scope, tham khảo hướng dẫn tạo app và kết nối api để biết chi tiết cách lấy access_token.

6.1 Dùng scope login để cài app

6.1.1 Cách hoạt động

- Như đã đề cập, login và install đều gọi đến url authorize nhưng khác scope truyền vào (scope login hoặc install).

- Do đó , ta có thể truyền kèm scope ở haraweb và commerece cùng với scope login ngay từ lần đầu gọi đến url.

- Ta vẫn sẽ có code tương ứng với các scope truyền vào, dùng thư viên oauth 2 để render ra access_token.

6.1.2 Đặc điểm

- Chỉ cần thực hiện gọi url authorize một lần.

- Access_token này được gọi là access_token user, có thời gian sử dụng ngắn hạn.

- App chỉ có thể dùng bởi user thực hiện cài app.

- Không xuất hiện trên danh sách ứng dụng của seller.

- Không dùng được webhook.

6.2 Dùng scope login và cả scope install để cài app (Khuyến khích)

6.2.1 Cách hoạt động

- Đầu tiên, ta gọi đến url authorize với scope login để nhận được id_token.

- Dùng jwt để decoded id_token này ra một object bao gồm thông tin user, role user, thông tin shop.

- Ta kiểm tra xem user đang đăng nhập:

  • Là chủ shop (role là admin) thì thực hiện gọi đến url authorize với scope install (vì scope webhook và scope grant_service chỉ bắt buộc phải là chủ shop mới dùng được)
  • Không phải chủ shop (role không phải admin) báo lỗi.

- Ta có được code tương ứng với các scope truyền vào, dùng thư viên oauth 2 để render ra access_token.

6.2.2 Đặc điểm

- Có thể kiểm tra thông tin user và shop 2 lần , tăng độ bảo mật và khả năng phân quyền.

- Access_token có thời gian sử dụng dài hạn.

- App xuất hiện trên danh sách ứng dụng của seller.

7. CÁCH SỬ DỤNG SCOPE LOGIN KHI VÀO APP

- Sau khi cài app, ta cần phải kiểm tra user đang đăng nhập có quyền vào app hay không.

- Có hai loại phân quyền:

  • Phân quyền của user trên seller
  • Phân quyền của user trên app (đây là phân quyền riêng tự cấu hình trên app)

- Khi user nhấp vào app, ta gọi đến url authorize với scope login, nhận được id_token.

- Dùng jwt để decoded id_token này ra một object bao gồm thông tin user, role user, thông tin shop.

- Sau đó chúng ta tiến hành kiểm tra :

  • Nếu là chủ shop (role là admin) thì vào app
  • Nếu không phải chủ shop (role không phải admin), thì có 3 trường hợp:
    • Trường hợp 1: phân quyền trên seller của user không đủ quyền để dùng các scope của app, xuất thông báo không có quyền vào app.
    • Trường hợp 2: phân quyền trên seller của user đủ quyền để dùng scope của app nhưng user đó không được phân quyền trên app (nếu có hệ thống phân quyền riêng của app), xuất thông báo không có quyền vào app.
    • Trường hợp 3: phân quyền trên seller của user không đủ quyền để dùng các scope của app và user đó được phân quyền trên app (nếu có hệ thống phân quyền riêng của app), thì vào app.