KakaFlow KB

Hướng dẫn kết nối API Shopee - Điều kiện, quy trình và cách sử dụng

14 phút đọc

Hướng dẫn kết nối API Shopee - Điều kiện, quy trình và cách sử dụng

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

Published: 2021-08-05 · Source: crawler_authoritative

Tình huống

Người bán Shopee hoặc đối tác bên thứ ba muốn kết nối API để tự động hóa 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 kết nối tự động với hệ thống quản lý riêng nhưng có điều kiện nghiêm ngặt. Đối với người bá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, hệ thống có khả năng kết nối với hệ thống khác. Đối với đối tác bên thứ ba: cần giấy phép kinh doanh, website chính thức, cung cấp tài khoản dùng thử để Shopee kiểm chứng. Quy trình xét duyệt: đăng ký tại https://open.shopee.com, 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ó 3 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). Cần thực hiện Shop Authorization để APP được phép gọi API cho Shop. Tất cả request phải authenticate bằng Authorization signature sử dụng thuật toán HMAC-SHA256. Mỗi APP có thể tạo tối đa 9 Local Shop, 9 Cross Border Shop và 3 Merchant test account.

Hành động

Bước 1: Kiểm tra điều kiện - Đảm bảo là Shop Yêu Thích/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/ISV), cung cấp Shop username và Key Account Manager Email nếu có. 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 sang môi trường thực tế. Bước 7: Tạo authorization link theo format: Fixed Authorization URL + partner_id + token (SHA256) + 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 thông báo, redirect URL hoặc Callback URL. Bước 10: Authenticate mọi request bằng Authorization signature: tạo signature base string (URL + | + Request Body), mã hóa bằng HMAC-SHA256 với Key từ Shopee Open Platform. Bước 11: Sử dụng Postman hoặc công cụ tương tự để test API với phương thức POST, Content-Type: application/json.

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

Chỉ áp dụng cho Shop Yêu Thích hoặc Shopee Mall có đội ngũ lập trình viên và hệ thống quản lý riêng

Nội dung gốc (Original)

Thông Báo Mới Tất cả Cập Nhật Mới Nhất Quy Định Shopee Tính năng mới Cập Nhật Vận Chuyển Phương Thức Vận Chuyển Shopee Phân Bổ ĐVVC Tự Động Người Bán Kinh Nghiệm Shopee Captain Câu chuyện thành công Các Câu Hỏi Thường Gặp Về Thanh toán & Trả hàng Về Chương trình & Công cụ Về Tăng doanh thu Về Xử lý đơn hàng & Vận chuyển Về Quản lý Shop Về Đăng bán sản phẩm Tổng Quan Khởi động bán hàng Shopee Shopee - Certified SSP Shopee-Certified Enablers Sao Quả Tạ Quy Định Vận Hành Quy Định Đăng Bán Quy Định Chat Shopee Mall Quản Lý Shop Thông Tin Thị Trường Shopee Uni Bắt Đầu Bán Hàng Thiết Lập Shop Kênh Quản Lý Shop Tài Khoản Và Bảo Mật Trang Trí Shop Chế Độ Tạm Nghỉ Nền Tảng Tài Khoản Phụ Quản Lý Đơn Hàng Hướng Dẫn Kết Nối API Xử Lý Đơn Hàng Vận Chuyển Quản Lý Tồn Kho Quản Lý Sản Phẩm Đăng Bán Mới Đăng Bán Hàng Loạt Hàng Đặt Trước Mẹo Hay về Đăng Bán Kênh Marketing Chương trình Tăng Đơn Cùng KOL YouTube Shopping Shopee Video Tiếp thị liên kết Người bán Quảng cáo Ngoại sàn Tổng Quan về Shopee MKT Chương Trình Shopee Công Cụ Marketing Của Shop Shopee Live Dịch Vụ Hiển Thị Gói Dịch Vụ & Chương Trình Mẹo Tăng Doanh Thu Tài Chính Quản Lý Doanh Thu SEasy - Cho Vay Người Bán Quy Trình Thanh Toán Số dư TK Shopee Phân Loại Phí Dữ Liệu Phân Tích Dữ Liệu Bán Hàng Hiệu Quả Hoạt Động Phát Triển Bán Hàng Toàn Cầu Chủ Động Bán Hàng Toàn Cầu Shop Yêu Thích Chăm Sóc Khách Hàng Dịch Vụ CSKH Sự Hài Lòng của Người Mua Trả Hàng/ Hoàn Tiền Trả Hàng / Hoàn Tiền Quản Lý Đơn Hàng Hướng Dẫn Kết Nối API Hướng dẫn kết nối API 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 Mục lục bài viết

Điều Kiện Sử Dụng & Quy Trình Xét Duyệt Open API

Hướng Dẫn Đăng Ký Tài Khoản Open API

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

Liên kết

Xem thêm:

Sơ đồ

Liên kết ngược