API Báo Giá (Logistics Người Bán)
Kênh Logistics Người Bán là gì
Kênh này cho phép người bán sử dụng logistics của riêng mình để báo giá và giao đơn hàng.
- Báo giá vận chuyển được thực hiện từ URL báo giá do người bán cung cấp.
- Giá vận chuyển và thời gian giao hàng do người bán tự cung cấp.
- Việc theo dõi đơn hàng được đơn giản hóa, người bán chịu trách nhiệm gửi các sự kiện "đã giao hàng", "đã nhận hàng" hoặc "giao hàng thất bại" qua OpenAPI.
Lưu ý: Kênh này sẽ được cung cấp cho các người bán cụ thể, những sản phẩm không được hỗ trợ bởi logistics của Shopee do kích thước và trọng lượng, theo quy định của đội thương mại Shopee.
URL Báo Giá Vận Chuyển
Là công cụ cho phép người bán gửi cho Shopee chi phí vận chuyển ước tính và thời gian giao hàng sẽ hiển thị cho người mua tại thời điểm mua hàng. Để người bán có thể sử dụng tính năng này, cần đáp ứng các yêu cầu đồng nhất được thiết lập trước.
*Người bán có thể tích hợp trực tiếp với Shopee để kết nối URL báo giá hoặc kết nối qua Integrator-HUB.
Yêu cầu đồng nhất/Tích hợp
Khác với các loại tích hợp khác, việc tích hợp API báo giá và cập nhật trạng thái đơn hàng (của kênh seller logistics) yêu cầu đánh giá và phê duyệt từ đội Shopee trước khi bắt đầu hoạt động. Để được đội Shopee phê duyệt cần:
-
Tuân thủ hợp đồng API báo giá vận chuyển:
-
Cấu hình và cung cấp URL qua phương thức HTTP POST.
-
Mỗi yêu cầu (request) chỉ chứa một mặt hàng của một người bán.
-
URL không có cấu trúc cụ thể, mang lại sự linh hoạt trong cấu hình.
-
Payload tiêu chuẩn cho yêu cầu và phản hồi báo giá (và xác thực với URL của Shopee)
-
Thời gian phản hồi tối đa 400ms.
-
Bảng dự phòng được đăng ký trực tiếp qua Seller Center.
-
Giám sát lỗi (và phát triển các thông báo được yêu cầu)
-
Phát triển API cập nhật trạng thái ("update_tracking_status");
-
Lưu ý: Các yêu cầu trên phải được đáp ứng bởi "hệ thống riêng" của người bán hoặc bởi ERP/HUB/Tích hợp của họ. Cần lưu ý rằng nếu không có chúng, các đơn hàng sẽ bị hủy vì quy trình không thể thực hiện thủ công qua Seller Center.
-
Lưu ý 2: Tất cả những ai phát triển API báo giá cũng phải phát triển API cập nhật trạng thái;
-
Lưu ý 3: APP Seller Logistics chỉ được dùng cho URL báo giá; để sử dụng bất kỳ API nào khác cần tạo APP thứ hai;
-
Gửi email xác nhận và phê duyệt từ đội Shopee qua ticket (bao gồm tất cả các tiêu chí trên).
Để có thể thực hiện tích hợp và kiểm tra trên, cũng cần:
a) Tạo APP Seller Logistic mới trên Open Platform và ủy quyền người bán cho APP đó
b) Có một APP có khả năng gọi OpenAPI để cập nhật trạng thái (và cũng ủy quyền người bán cho APP đó)
Sau khi hoàn thành tất cả các bước này, cần tạo ít nhất 2 đơn hàng thử nghiệm, cần được dẫn đến trạng thái đã giao và đã hủy, để xác nhận HUB là kênh được phê duyệt.
Tạo APP Seller Logistics và ủy quyền người bán
Sau khi tài khoản Open Platform của bạn đã hoạt động, bước tiếp theo là tạo APP chỉ dùng để kết nối URL báo giá của bạn với Shopee và các người bán tương ứng (shop_id).
Các bước thực hiện như sau:
- Đăng nhập vào Open Platform và vào tab "Console":
- Trong "App List", nhấp vào "+ Add new APP":
- Chọn "App Category" là "Seller Logistics":
- Nhập trong "App Description" các URL sẽ được dùng trong Live (production) và Test (môi trường thử nghiệm), rồi nhấp "Submit".
*Không sao nếu chỉ có một URL;
- APP đã được tạo. Tiếp theo chỉ cần thực hiện yêu cầu "Go-Live", sẽ cung cấp APP trong môi trường production trong vòng 24 giờ.
- Cần điền thêm một số thông tin trước.
Nếu không thể cung cấp "username" và "password", có thể điền như hình dưới:
- Đối với "App IP", nhập IP chính của ứng dụng của bạn (lưu ý rằng chúng tôi sẽ không giới hạn truy cập chỉ với IP này).
Đối với "Other IT Assets Declaration", điền như hình dưới.
24 giờ sau khi yêu cầu "Go-live", partner_id Live sẽ được cấp và bạn sẽ được thông báo qua email. Sau khi nhận email, các bước tiếp theo là:
1 - Mở ticket trên Nền tảng Ticket OP, với tiêu đề "Seller Logistics" cho biết shop_id (hoặc các Shop ID) bạn muốn kết nối với URL của mình. Sau khi nhận yêu cầu và đội Shopee hoàn thành kết nối URL, sẽ cho phép tiến hành ủy quyền người bán.
Lưu ý: mỗi shop_id chỉ có thể được kết nối với một URL trên Shopee;
2 - Thực hiện quy trình ủy quyền cho người bán của bạn, theo hướng dẫn tại đường dẫn này (đến mục 4 của "Ủy quyền với tài khoản shop").
3 - Sau khi đội Shopee trả lời ticket của bạn xác nhận cấu hình đã hoàn tất và người bán của bạn thực hiện quy trình ủy quyền, bạn có thể bắt đầu thực hiện các bài kiểm tra đầu tiên trong môi trường LIVE.
Payload tiêu chuẩn cho yêu cầu và phản hồi báo giá
Tham số yêu cầu (query)
URL Request Parameters:
| - | Ví dụ | Địa chỉ HTTP |
|---|---|---|
| URL | https://api.frete/ | URL do ERP hoặc người bán cung cấp |
| Tên | Kiểu | Ví dụ | Mô tả |
|---|---|---|---|
| partner_id | int | 1 | ID đối tác được cấp sau khi đăng ký thành công. Bắt buộc cho tất cả các yêu cầu. |
| timestamp | timestamp | 1610000000 | Cho biết timestamp của yêu cầu. Bắt buộc cho tất cả các yêu cầu. Hết hạn sau 5 phút. |
| sign | string | e318d3e932719916a9f9ebb57e2011961 bd47abfa54a36e040d050d8931596e2 | Chữ ký được tạo từ chuỗi cơ sở "{}{}{}"%(parnter_id, api full path, timestamp) và partner_key qua thuật toán HMAC-SHA256. Chi tiết: https://open.shopee.com/documents?module=87&type=2&id=58&version=2 |
Body Request Parameters:
| Tên | Kiểu | Bắt buộc | Ví dụ | Mô tả | ||
|---|---|---|---|---|---|---|
| shop_id | int | True | 112345678 | Mã định danh duy nhất của mỗi người bán | ||
| origin_zip_code | string | True | 12345000 | CEP của người bán gồm 8 chữ số, chỉ số, không có dấu chấm và gạch ngang | ||
| destination_zip_code | string | True | 12345000 | CEP của người mua gồm 8 chữ số, chỉ số, không có dấu chấm và gạch ngang | ||
| items | array | True | - | Danh sách sản phẩm | ||
| item_id | int | True | 12345678 | Mã định danh mặt hàng trên Shopee | ||
| sku | string | False | item_sku | SKU do người bán đăng ký trên Shopee | ||
| model_id | int | False | 12345678 | Mã định danh model đăng ký trên Shopee. Lưu ý: trong báo giá PDP, model_id và category_id được gửi là 0, nhưng trên trang checkout được gửi bình thường. | ||
| category_id | int | True | 12345678 | Danh mục mặt hàng đăng ký trên Shopee. Lưu ý: trong báo giá PDP, model_id và category_id được gửi là 0, nhưng trên trang checkout được gửi bình thường. | ||
| quantity | int | True | 12345678 | Số lượng mặt hàng | ||
| price | float | False | 150.4 | Giá sản phẩm | ||
| dimensions | object | True | - | Kích thước sản phẩm | ||
| length | int | True | 10 | Chiều dài tính bằng centimét | ||
| width | int | True | 10 | Chiều rộng tính bằng centimét | ||
| height | int | True | 10 | Chiều cao tính bằng centimét | ||
| weight | int | True | 100 | Trọng lượng tính bằng gram |
Response Parameters / Phản hồi Báo giá (lỗi):
| Tên | Kiểu | Bắt buộc | Ví dụ | Mô tả |
|---|---|---|---|---|
| error | string | True | - | Mã định danh báo giá do người bán thực hiện |
| message | string | True | - | CEP của người mua |
| request_id | string | True | - | Mã định danh lần gọi API |
Response Parameters / Phản hồi Báo giá (thành công):
| Tên | Kiểu | Bắt buộc | Ví dụ | Mô tả | |||
|---|---|---|---|---|---|---|---|
| quotation_id | int | True | 091234000 | Mã định danh báo giá do người bán thực hiện | |||
| destination_zip_code | string | True | 091234000 | CEP của người mua | |||
| packages | array | True | - | Danh sách gói hàng | |||
| dimensions | object | True | - | Kích thước sản phẩm | |||
| length | int | True | 10 | Chiều dài tính bằng centimét | |||
| width | int | True | 10 | Chiều rộng tính bằng centimét | |||
| height | int | True | 10 | Chiều cao tính bằng centimét | |||
| weight | int | True | 100 | Trọng lượng tính bằng gram | |||
| items | array | True | - | Danh sách sản phẩm | |||
| item_id | int | True | 12345678 | Mã định danh mặt hàng trên Shopee | |||
| sku | string | False | sku_item | SKU do người bán đăng ký trên Shopee | |||
| model_id | int | False | 12345678 | Mã định danh model đăng ký trên Shopee | |||
| category_id | int | False | 12345678 | Danh mục mặt hàng đăng ký trên Shopee | |||
| quantity_id | int | True | 2 | Số lượng mặt hàng | |||
| price | int | True | 150.4 | Giá sản phẩm | |||
| dimensions | object | True | - | Kích thước sản phẩm | |||
| length | int | True | 10 | Chiều dài tính bằng centimét | |||
| width | int | True | 10 | Chiều rộng tính bằng centimét | |||
| height | int | True | 10 | Chiều cao tính bằng centimét | |||
| weight | int | True | 100 | Trọng lượng tính bằng gram | |||
| quotations | array | True | - | Danh sách báo giá vận chuyển | |||
| price | float | True | 150.4 | Giá vận chuyển hiển thị cho người mua | |||
| handling_time | int | True | 20 | Thời gian chuẩn bị đơn hàng tính bằng ngày làm việc. Phải luôn lớn hơn hoặc bằng 1. Thời gian này giới hạn thời gian xuất hóa đơn và sắp xếp giao hàng của người bán. | |||
| shipping_time | int | True | 10 | Thời gian vận chuyển đơn hàng tính bằng ngày làm việc | |||
| promise_time | int | True | 30 | Tổng thời gian chuẩn bị + thời gian vận chuyển | |||
| service_code | string | True | M1020 | Mã xác định đơn vị vận chuyển trong ngữ cảnh của người bán (mã sẽ được trả về trong tham số "shipping_carrier" của API get_order_detail, ví dụ: "Logística do Vendedor - M1020".) |
Ví dụ yêu cầu
cURL
curl --location 'https://api.frete/?partner_id=123456&sign=6b664c45535a544455524f6b565776706752784455784978574361444e795a4c×tamp=1709843385' \
--header 'Content-Type: application/json' \
--data '{
"shop_id": 601216389,
"origin_zip_code": "87952525",
"destination_zip_code": "17036785",
"items": [
{
"item_id": 892569034,
"model_id": 1,
"sku": "",
"category_id": 1,
"quantity": 1,
"price": 12.5,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 150
}
}
]
}'
Ví dụ phản hồi (thành công)
- Sử dụng HTTP status code 200
Json
{
"quotation_id": 1709843321,
"destination_zip_code": "17036785",
"packages": [
{
"dimensions": {
"length": 35,
"width": 90,
"height": 114,
"weight": 27300
},
"items": [
{
"item_id": 892569034,
"model_id": 1,
"sku": "",
"category_id": 1,
"quantity": 1,
"price": 12.5,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 150
}
}
],
"quotations": [
{
"price": 93.55,
"handling_time": 1,
"shipping_time": 7,
"promise_time": 8,
"service_code": "50"
}
]
}
]
}
Ví dụ phản hồi (lỗi)
- Sử dụng HTTP status code 403
Json
{
"request_id": "Id da requisição",
"error": "coluna Error",
"message": "coluna Message"
}
Phản hồi mặc định cho các lỗi không được ánh xạ trong bảng lỗi
- Sử dụng HTTP status code 500
Json
{
"request_id": "65e9e26dd9d2565e9e26dd9d64",
"error": "Internal system error",
"message": "internal system error"
}
Mã phản hồi dự kiến
| HTTP status code | Error | Message | Kích hoạt dự phòng |
|---|---|---|---|
| 200 | success API call, error Empty | success API call, error Empty | False |
| 403 | error_partner_id | there is no partner_id in query | False |
| 403 | error_partner_id | partner_id is invalid | False |
| 403 | error_ sign | there is no sign in query | False |
| 403 | error_ sign | your sign is invalid | False |
| 403 | error_timestamp | there is no timestamp in query | False |
| 403 | error_timestamp | your timestamp is invalid | False |
| 403 | error_ shop_id | there is no shop_id in body | False |
| 403 | error_ shop_id | The shop_id is invalid | False |
| 403 | Invalid origin_zip_code | The origin_zip_code is invalid | False |
| 403 | invalid destination_zip_code | The destination_zip_code is invalid | False |
| 403 | error_destination_zip_code | No shipping channel is available. | False |
| 403 | Invalid item_id | The item_id is invalid | False |
| 403 | Invalid model_id | The model_id is invalid | False |
| 403 | Invalid sku | The sku is not valid | False |
| 403 | invalid category_id | The category_id is invalid | False |
| 403 | invalid quantity | The quantity is invalid | False |
| 403 | invalid price | The price is invalid | False |
| 403 | error_dimensions | The dimensions is invalid | False |
| 403 | error_length | The length is invalid | False |
| 403 | error_width | The width is invalid | False |
| 403 | error_height | The height is invalid | False |
| 403 | error_weight | The weight is invalid | False |
| 500 | Internal system error | internal system error | True |
Xác thực phản hồi (với URL của Shopee)
- Để đảm bảo phản hồi đúng định dạng mong đợi, chúng tôi có URL để xác thực và thông báo các chỉnh sửa cần thiết.
- URL: "https://seller-quotation-api.uat.shps-br-services.com/validate\_quotation\_endpoint"
- Tham số "x-quotation-id" được dùng để chèn URL sẽ được đăng ký trên Shopee.
- Ví dụ payload sử dụng URL xác thực định dạng phản hồi:
Json
curl --location 'https://seller-quotation-api.uat.shps-br-services.com/validate_quotation_endpoint' \
--header 'api-key: 8a50d1d005d0649b5bdd9b13f0e871e0bd6439bd8e146577a6d51935a5ccea7c' \
--header 'x-partner-id: 2007416' \
--header 'x-quotation-api-url: https://api.cotação/shopee' \
--header 'x-sign: 658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53' \
--header 'Content-Type: application/json' \
--data '{
"shop_id": 549724933,
"origin_zip_code": "16200850",
"destination_zip_code": "16200850",
"items": [
{
"item_id": 10010394,
"sku": "10010394",
"model_id": 1,
"category_id": 1,
"quantity": 1,
"price": 277.67,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 10
}
}
]
}'
- Phản hồi không có lỗi (có thể nhận biết khi tham số "validation_errors" trống ("validation_errors:[]"):
Json
{
"validation_errors": [],
"details": {
"called_api": "https://api.cotação/shopee",
"with_params": {
"sign": "658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53",
"partner_id": 2007416,
"timestamp": 1713445311
},
"with_body": {
"shop_id": 549724933,
"origin_zip_code": "16200850",
"destination_zip_code": "16200850",
"items": [
{
"item_id": 10010394,
"model_id": 1,
"sku": "10010394",
"category_id": 1,
"quantity": 1,
"price": 277.67,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 10
}
}
]
},
"response_from_quotation_api": {
"status_code": 200,
"response_body": {
"quotation_id": 617788888,
"destination_zip_code": "16200850",
"packages": [
{
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 10
},
"items": [
{
"item_id": 10010394,
"sku": "10010394",
"model_id": 1,
"category_id": 1,
"quantity": 1,
"price": 277.67,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 10
}
}
],
"quotations": [
{
"price": 34.9,
"handling_time": 5,
"shipping_time": 10,
"promise_time": 20,
"service_code": "2018605604"
}
]
}
]
},
"method_called": "POST"
}
}
}
- Phản hồi ví dụ với các lỗi cần sửa:
Json
{
"validation_errors": "Input should be a valid string: ('error',)",
"details": {
"called_api": "https://api.cotação/shopee": {
"sign": "658ABD0FD8D8525C0A87B0E360A5C518C2987E5B4A3D20542A4B11594E11CE53",
"partner_id": 2007416,
"timestamp": 1713472133
},
"with_body": {
"shop_id": 549724933,
"origin_zip_code": "16200850",
"destination_zip_code": "16200850",
"items": [
{
"item_id": 10010394,
"model_id": 0,
"sku": "10010394",
"category_id": 1,
"quantity": 1,
"price": 277.67,
"dimensions": {
"length": 1,
"width": 1,
"height": 1,
"weight": 10
}
}
]
},
"response_from_quotation_api": {
"status_code": 403,
"response_body": {
"request_id": "17134721330005",
"error": 403,
"message": "there is no partner_id in query",
"msger": "Nao foi possivel concluir sua solicitacao."
},
"method_called": "POST"
}
}
}
Thời gian phản hồi tối đa (của báo giá)
- Vì checkout là thời điểm quan trọng nhất trong trải nghiệm người dùng khi mua hàng, điều cần thiết là đảm bảo trải nghiệm tốt nhất cho người mua.
- Thời gian phản hồi tối đa là 1 giây. Cần thực hiện kiểm tra tải để đảm bảo đáp ứng yêu cầu này.
- Thời gian phản hồi vượt quá 1 giây sẽ không được chấp nhận, làm cho việc tích hợp không khả thi. Do đó, duy trì tối ưu tham số này là yếu tố quan trọng để mang lại trải nghiệm tốt nhất cho người mua.
Bảng dự phòng
- Tài nguyên này nhằm hỗ trợ tính toán phí vận chuyển trong trường hợp có sự cố trong quá trình báo giá qua API (timeout hoặc trả về 500 cho các yêu cầu).
Cấu hình giá trị vận chuyển cho dự phòng
- Để dự phòng hoạt động, người bán cần đăng ký giá trị vận chuyển và bật kênh Logistics Người bán theo các bước mô tả dưới đây.
- Trong Seller Center, vào Cài đặt Vận chuyển và nhấp vào nút Cấu hình kênh:
Điền giá trị vận chuyển dự phòng
Sau đó, màn hình điền giá trị vận chuyển sẽ được tải. Giá trị vận chuyển có thể được điền theo tỉnh thành (giá trị duy nhất) hoặc theo địa phương.
Giá trị vận chuyển duy nhất theo tỉnh
- Chọn các tỉnh
- Điền vào trường giá trị vận chuyển
- Nhấp Lưu
Giá trị vận chuyển duy nhất theo thành phố
- Chọn các tỉnh
- Tắt nút Flat rate for this area
- Bỏ chọn Select All Cities và chọn các thành phố bạn muốn nhập giá trị vận chuyển
- Điền vào trường Rate của các thành phố tương ứng
- Nhấp Lưu
Bật kênh Logistics Người bán
Thời hạn giao hàng cho giá trị vận chuyển dự phòng
-
Thời hạn giao hàng sẽ cố định khi bảng dự phòng được kích hoạt:
-
Thời gian tối thiểu: 10 ngày dương lịch
-
Thời gian tối đa: 20 ngày làm việc
Trạng thái đơn hàng và theo dõi
Phát triển API cập nhật trạng thái:
Việc cập nhật trạng thái và theo dõi đơn hàng sẽ được thực hiện qua API cập nhật tracking và dựa trên số đơn hàng được tạo trên Shopee (ID Đơn hàng, còn được biết là OrderSN). Trong đó cũng bắt buộc phải cung cấp số tracking.
Để cập nhật số tracking và trạng thái đơn hàng, cần sử dụng endpoint v2.logistics.update_tracking_status (OpenAPI). Các trạng thái có thể là:
- Đơn hàng đã giao (logistics_pickup_done)
- URL và tracking number có thể được gửi khi cập nhật trạng thái đơn hàng sang Đã giao.
- Đơn hàng đã nhận (logistics_delivery_done)
- Trạng thái Đã nhận chỉ được chấp nhận khi đơn hàng đã có trạng thái Đã giao.
- Giao hàng thất bại (logistics_delivery_failed)
- Trạng thái Giao hàng thất bại chỉ được chấp nhận khi đơn hàng đã có trạng thái Đã giao.
QUAN TRỌNG: sau khi gửi trạng thái Đơn hàng đã nhận hoặc Giao hàng thất bại, sẽ không còn được phép cập nhật trạng thái nữa vì cả hai đều là trạng thái kết thúc;
*các tham số tracking_number và tracking_url chỉ được gửi khi cập nhật trạng thái sang logistics_pickup_done.
Link tài liệu API "/api/v2/logistics/update_tracking_status".
Luồng và trạng thái đơn hàng của kênh
Quy tắc hoa hồng và vận chuyển cho kênh
- Giảm giá vận chuyển tối đa cho người mua là R$ 20, nếu người bán tham gia Chương trình Freeship
- Người bán sẽ đồng hưởng trong khoản giảm giá cung cấp cho khách hàng.
FAQ:
1 - Tất cả người bán đều có thể truy cập kênh Logistics Người bán không?
Đ: Chỉ những người bán được quản lý mới có quyền truy cập kênh, để biết thêm thông tin hãy liên hệ với Quản lý tài khoản của bạn.
2 - Làm thế nào để xác định báo giá trong đơn hàng?
Đ: Sau khi đơn hàng được tạo với báo giá thành công, tham số "service_code" sẽ được trả về trong tham số "shipping_carrier" của API get_order_detail.
Ví dụ 1:
- "service_code" được gửi: "Canal X"
- giá trị trả về của tham số "shipping_carrier": "Logística do vendedor - Canal X"
Ví dụ 2:
- Bảng dự phòng được kích hoạt.
- giá trị trả về của tham số "shipping_carrier": "Logística do vendedor"
3 - Tôi có thể dùng APP Seller Logistics để gọi OpenAPI không?
Đ: Không, loại APP này chỉ dùng cho API báo giá (URL báo giá).
Để có thêm câu hỏi kỹ thuật, mở ticket trên Nền tảng Ticket OP.