Tạo yêu cầu hỏi nhà cung cấp

Có hai endpoint ghi dữ liệu vào một cuộc trao đổi với nhà cung cấp: một để bắt đầu, một để tiếp tục. Cả hai đều nhận cùng mảng questions và đều hỗ trợ Idempotency-Key.

Tạo một yêu cầu hỏi

POST /v1/supplier-inquiries — scope supplier_inquiry:write.

Nội dung request

TrườngBắt buộcMô tả
product_urlLink sản phẩm 1688 hoặc Taobao dạng tuyệt đối, tối đa 2048 ký tự
questions1–10 câu hỏi, xem loại câu hỏi
skuKhông{ "id": "...", "label": "..." }, mỗi giá trị 200 ký tự — giới hạn câu hỏi cho đúng một biến thể
attachmentsKhôngTối đa 5 tham chiếu tệp, xem tệp đính kèm
POST /v1/supplier-inquiries
Authorization: Bearer hio_live_...
Idempotency-Key: inq-2026-05-20-001
 
{
  "product_url": "https://detail.1688.com/offer/554456348334.html",
  "sku": { "id": "3245:12345", "label": "Đen / XL" },
  "questions": [
    { "type": "packed_weight", "note": "Khối lượng kèm hộp bán lẻ" },
    { "type": "carton_info" },
    { "type": "neutral_packaging" }
  ]
}

Phản hồi

201 Created, hoặc 200 OK khi một Idempotency-Key phát lại một request trước đó.

{
  "id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "product": {
    "channel": "1688",
    "source_product_id": "554456348334",
    "product_url": "https://detail.1688.com/offer/554456348334.html",
    "canonical_product_url": "https://detail.1688.com/offer/554456348334.html",
    "title": "...",
    "image": "...",
    "shop_id": "...",
    "shop_name": "..."
  },
  "sku": {
    "id": "3245:12345",
    "label": "Đen / XL"
  },
  "message_count": 1,
  "last_message_at": "2026-05-20T08:31:12.000Z",
  "created_at": "2026-05-20T08:31:11.000Z",
  "updated_at": "2026-05-20T08:31:12.000Z",
  "message": {
    "id": "smsg_1a4b...",
    "type": "initial",
    "status": "waiting_supplier"
  },
  "request_id": "req_..."
}

title, image, shop_idshop_name được điền theo nguyên tắc nỗ lực tối đa. Việc bổ sung dữ liệu này dùng API chi tiết sản phẩm, vốn cần một quyền uỷ quyền sàn mà ứng dụng của bạn có thể không có — khi không khả dụng, các trường này giữ giá trị null và yêu cầu hỏi vẫn được xử lý bình thường.

Một yêu cầu hỏi đang hoạt động cho mỗi sản phẩm

Nếu sản phẩm đã có một yêu cầu hỏi đang hoạt động, request sẽ thất bại:

409 Conflict
{
  "error": {
    "code": "ACTIVE_INQUIRY_EXISTS",
    "message": "An active supplier inquiry already exists for this product.",
    "details": { "inquiry_id": "sinq_9f2c...", "next_action": "add_message" }
  }
}

Hãy dùng inquiry_id được trả về để gửi câu hỏi tiếp theo. Nếu cuộc hội thoại trước đó ở trạng thái completed hoặc failed, request tạo mới sẽ mở lại nó thay vì báo lỗi, và tin nhắn mới được ghi nhận là follow_up.

Hỏi tiếp

POST /v1/supplier-inquiries/{inquiry_id}/messages — scope supplier_inquiry:write.

POST /v1/supplier-inquiries/sinq_9f2c.../messages
{
  "questions": [
    { "type": "lead_time", "note": "Cho 500 sản phẩm" },
    { "type": "moq" }
  ],
  "attachments": [
    {
      "type": "image",
      "url": "https://cdn.example.com/packaging-example.jpg",
      "filename": "packaging-example.jpg",
      "mime_type": "image/jpeg"
    }
  ]
}
201 Created
{
  "inquiry_id": "sinq_9f2c...",
  "status": "waiting_supplier",
  "message": {
    "id": "smsg_77de...",
    "type": "follow_up",
    "status": "waiting_supplier",
    "questions": [
      { "id": "sqst_...", "type": "lead_time", "note": "Cho 500 sản phẩm", "question": null, "status": "pending", "answer": null }
    ],
    "attachments": [
      {
        "id": "satt_...",
        "type": "image",
        "url": "https://cdn.example.com/packaging-example.jpg",
        "filename": "packaging-example.jpg",
        "mime_type": "image/jpeg",
        "source": "developer",
        "expires_at": null,
        "created_at": "2026-05-20T10:02:00.000Z"
      }
    ],
    "provider_note": null,
    "created_at": "2026-05-20T10:02:00.000Z",
    "answered_at": null
  },
  "request_id": "req_..."
}

Yêu cầu hỏi ở trạng thái cancelled sẽ từ chối tin nhắn mới với 409 INQUIRY_NOT_ACTIVE. Yêu cầu ở trạng thái completed hoặc failed sẽ được mở lại.

Tệp đính kèm

Cả hai endpoint ghi đều nhận một mảng attachments tùy chọn — một ảnh tham khảo, ảnh chụp màn hình SKU, bản vẽ kích thước, một file PDF thông số. Tệp đính kèm thuộc về tin nhắn mà bạn gửi kèm, nên mỗi lượt trao đổi có tệp đính kèm riêng của nó.

TrườngBắt buộcMô tả
urlChỉ chấp nhận https://, tối đa 2048 ký tự. http:, file:, data:, javascript:ftp: đều bị từ chối với INVALID_ATTACHMENT_URL
typeKhôngimage, document hoặc other; mặc định là other
filenameKhôngTối đa 255 ký tự
mime_typeKhôngTối đa 128 ký tự — là giá trị bạn khai báo, được lưu nguyên trạng

Tối đa năm tệp đính kèm cho mỗi tin nhắn, nếu không sẽ nhận 400 TOO_MANY_ATTACHMENTS.

HIOBuy chỉ lưu metadata và URL, không lưu tệp: hệ thống không tải lên, tải xuống, sao chép hay trung chuyển nội dung tệp đính kèm, và cũng không bao giờ truy cập URL bạn gửi. Hãy tự lưu trữ tệp và đảm bảo URL vẫn truy cập được từ phía dịch vụ hỏi nhà cung cấp trong suốt thời gian cuộc hội thoại còn mở.

Tính bất biến (idempotency)

Hãy gửi Idempotency-Key (hoặc X-Idempotency-Key, tối đa 200 ký tự) trên cả hai endpoint ghi. Một key lặp lại trong cùng ứng dụng sẽ trả về tin nhắn đã tạo ở lần đầu, với mã trạng thái 200 thay vì 201, và không bao giờ liên hệ nhà cung cấp hai lần.

Luôn thử lại request tạo bị timeout với cùng một key — nếu không có key, lần thử lại có thể mở thêm một cuộc hội thoại thứ hai hoặc gặp ACTIVE_INQUIRY_EXISTS.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support