KakaFlow KB

Hướng dẫn kết nối và sử dụng Shopee Open API

13 phút đọc

Hướng dẫn kết nối và sử dụng Shopee Open API

Trust: ★★★☆☆ (0.90) · 0 validations · factual

Published: 2021-08-05 · Source: crawler_authoritative

Tình huống

Người bán Shopee (Shop Yêu Thích hoặc Shopee Mall) hoặc đối tác bên thứ ba muốn kết nối API để quản lý đơn hàng và sản phẩm thông qua hệ thống riêng

Insight

Shopee Open API cho phép người bán và đối tác bên thứ ba kết nối hệ thống quản lý riêng với Shopee. Điều kiện sử dụng: tài khoản phải là Shop Yêu Thích hoặc Shopee Mall, có lập trình viên hỗ trợ, có hệ thống quản lý đơn hàng/sản phẩm riêng được lập trình trên website. Đối tác bên thứ ba cần có giấy phép kinh doanh, website chính thức và tài khoản dùng thử. Quy trình xét duyệt: đăng ký tại Shopee Open Platform, thời gian xử lý 3 ngày làm việc cho người bán, 1-2 tuần cho đối tác bên thứ ba. Có 4 loại nhà phát triển: Individual Seller (hộ kinh doanh cá thể), Enterprise Seller (doanh nghiệp), ISV Enterprise 3rd party (đối tác bên thứ ba). API có 2 môi trường: Live environment (thực tế) và Sandbox environment (thử nghiệm). Mỗi APP có thể tạo tối đa 9 Local Shop, 9 Cross Border Shop và 3 Merchant test account. Shop Authorization cần qua 3 bước: lập trình viên tạo authorization link, người bán click và đăng nhập, người bán xác nhận ủy quyền. Authentication sử dụng HMAC-SHA256 với signature base string được tạo từ URL API + | + Request Body. Tất cả API sử dụng phương thức POST với Content-Type: application/json.

Hành động

Bước 1: Kiểm tra điều kiện - đảm bảo tài khoản là Shop Yêu Thích hoặc Shopee Mall, có lập trình viên và hệ thống quản lý riêng. Bước 2: Đăng ký tài khoản tại https://open.shopee.com, nhập email hợp lệ, xác minh email, tạo password. Bước 3: Chọn Console, điền thông tin Profile, chọn loại nhà phát triển phù hợp (Individual Seller, Enterprise Seller, hoặc ISV). Cung cấp Shop username và Key Account Manager’s Email nếu là Shopee Seller. Bước 4: Đợi xét duyệt (3 ngày cho người bán, 1-2 tuần cho đối tác). Bước 5: Sau khi được duyệt, tạo APP bằng cách chọn App List > Create App, điền APP Type, APP Name, chọn VietNam cho App Service Region. Bước 6: Chọn Go-Live để chuyển từ Sandbox sang Live environment. Bước 7: Tạo authorization link với Fixed Authorization URL + partner_id + token (SHA256 hash) + redirect_URL. Bước 8: Người bán click authorization link, đăng nhập và xác nhận ủy quyền. Bước 9: Lấy shop_id từ email, redirect URL hoặc callback URL. Bước 10: Authenticate request bằng cách tạo signature base string (URL + | + Request Body) và mã hóa bằng HMAC-SHA256. Sử dụng Postman hoặc công cụ tương tự để test API với phương thức POST và header Authorization.

Điều kiện áp dụng

Chỉ áp dụng cho tài khoản Shop Yêu Thích hoặc Shopee Mall. Cần có lập trình viên và hệ thống quản lý riêng. Đối tác bên thứ ba cần giấy phép kinh doanh.

Nội dung gốc (Original)

Hướng dẫn kết nối API 05-08-2021 Đánh dấu trang Điều Kiện Sử Dụng & Quy Trình Xét Duyệt Open API

  1. Điều kiện sử dụng Open API

1.1. Đối với Người Bán

Tài khoản mà bạn muốn kết nối API phải là tài khoản Shop Yêu Thích hoặc Shopee Mall. Bạn phải có lập trình viên để hỗ trợ kết nối API Bạn cần có hệ thống quản lý đơn hàng, sản phẩm riêng (Hệ thống phải được lập trình trên website để quản lý đơn hàng, sản phẩm). Hệ thống của bạn phải có khả năng kết nối với hệ thống khác.

1.2. Đối với đối tác là bên thứ ba (3rd Party)

Đối tác cần có giấy phép kinh doanh và website chính thức của công ty. Cần cung cấp tải khoản dùng thử và mật khẩu để Shopee kiểm chứng tài khoản trước khi xét duyệt.

  1. Quy Trình Xét Duyệt API

Bạn cần đăng ký tài khoản API tại Shopee Open Platform TẠI ĐÂY. Tham khảo hướng dẫn để đăng ký tài khoản TẠI ĐÂY.

Sau khi đăng ký thành công, tài khoản của bạn sẽ được Shopee xét duyệt (tối đa 2 tuần kể từ khi đăng ký tài khoản). Chi tiết ở bảng bên dưới:

Đối tượng xét duyệt

Thời gian xử lý

Người Bán

3 ngày làm việc

Đối tác là bên thứ 3

1 -2 tuần làm việc (tùy thuộc vào những nội dung cần xác minh thêm với từng đối tác)

Sau thời gian xử lý, Shopee sẽ gửi email thông báo cho bạn kết quả xét duyệt với nội dung như sau:

Xét duyệt thành công: bạn sẽ nhận được hướng dẫn để bắt đầu sử dụng API. Tham khảo hướng dẫn sử dụng API TẠI ĐÂY Xét duyệt không thành công: bạn sẽ nhận được thông báo từ Shopee và hướng dẫn tùy vào trường hợp của bạn.  Hướng Dẫn Đăng Ký Tài Khoản Open API

  1. Đăng ký tài khoản Shopee Open Platform

Bước 1: Truy cập đường link sau để đăng ký tài khoản Shopee Open Platform: https://open.shopee.com/

Bước 2: Nhập email để đăng ký tài khoản.

⚠️Lưu ý:

  • Địa chỉ Email và tên Công ty/ Shop không thể thay đổi sau khi đã hoàn thành đăng ký.
  • Bạn cần cung cấp địa chỉ Email hợp lệ để Shopee có thể gửi yêu cầu xác nhận đến Email của bạn.

Bước 3: Chọn Verify your email trong email yêu cầu xác minh

Bước 4: Điền Password và chọn Create.

Sau khi xác minh email thành công, bạn có thể đăng nhập vào tài khoản của mình.

Bước 5: Điền thông tin chi tiết

5.1. Chọn Console để chuyển sang trang điền thông tin cơ bản.

5.2. Để sử dụng Open API, tài khoản của bạn cần được Shopee xét duyệt, thông qua việc cung cấp thông tin tài khoản (Profile). Chọn loại app bằng cách nhấn chọn tên app tương ứng và điền thông tin

5.3. Điền thông tin 

⚠️Lưu ý: Bạn có thể lựa chọn 4 loại Nhà phát triển, mỗi loại Nhà phát triển chỉ có thể tạo một số loại APP tương ứng. Hiện tại Shopee Việt Nam chưa hỗ trợ Individual 3rd Party:

  • Chọn “Individual Seller” nếu bạn là Người bán trên Shopee, và là hộ kinh doanh cá thể.
  • Chọn “Enterprise Seller” nếu bạn là Người bán trên Shopee, và là doanh nghiệp.
  • Chọn “ISV (Enterprise 3rd party)” nếu bạn không phải là Người bán trên Shopee, và là đối tác bên thứ 3.

Chi tiết về mỗi loại Nhà phát triển và các APP tương ứng, bạn có thể tham khảo thêm TẠI ĐÂY

⚠️ Lưu ý: Nếu bạn là Shopee Seller: bạn phải cung cấp Shop username (tên đăng nhập) của Shop bạn và Key Account Manager’s Email (tên của nhân viên hỗ trợ ngành hàng) nếu có. (Những thông tin này là tùy chọn)

Trong trường hợp bạn chưa biết username, đăng nhập vào banhang.shopee.vn, username sẽ nằm ở góc trên bên phải của màn hình như hình minh họa.

Bạn đã hoàn tất bước đầu tiên để liên kết Open API. Shopee sẽ xét duyệt tài khoản của bạn và kết quả xét duyệt sẽ được thông qua Email mà bạn đã dùng để đăng ký tài khoản. (Xem thêm mục Điều Kiện Sử Dụng & Quy Trình Xét Duyệt Open API TẠI ĐÂY)

  1. Tạo APP (Sau khi tài khoản được xét duyệt thành công)

Bước 1: Chọn App List

Bước 2: Chọn Create App

Bước 3: Điền thông tin bổ sung:

APP Type: Lựa chọn type phù hợp với mục đích của bạn. (Tham khảo các loại APP type TẠI ĐÂY) APP Name: Nhập App Name. App Service Region: Chọn VietNam. App Description: Miêu tả về App. App Logo: Chọn Logo cho App của mình.

Bước 4: Kiểm tra lại thông tin của bạn và chọn Submit (Sau khi Submit thì bạn đã đăng ký thành công trên môi trường Thử nghiệm (Sandbox) và có thể sử dụng Test partner_id, Test key cho môi trường này)

Bước 5: Chọn Go-Live để có thể sử dụng API trên môi trường thực tế (Live)

Bước 6: Điền thông tin cơ bản

Bước 7: Chọn Submit và đợi trong vòng 24h

⚠️ Lưu ý: Bạn nên kiểm tra thật kĩ mọi thứ trước khi xác nhận chuyển qua môi trường thực tế vì mọi thao tác trên môi trường này sẽ có hiệu lực ngay. 

  1. Cách xóa App trong Shopee Open Platform

Bước 1: Chọn App List

Bước 2: Chọn APP muốn xóa

Bước 3: Chọn Delete

Bước 4: Chọn Confirm để xác nhận khi có thông báo hiển thị

Hướng Dẫn Sử Dụng API

  1. Phân biệt môi trường trên API

Sau khi App đã được xét duyệt, Người Bán sẽ nhận được thông tin API của 2 môi trường là Live và Sandbox environment.

Live environment:

Sandbox environment:

  1. Sử dụng tài khoản test trên Sandbox environment

Shopee sẽ cung cấp test account để các lập trình viên có thể mô phỏng hoạt động mua bán giống với môi trường Live và kiểm tra các tính năng có trong tài khoản test.

Seller account:

Bạn có thể đăng nhập vào Seller test account của mình bằng cách sử dụng thông tin account có trong https://open.shopee.com→ login → Console → Tool → Test Account → Create Test Account.

⚠️Lưu ý: Số lượng test account mỗi APP có thể tạo tối đa là 9 Local Shop, 9 Cross Border Shop và 3 Merchant. Mỗi test account bao gồm một cặp shop - buyer và có thể được sử dụng với mục đích Seller & Buyer

Buyer account:

Bạn có thể sử dụng test account đã tạo để dùng làm Buyer account và mô phỏng quy trình mua hàng như ở trên môi trường Live.

  1. Shop Authorization

Để APP của bạn gọi được API cho Shop, APP cần được ủy quyền bởi Người bán thông qua phương thức Shop Authorization với quy trình như sau:

Lập trình viên tạo authorization link Người bán click vào authorization link và đăng nhập bằng tài khoản Người bán Người bán xác nhận ủy quyền cho APP

  • Lập trình viên tạo authorization link theo quy tắc dưới đây:

Authorization link là URL được kết hợp giữa Fixed Authorization URL và Các params cần thiết.

  • Fixed Authorization URL:

Đối với Test environment (Sandbox) : https://partner.test-stable.shopeemobile.com/api/v1/shop/auth_partner Đối với Live environment : https://partner.shopeemobile.com/api/v1/shop/auth_partner

  • Các params cần thiết:

Partner_id:

  • Đối với Test environment (Sandbox): console → App List → APP Overview → Test Partner_id.

  • Đối với Live environment: console → App List → APP Overview → Live Partner_id.

Token: được tính bằng thuật toán SHA256, gồm 2 bước:

  • Tạo token base string: join Key và redirect url với nhau.

Ví dụ: 9b754aba01a5d719cc70c57782941ae6ff90fcc687282908ee480a364901d181https://www.google.com

  • Dùng thuật toán SHA256 để hash chuỗi token base string ở trên, với Output cần phải được mã hóa hex để tạo ra Token

Redirect_URL:

Đây sẽ là URL mà Người bán được chuyển về sau khi ủy quyền hoàn tất. Thông tin shop_id sẽ được truyền vào URL này, lập trình viên có thể lưu shop_id được trả về để dễ dàng quản lý thông tin shops.

Ví dụ authorization link hoàn chỉnh:

https://partner.test-stable.shopeemobile.com/api/v1/shop/auth_partner?id=70148&token=815d97b3a582e2e39957545a0c8c3da63d2466b902a32956ddd7a784badccdb8&redirect=https://www.google.com

  • Người bán xác nhận ủy quyền cho APP:

  1. Chọn VietNam sau đó nhập username và password của Kênh Người Bán.

  2. Chọn Login.

  3. Nhập OTP và chọn Verify.

  4. Chọn Confirm Authorization để xác nhận authorization.

  • Cách lấy ShopID:

Có ba cách để lấy shop ID sau khi cửa hàng ủy quyền:

Thông báo Shop ID sẽ được gửi đến email đã đăng ký của lập trình viên (Không áp dụng cho test environment). Shop ID hiển thị trong redirect URL sau khi ủy quyền thành công.

Thông báo trong Json sẽ được push đến Callback URL của lập trình viên ( xem thêm Push Mechanism )

  • Cách hủy Authorization:
  • Quy trình tương tự như Shop Authorization trừ url authorization thay đổi thành cancel_auth_partner:
  1. Cách Authenticate Request

Để tăng tính bảo mật của API, Shopee yêu cầu Lập trình viên cần authenticate request để gọi thành công bất kỳ API nào với Authorization signature ở headers.

Quy trình tạo Authorization signature như sau:

  • Tạo signature base string

  • Mã hóa signature base string bằng thuật toán HMAC-SHA256

  1. Tạo signature base string:
  • Signature base string được hình thành bằng cách join URL của API cần gọi, |, Request Body.

Ví dụ của GetOrderDetail API:

https://partner.shopeemobile.com/api/v1/orders/detail|{“ordersn”:“160798865”,“shopid”:61299,“partner_id”:1,“timestamp”:1470198856}

  1. Mã hóa signature base string bằng thuật toán HMAC-SHA256:
  • Để mã hóa, lập trình viên cần sử dụng signature base string từ bước 1 và Key từ Shopee Open Platform và cho vào hàm HMAC-SHA256. Các chi tiết của thuật toán được giải thích tại đây. Output của hàm này cần được mã hóa hex để tạo ra Authorization signature.

Ví dụ về Authorization Signature:

b37c061daf2fcfa2baffe7539110938be5b7525041c147e78ad8afa78cc1a72d

Sử dụng Authorization Signature

  • Một request đến Shopee APi thông thường sẽ có format giống như bên dưới:

POST /api/v1/orders/detail HTTP/1.1

Host: partner.shopeemobile.com

Content-Type: application/json

Content-Length: 89

Authorization: b37c061daf2fcfa2baffe7539110938be5b7525041c147e78ad8afa78cc1a72d

{“ordersn”:“160726152598865”,“shopid”:61299,“partner_id”:1,“timestamp”:1470198856}

  1. Cách để test Open API

Lập trình viên có thể sử dụng các công cụ kiểm tra API (ví dụ: Postman, SoapUI, KarateDSL) để gọi các chức năng Shopee Open API.

Ví dụ về sử dụng Postman:

  1. Tất cả các API cần sử dụng phương thức POST.

  2. Để biết thêm chi tiết về các hàm API, vui lòng tìm hiểu trong https://open.shopee.com/documents.

  3. Tất cả các request gọi đến Shopee API cần phải chứa HTTP header Content-Type: application/json.

  4. Để có được giá trị cho field Authorization, vui lòng làm theo hướng dẫn “Cách Authenticate Request”

  5. HTTP body chỉ nên chứa một chuỗi JSON được tuần tự hóa. 3 tham số dưới đây sẽ xuất hiện trong tất cả các yêu cầu:

  6. Thông tin liên quan Shopee Open platform portal: https://open.shopee.com API Document: https://open.shopee.com/documents Developer Guide: https://open.shopee.com/documents?module=63&type=2&id=51 API Call Flow: https://open.shopee.com/documents?module=63&type=2&id=54 Authenticate a request: https://open.shopee.com/documents?module=63&type=2&id=53 Data Definition: https://open.shopee.com/documents?module=63&type=2&id=50

Bài viết này có hữu ích đối với bạn? Có nè Không hẳn Quay lại: Hướng dẫn yêu cầu hỗ trợ (raise ticket) API trên Shopee Open Platform Tham khảo thêm Hướng dẫn yêu cầu hỗ trợ (raise ticket) API trên Shopee Open Platform

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược