API hỏi nhà cung cấp

Ước tính cước vận chuyển quốc tế trước khi khách đặt mua

Với một chiếc sofa, một cây đèn sàn, một máy chạy bộ hay một chuồng thú cưng cỡ lớn, cước vận chuyển quốc tế gần như phụ thuộc hoàn toàn vào cách món hàng thực sự được đóng gói: khối lượng sau đóng gói, kích thước thùng, và hàng được chia thành bao nhiêu kiện.

Những dữ liệu đó thường thiếu hoặc không đáng tin trên trang sản phẩm 1688 và Taobao. Điều này đẩy khách hàng của bạn vào một vấn đề rất thực tế:

Họ biết sản phẩm giá bao nhiêu. Họ hoàn toàn không biết đưa nó về nước mình tốn bao nhiêu.

API hỏi nhà cung cấp lấp đúng khoảng trống đó. Dịch vụ liên hệ nhà cung cấp của HIOBuy sẽ trao đổi với nhà cung cấp thật trước khi mua hàng, xác nhận khối lượng sau đóng gói, kích thước kiện hàng và chi tiết thùng carton, rồi trả câu trả lời về ứng dụng của bạn dưới dạng dữ liệu có cấu trúc — sẵn sàng để đưa vào bài toán ước tính cước vận chuyển.

Vì sao chỉ Product API là chưa đủ

Các API sản phẩm cung cấp đáng tin cậy những gì chính sàn thương mại biết: tiêu đề, hình ảnh, giá, SKU, thuộc tính, thông tin shop. Nhưng dữ liệu logistics lại là chuyện khác:

• hoàn toàn không công bố khối lượng;
• khối lượng hiển thị là khối lượng tịnh của sản phẩm, không phải khối lượng sau đóng gói;
• có kích thước sản phẩm, nhưng không có kích thước sau khi đóng gói;
• khối lượng do người bán tự nhập và chỉ mang tính tham khảo;
• các SKU khác nhau cho ra khối lượng đóng gói khác nhau;
• một món hàng lớn được chia ra nhiều kiện để gửi đi;
• số lượng thùng carton, khối lượng thùng và kích thước thùng đều không có trên trang.

Product API cho bạn biết những gì sàn thương mại biết. Một yêu cầu hỏi nhà cung cấp mang về những gì chỉ nhà cung cấp mới xác nhận được.

Ví dụ: ước tính cước vận chuyển cho một chiếc sofa

Một khách hàng ở Hoa Kỳ đang xem một chiếc sofa trên 1688 trong ứng dụng của bạn, giá ¥800. Product API đã trả về sản phẩm, giá, hình ảnh, SKU và thuộc tính — nhưng không có khối lượng sau đóng gói hay kích thước kiện hàng đáng tin cậy.

Nên ứng dụng của bạn không thể trả lời câu hỏi duy nhất thực sự quan trọng tiếp theo:

Giá sản phẩm          ¥800
Vận chuyển quốc tế    ???

Với hàng cồng kềnh, ẩn số đó hoàn toàn có thể vượt cả giá trị của bản thân sản phẩm.

Ứng dụng của bạn tạo một yêu cầu hỏi:

POST /v1/supplier-inquiries
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "questions": [
    { "type": "packed_weight" },
    { "type": "package_dimensions" },
    { "type": "carton_info" }
  ]
}

HIOBuy chuyển tác vụ cho dịch vụ liên hệ nhà cung cấp, và một nhân viên tại Trung Quốc sẽ liên hệ đúng nhà cung cấp của listing đó. Nhà cung cấp trả lời rằng chiếc sofa được gửi thành hai kiện:

Kiện 1   32 kg   110 × 75 × 55 cm
Kiện 2   18 kg    90 × 60 × 40 cm

Những câu trả lời đó quay về ứng dụng của bạn dưới dạng JSON có cấu trúc, và toàn bộ hành trình trông như sau:

Sản phẩm 1688
      ↓  Product API
Giá: ¥800
      ↓  thiếu dữ liệu logistics đáng tin cậy
Yêu cầu hỏi nhà cung cấp
      ↓  HIOBuy liên hệ nhà cung cấp thật
Nhà cung cấp xác nhận: 2 kiện, 32 kg + 18 kg, kích thước thùng
      ↓  dữ liệu logistics có cấu trúc
Ước tính cước vận chuyển quốc tế (Trung Quốc → Hoa Kỳ)
      ↓
Khách hàng thấy tổng chi phí ước tính trước khi mua

Và đó chính là mục đích của toàn bộ quy trình này:

Chi phí sản phẩm
+ cước vận chuyển quốc tế ước tính
= một mức chi phí thực tế trước khi mua

Vị trí của nó trong hệ API HIOBuy

Product API            "Sản phẩm là gì, và giá bao nhiêu?"
        ↓
API hỏi nhà cung cấp   "Nhà cung cấp sẽ đóng gói nó thế nào trên thực tế?"
        ↓
Báo giá vận chuyển     "Gửi đi quốc tế sẽ tốn khoảng bao nhiêu?"

Hỏi nhà cung cấp chính là lớp còn thiếu giữa dữ liệu sản phẩm và một báo giá vận chuyển.

Không chỉ là dữ liệu vận chuyển

Dữ liệu đóng gói phục vụ ước tính vận chuyển là ứng dụng đầu tiên và cụ thể nhất của API này, nhưng cũng chính kênh liên hệ nhà cung cấp đó có thể trả lời mọi điều mà chỉ nhà cung cấp mới biết:

MOQ · tồn kho · thời gian sản xuất · đóng gói trung tính · tùy chỉnh · thông tin thùng carton · chi tiết sản phẩm · và bất cứ điều gì khác, thông qua kiểu other.

Vậy nên hôm nay nó mang lại cho bạn dữ liệu đóng gói → ước tính vận chuyển, và cũng chính lời gọi đó phục vụ được thông tin nhà cung cấp → quyết định mua hàng. Xem loại câu hỏi để biết đủ mười loại và lược đồ câu trả lời của từng loại.

Cách hoạt động

1. Ứng dụng của bạn gọi POST /v1/supplier-inquiries kèm URL sản phẩm, một SKU tùy chọn, và một hoặc nhiều câu hỏi có kiểu.
2. HIOBuy tạo yêu cầu hỏi và chuyển nó cho dịch vụ liên hệ nhà cung cấp.
3. Một nhân viên tại Trung Quốc liên hệ nhà cung cấp của listing đó.
4. Nhà cung cấp trả lời.
5. Câu trả lời được chuẩn hóa thành dữ liệu có cấu trúc theo lược đồ của từng loại câu hỏi.
6. Endpoint của bạn nhận webhook supplier_inquiry.message_answered, hoặc bạn chủ động truy vấn GET /v1/supplier-inquiries/{id}.

Một yêu cầu hỏi là một cuộc hội thoại, không phải một request dùng một lần. Khi nó đã tồn tại, hãy tiếp tục thêm tin nhắn hỏi tiếp vào cùng luồng thay vì mở một luồng thứ hai.

Tệp đính kèm

Có những câu hỏi sẽ dễ đặt hơn rất nhiều khi kèm một tấm ảnh. Một mẫu đóng gói tham khảo, ảnh chụp màn hình SKU, bản vẽ kích thước, một tờ thông số kỹ thuật — và ở chiều ngược lại, ảnh đóng gói của chính nhà cung cấp, ảnh thùng carton hay một file báo giá PDF.

Mỗi tin nhắn, của bạn lẫn của nhà cung cấp, đều có thể mang tối đa năm tệp đính kèm:

{
  "message": "Please ask the supplier whether they can use packaging similar to this.",
  "attachments": [
    {
      "type": "image",
      "url": "https://example.com/reference-packaging.jpg",
      "filename": "reference-packaging.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}

type nhận giá trị image, document hoặc other. URL bắt buộc phải là https://; mọi giá trị khác đều bị từ chối với INVALID_ATTACHMENT_URL.

Phản hồi của nhà cung cấp cũng có thể kèm tệp. Chúng xuất hiện trong mảng attachments của tin nhắn và trong webhook supplier_inquiry.message_answered, bên cạnh các câu trả lời có cấu trúc. Bạn chỉ nhìn thấy những tệp mà dịch vụ hỏi nhà cung cấp đánh dấu là dành cho bạn — các tệp làm việc nội bộ của nhân viên và ảnh chụp màn hình trao đổi với nhà cung cấp luôn nằm trong nội bộ dịch vụ và không bao giờ ra tới API.

Quyền truy cập

Tính năng hỏi nhà cung cấp mặc định bị tắt. HIOBuy bật tính năng này cho từng ứng dụng sau khi hoàn tất thủ tục hợp tác thương mại — hãy liên hệ bộ phận hỗ trợ HIOBuy để yêu cầu quyền truy cập.

Nếu năng lực này chưa được cấp hoặc đang bị tạm ngưng, mọi endpoint đều trả về 403 SUPPLIER_INQUIRY_NOT_ENABLED.

Các sàn được hỗ trợ

Mọi trường hợp khác sẽ thất bại với UNSUPPORTED_MARKETPLACE. Sản phẩm được xác định bằng channel + source_product_id, không bao giờ bằng chuỗi URL thô, nên các dạng link khác nhau của cùng một offer đều quy về cùng một sản phẩm.

Trạng thái yêu cầu hỏi

pending, processing, waiting_supplier và answered được tính là đang hoạt động. Mỗi ứng dụng chỉ được có một yêu cầu hỏi đang hoạt động cho mỗi sản phẩm — đó là cách duy trì đúng một luồng trao đổi với nhà cung cấp cho mỗi offer. Gửi request tạo mới cho sản phẩm có yêu cầu hỏi ở trạng thái completed hoặc failed sẽ mở lại cuộc hội thoại đó thay vì tạo mới.

Webhook

Đăng ký một endpoint trong developer portal và theo dõi nhóm sự kiện supplier_inquiry. Việc ký và cơ chế thử lại tuân theo quy tắc webhook tiêu chuẩn.

Mọi payload đều chứa inquiry_id và product.{channel,source_product_id}.

Mã lỗi

SUPPLIER_INQUIRY_SERVICE_UNAVAILABLE được thiết kế chung có chủ đích: các nguyên nhân từ phía nhà cung cấp dịch vụ như số dư hay trạng thái tài khoản sẽ không được tiết lộ. Hãy cung cấp request_id khi liên hệ bộ phận hỗ trợ.

Endpoint