Hướng dẫn tích hợp Instant Mart
Tài liệu này giới thiệu quy trình đăng sản phẩm, quản lý đơn hàng, báo cáo doanh thu và luồng tích hợp/kiểm thử OpenAPI trên Instant Mart.
Giới thiệu về dự án Instant Mart
Bối cảnh:
Instant Mart là cấu trúc shop đặc biệt được thiết kế để hỗ trợ các nhà bán lẻ vận hành cả quản lý trung tâm và hoạt động ở cấp chi nhánh. Theo mô hình này:
- Mỗi Mart Shop (Cửa hàng chính thức) hoạt động như trụ sở, chịu trách nhiệm quản lý SKU toàn cầu, tạo sản phẩm và xem báo cáo tài chính.
- Nhiều Outlet (Cửa hàng chi nhánh) tồn tại dưới mart, đại diện cho các địa điểm shop riêng lẻ. Outlet chịu trách nhiệm xử lý hoạt động hàng ngày như quản lý đơn hàng, duy trì tồn kho và đóng gói kiện hàng cho tài xế lấy hàng.
Với tích hợp Open API, nhà bán lẻ Mart có thể chọn quản lý SKU ở cấp merchant (dùng chung cho tất cả outlet) hoặc ở cấp outlet (độc lập cho từng chi nhánh).
Trước khi tích hợp với Open API, nhà bán lẻ phải onboard cả merchant mart và các shop outlet trong cổng BDC, đảm bảo chúng được đăng ký là Instant Mart Shops. Thiết lập này cho phép các nhà phát triển xây dựng giải pháp API hỗ trợ toàn bộ luồng hoạt động của nhà bán lẻ Instant Mart.
1. Thiết lập tài khoản kiểm thử Sandbox
1.1 Tạo tài khoản kiểm thử Sandbox
Bạn có thể bắt đầu bằng cách truy cập trang Tài khoản kiểm thử trên Shopee Open Platform Console > Chọn module Mart&Outlet shops để tạo shop kiểm thử.
Lưu ý: Kiểm thử sandbox Instant Mart yêu cầu whitelist hai bước: Sandbox V2 phải được bật trước danh sách whitelist Mart & Outlet Shop.
2. Cấp ủy quyền
2.1 Ủy quyền shop
Tìm Partner_id kiểm thử trên trang App List:
Nhấp Authorize → đăng nhập bằng tài khoản Mart để hoàn tất ủy quyền cho cả Mart và Outlet shop cùng lúc.
Tham khảo bài viết Ủy quyền và xác thực để biết thêm thông tin.
3. Quy trình kiểm thử
3.1 Kiểm thử Open API
Sử dụng Công cụ kiểm thử API hoặc Postman để kiểm thử Open API.
3.2 Các chức năng Open API chính
Các chức năng API chính cần thiết cho dự án ID Mart:
| Phần | Phần phụ |
| Sản phẩm | Chuẩn bị cho SKU mới |
| Tạo SKU mới | |
| Cập nhật SKU hiện có | |
| Tạo biến thể SKU | |
| Quản lý tồn kho & giá | |
| Quản lý SKU chung | |
| Đơn hàng | Lấy danh sách & chi tiết đơn hàng |
| Hủy đơn hàng | |
| Yêu cầu vận chuyển | |
| Tạo mã theo dõi | |
| Tạo vận đơn | |
| Trả hàng & Hoàn tiền | Lấy danh sách & chi tiết trả hàng |
| Chấp nhận trả hàng/hoàn tiền | |
| Tranh chấp trả hàng/hoàn tiền | |
| Tài chính | Lấy chi tiết escrow |
| Lấy giao dịch ví | |
| Tạo báo cáo doanh thu | |
| Tạo báo cáo thu nhập | |
| Cài đặt shop | Cập nhật hồ sơ shop |
| Giờ hoạt động shop |
3.2.1 Quan hệ giữa Mart & Outlet shop
Kiểm tra quan hệ: v2.shop.get_shop_info
Với mart_shop_id → trả về tất cả outlet shop ID dưới Mart.
Với outlet_shop_id → trả về mart shop ID tương ứng.
3.2.1.1 Sử dụng v2.shop.get_shop_info với Mart Shop
Khi gọi v2.shop.get_shop_info với mart_shop_id, nó sẽ trả về danh sách tất cả Outlet shop ID dưới mart shop đó.
Ví dụ phản hồi:
{
"auth_time": 1755082218,
"error": "",
"expire_time": 1786636799,
"is_cb": false,
"is_direct_shop": false,
"is_main_shop": false,
"is_mart_shop": true,
"is_one_awb": false,
"is_outlet_shop": false,
"is_sip": false,
"is_upgraded_cbsc": false,
"linked_direct_shop_list": [],
"linked_main_shop_id": 0,
"merchant_id": null,
"message": "",
"outlet_shop_info_list": [
\{
"outlet\_shop\_id": 225622030
\},
\{
"outlet\_shop\_id": 225622031
\},
\{
"outlet\_shop\_id": 225622032
\},
\{
"outlet\_shop\_id": 225622033
\},
\{
"outlet\_shop\_id": 225622034
\}
],
"region": "TH",
"request_id": "e3e3e7f33c4e6283bc127a54263d8c01",
"shop_fulfillment_flag": "Others",
"shop_name": "op_64564962416254514c64",
"status": "NORMAL"
}
3.2.1.2 Sử dụng v2.shop.get_shop_info với Outlet Shop
Khi gọi v2.shop.get_shop_info với outlet_shop_id, nó sẽ trả về mart shop ID tương ứng.
Ví dụ phản hồi:
{
"auth_time": 1755158035,
"error": "",
"expire_time": 1786723199,
"is_cb": false,
"is_direct_shop": false,
"is_main_shop": false,
"is_mart_shop": false,
"is_one_awb": false,
"is_outlet_shop": true,
"is_sip": false,
"is_upgraded_cbsc": false,
"linked_direct_shop_list": [],
"linked_main_shop_id": 0,
"mart_shop_id": 225621997,
"merchant_id": null,
"message": "",
"region": "TH",
"request_id": "e3e3e7f33c4e97dc9f31cfda55db5101",
"shop_fulfillment_flag": "Others",
"shop_name": "op_51505343495178456857",
"status": "NORMAL"
}
3.2.2 Quản lý sản phẩm
Các trường phân biệt giữa Mart SKU và Outlet SKU
| Module | Trường | Quản lý MART SKU | Quản lý Outlet SKU |
| Thông tin cơ bản | title | Có | Không |
| video | Có | Không | |
| image | Có | Không | |
| status | Có | Có | |
| category | Có | Không | |
| Thông số kỹ thuật | brand | Có | Không |
| attribute | Có | Không | |
| size chart | Có | Không | |
| Thông số kỹ thuật | variation name | Có | Không |
| variation option | Có | Không | |
| variation image | Có | Không | |
| price | Không | Có | |
| purchase limit | Không | Có | |
| wholesales | Không | Có | |
| stock | Không | Có | |
| model status | Có | Có | |
| module seller SKU | Có | Không | |
| weight | Có | Không | |
| dimension | Có | Không | |
| Vận chuyển | logistics channel | Không | Có |
| installation channel | Không | Có | |
| Khác | DTS | Không | Có |
| seller SKU | Có | Không | |
| condition | Có | Không |
Các thao tác chính bao gồm:
- Thêm Mart SKU → v2.product.add_item
- Cập nhật tồn kho/giá SKU → v2.product.update_stock, v2.product.update_price (chỉ ở cấp outlet)
- Xuất bản Outlet SKU → v2.product.publish_item_to_outlet_shop
- Đồng bộ Mart SKU lên Outlet SKU → v2.product.update_item
3.2.2.1 Thêm Mart SKU
Thêm mart SKU bằng cách gọi v2.product.add_item sử dụng mart shop_id.
Tham khảo bài viết Tạo sản phẩm để biết thêm thông tin.
Ví dụ lệnh gọi:
{
"original\_price": 123.3,
"description": "rachel add item from openapi 002",
"weight": 1.1,
"item\_name": "rachel add item from openapi item 001",
"item\_status": "NORMAL",
"dimension": \{
"package\_height": 2,
"package\_length": 3,
"package\_width": 4
\},
"category\_id": 400091,
"logistic\_info": [\{
"size\_id": 0,
"shipping\_fee": 2.5,
"enabled": true,
"logistic\_id": 80018,
"is\_free": false
\},
\{
"size\_id": 0,
"shipping\_fee": 2.5,
"enabled": true,
"logistic\_id": 81014,
"is\_free": false
\}],
"image": \{
"image\_id\_list": ["c54265d475b85e00ffb2404585e32b6f", "6fb33d484f232510b5f9b169f2758322", "591ab15ea954b9879374765854595600", "00a2258551b5a2f0a7c283f877330f93", "abf02b19b42e4aa964ef0725491ca9e3", "730f45972377cd4eb9813c6e53e60e9a"]
\},
"pre\_order": \{
"is\_pre\_order": false,
"days\_to\_ship": 2
\},
"item\_sku": "item sku 001",
"condition": "NEW",
"brand": \{
"brand\_id": 0,
"original\_brand\_name": "no brand"
\},
"item\_dangerous": 0,
"description\_info": \{
"extended\_description": \{
"field\_list": [\{
"field\_type": "text",
"text": "rachel add item from openapi 001",
"image\_info": \{
"image\_id": "-"
\}
\},
\{
"field\_type": "image",
"text": "-",
"image\_info": \{
"image\_id": "c54265d475b85e00ffb2404585e32b6f"
\}
\}]
\}
\},
"description\_type": "extended",
"seller\_stock": [\{
"location\_id": "IDZ",
"stock": 555
\}]
}
3.2.2.2 Cập nhật tồn kho/giá Mart SKU
Cập nhật tồn kho và giá Mart SKU bằng cách gọi v2.product.update_stock hoặc v2.product.update_price.
Tham khảo bài viết Quản lý tồn kho & giá để biết thêm thông tin.
Lưu ý: Tồn kho và giá chỉ có thể được quản lý ở cấp outlet shop. Bạn phải cung cấp shop_id của outlet shop khi gọi API để cập nhật tồn kho hoặc giá.
3.2.2.3 Xuất bản Outlet SKU
Gọi v2.product.publish_item_to_outlet_shop để xuất bản outlet SKU.
Ví dụ lệnh gọi:
{
"mart_item_id": 1234,
"outlet_shop_id": 2345,
"publish_item": {
"model": [
\{
"relate\_mart\_model\_id": 1234,
"original\_price": 123,
"seller\_stock": [
\{
"location\_id": "IDZ",
"stock": 100
\}
],
"pre\_order": \{
"is\_pre\_order": false,
"days\_to\_ship": 3
\}
\}
],
"logistic\_info": [
\{
"logistic\_id": 12345,
"enabled": true,
"shipping\_fee": 3.45,
"size\_id": 0,
"is\_free": false
\}
]
}
}
Gọi v2.product.get_item_base_info để kiểm tra xem thông tin outlet item có đồng bộ đúng không.
Tham khảo bài viết Quản lý thông tin cơ bản sản phẩm để kiểm tra thông tin sản phẩm.
3.2.2.4 Lấy thông tin ánh xạ sản phẩm
Khi mart SKU có outlet SKU đã xuất bản, gọi v2.get_mart_item_mapping_by_id để lấy thông tin ánh xạ sản phẩm.
Ví dụ lệnh gọi:
{
"mart_item_id": 844087076,
"outlet_shop_id_list": [
225034791
]
}
3.2.2.5 Đồng bộ Mart SKU lên Outlet SKU
Đồng bộ trường mart sku lên outlet sku.
-
Gọi v2.product.update_item để cập nhật trường mart item.
-
Gọi v2.product.get_item_base_info / vào seller center outlet để kiểm tra thông tin outlet item có đồng bộ đúng không.
Lưu ý: Chỉ các trường được quản lý bởi mart sku mới có thể đồng bộ lên outlet sku.
3.2.3 Phụ thuộc kênh Instant tại ID
3.2.3.1 Tổng quan cấu trúc kênh
| Kênh Mask | Kênh Logistics |
| 8000 - Instant | 80012 - GoSend Instant 80019 - GrabExpress Instant 80044 - SPX Instant |
| 8008 - Instant 2 giờ | 80054 - SPX Instant - 2 Jam80061- GrabExpress Instant - 2 Jam80063- GoSend Instant - 2 Jam |
| 8007 - Instant 4 giờ | 80053 -SPX Instant - 4 Jam80062- GrabExpress Instant - 4 Jam80064-GoSend Instant - 4 Jam |
*Nhà phát triển cần biết rằng người bán được whitelist riêng cho các kênh này.
3.2.3.2 Tóm tắt giới hạn về kênh Instant tại ID
Instant 2 giờ (8008) và Instant 4 giờ (8007) phải luôn được bật/tắt cùng nhau.
| Trường hợp | Điều kiện hiện tại | Hành động | Lỗi |
| 1 | 8000 Instant: BẬT - 80044 SPX Instant: BẬT - 80012 GoSend Instant: TẮT - 80019 GrabExpress Instant: TẮT 8008 Instant 2 giờ: TẮT - 80054- SPX Instant - 2 Jam: TẮT - 80061-GrabExpress Instant - 2 Jam:TẮT - 80063-GoSend Instant - 2 Jam:TẮT 8007 Instant 4 giờ: TẮT - 80053-SPX Instant - 4 Jam: TẮT - 80062-GrabExpress Instant - 4 Jam: TẮT - 80064-Gosend Instant - 4 Jam: TẮT | Tắt 80044 | SPX Instant không thể tắt. Vui lòng bật ít nhất 1 kênh sau: {GoSend Instant, GrabExpress Instant, SPX Instant - 2 Jam, GrabExpress Instant - 2 Jam,GoSend Instant - 2 Jam,SPX Instant - 4 Jam,GrabExpress Instant - 4 Jam,GoSend Instant - 4 Jam} |
| 2 | 8000 Instant: TẮT - 80044 SPX Instant: TẮT - 80012 GoSend Instant: TẮT - 80019 GrabExpress Instant: TẮT 8008 Instant 2 giờ: BẬT - 80054- SPX Instant - 2 Jam: BẬT - 80061-GrabExpress Instant - 2 Jam:TẮT - 80063-GoSend Instant - 2 Jam:TẮT 8007 Instant 4 giờ: BẬT - 80053- SPX Instant - 4 Jam: BẬT - 80062-GrabExpress Instant - 4 Jam: TẮT - 80064-Gosend Instant - 4 Jam: TẮT | Tắt 80054 | Kênh SPX Instant - 2 Jam không thể tắt. Vui lòng bật ít nhất 1 kênh sau. {SPX Instant, GoSend Instant, GrabExpress Instant, GrabExpress Instant - 2 Jam, GrabExpress Instant - 4 Jam, GoSend Instant - 2 Jam, GoSend Instant - 4 Jam} |
| 3 | 8000 Instant: TẮT - 80044 SPX Instant: TẮT - 80012 GoSend Instant: TẮT - 80019 GrabExpress Instant: TẮT 8008 Instant 2 giờ: BẬT - 80054-SPX Instant - 2 Jam : BẬT - 80061-GrabExpress Instant - 2 Jam:TẮT - 80063-GoSend Instant - 2 Jam:TẮT 8007 Instant 4 giờ: BẬT - 80053-SPX Instant - 4 Jam: BẬT - 80062-GrabExpress Instant - 4 Jam: TẮT - 80064-Gosend Instant - 4 Jam: TẮT | Tắt 80053 | Kênh SPX Instant - 4 Jam không thể tắt. Vui lòng bật ít nhất 1 kênh sau. {SPX Instant, GoSend Instant, GrabExpress Instant, GrabExpress Instant - 2 Jam, GrabExpress Instant - 4 Jam, GoSend Instant - 2 Jam, GoSend Instant - 4 Jam,SPX Instant - 2 Jam} |
| 4 | Người bán chỉ được whitelist cho kênh trong 8000 Instant 8000 Instant: BẬT - 80044 SPX Instant: BẬT - 80012 GoSend Instant: TẮT - 80019 GrabExpress Instant: TẮT | Tắt 80044 | Kênh SPX Instant không thể tắt. Vui lòng bật các kênh sau. GoSend Instant, GrabExpress Instant |
3.2.4 Phụ thuộc kênh Instant tại TH
3.2.4.1 Tổng quan cấu trúc kênh
| Kênh Mask | Kênh Logistics |
| 0 | 70124-Instant Delivery - ส่งทันที (แพ็ก 30 นาที) |
| 0 | 70125-Instant Delivery - ส่งทันที (แพ็ก 10 นาทีจากสาขา) |
3.2.5 Phụ thuộc kênh Instant tại VN
3.2.5.1 Tổng quan cấu trúc kênh
| Kênh Mask | Kênh Logistics |
| 5115 | 50040-SPX Instant - Hỏa Tốc - Ưu Tiên |
3.2.6 Quản lý đơn hàng
Để tạo đơn hàng kiểm thử, truy cập trang Đơn hàng kiểm thử trên Shopee Open Platform Console và chọn Tạo đơn hàng kiểm thử.
Chọn shop, sản phẩm và tùy chọn vận chuyển, sau đó nhấp Tạo để tạo đơn hàng.
Thông tin đơn hàng bao gồm Order SN, Item ID, Trạng thái, Thời gian cập nhật và Shop ID. Bạn cũng có thể lấy hàng, giao hàng hoặc xóa đơn hàng từ trang này.
Tham khảo bài viết Quản lý đơn hàng để biết thêm thông tin về các bước tiếp theo.
3.2.7 Quản lý trả hàng & hoàn tiền
Tham khảo bài viết Quản lý trả hàng & hoàn tiền để biết thêm thông tin.
3.2.8 Tài chính: Lấy doanh thu và giao dịch ví
Bạn có thể tạo và truy xuất báo cáo thu nhập, báo cáo doanh thu hoặc giao dịch ví bằng cách gọi các API với mart shop_id. Khi sử dụng mart shop_id, phản hồi sẽ trả về tài liệu tổng hợp bao gồm tất cả outlet shop dưới mart shop.
| Chức năng | Open API | Ghi chú |
| Tạo báo cáo doanh thu | v2.payment.generate_income_report | Tham số yêu cầu: release_time_from và release_time_to. |
| Lấy báo cáo doanh thu | v2.payment.get_income_report | Để truy vấn trạng thái báo cáo doanh thu và cung cấp liên kết tệp bằng cách truyền income_report_id. |
| Tạo báo cáo thu nhập | v2.payment.generate_income_statement | Tham số yêu cầu: statement_type=1 nghĩa là báo cáo theo tuần; statement_type=2 nghĩa là báo cáo theo tháng |
| Lấy báo cáo thu nhập | v2.payment.get_income_statement | Để truy vấn trạng thái báo cáo thu nhập và cung cấp liên kết tệp bằng cách truyền income_statement_id |
| Lấy giao dịch ví | v2.payment.get_wallet_transaction_list | Lấy lịch sử giao dịch của ví. |
3.2.9 Cài đặt shop
- Bạn có thể cập nhật tên shop, logo và mô tả bằng cách gọi v2.shop.update_profile.
- Bạn có thể cập nhật giờ hoạt động bằng cách gọi v2.logistics.update_operating_hours.
Lưu ý:
- Các giá trị cung cấp phải tuân theo các hạn chế được lấy từ v2.logistics.get_operating_hour_restrictions.
- API này thực hiện cập nhật ghi đè. Khi cập nhật giờ hoạt động lấy hàng, bạn phải bao gồm tất cả các đoạn, kể cả những đoạn không thay đổi.
4.
Cơ chế push là từ điển các thông báo hệ thống từ Shopee, bao gồm cập nhật về sản phẩm, đơn hàng, trả hàng, marketing, ổn định và cập nhật thị trường chung.
Đối với Instant Mart, chúng tôi khuyến nghị kết nối với order_status_push. Để biết thêm chi tiết, vui lòng tham khảo bài viết order_status_push.
5. FAQ & Hỗ trợ
Để biết các câu hỏi thường gặp, vui lòng tham khảo FAQ.
Nếu bạn gặp bất kỳ vấn đề nào liên quan đến Instant Mart API (ví dụ: onboarding, cấu hình kênh logistics, đồng bộ đơn hàng, v.v.), vui lòng gửi ticket đến nhóm hỗ trợ sản phẩm Shopee tại đây.
Khi gửi ticket, vui lòng chọn: L1 Question Category → Instant Mart
Chọn đúng danh mục giúp chúng tôi xác định và ưu tiên yêu cầu của bạn hiệu quả hơn.