API thu mua thủ công

Một kênh, một người bán, một đơn mua hàng

Một đơn mua hàng có thể chứa nhiều sản phẩm hoặc SKU, nhưng mọi mặt hàng phải thuộc cùng một kênh và cùng một người bán.

Nếu khách mua sản phẩm từ nhiều người bán hoặc kênh khác nhau, ứng dụng của bạn phải tách thành các đơn mua hàng riêng theo kênh và người bán trước khi gọi API đơn hàng HIOBuy.

HIOBuy không tự động tách đơn mua hàng và không cung cấp API đặt hàng hàng loạt cho quy trình này.

Xác định kênh và người bán

Sử dụng channel ở cấp đơn hàng. Kênh trong đường dẫn rút gọn, nội dung yêu cầu và từng dòng hàng phải khớp nhau. Không trộn kênh trong lines[] hoặc items[].
Khi nhóm sản phẩm ở phía ứng dụng, hãy dùng seller.id thật từ API sản phẩm nếu có: 1688 lấy từ sellerOpenId, chi tiết Taobao lấy từ shop_id. Giá trị dự phòng được tạo như seller_1688_* / seller_taobao_*, ID bị thiếu, tên sản phẩm hoặc tên cửa hàng không phải bằng chứng đáng tin cậy về người bán. ID cửa hàng Taobao và ID người bán trong phản hồi dựng đơn thuộc các hệ định danh khác nhau, không được so sánh trực tiếp.
Yêu cầu tạo đơn tiêu chuẩn không thêm trường người bán bắt buộc mới. Trong chế độ self, trước khi tạo đơn chính thức, Gateway xác minh người bán của 1688 bằng chi tiết sản phẩm gốc; với Taobao, dùng render_item_list[].seller_id và kiểm tra đầy đủ mọi sản phẩm/SKU được yêu cầu. Thiếu bằng chứng hoặc thông tin không rõ ràng thì từ chối.
Trong chế độ mua hàng Warehouse, bao gồm đơn thủ công, kho phải xác minh người bán trước khi tạo đơn, bắt đầu mua hàng, trừ ví hoặc trả về thành công một phần. Gateway kiểm tra xung đột kênh trong yêu cầu gốc và chuyển tiếp lỗi từ kho mà không truy vấn lại các sàn. Kho phải được nghiệm thu riêng; việc triển khai Gateway không chứng minh kho bên ngoài đã có bước kiểm tra này.
Đơn thủ công dùng channel=manual; mọi mặt hàng cũng phải có cùng source_platform. seller_name chỉ là thông tin khai báo để hiển thị. Kho phải xác minh người bán thật của từng sản phẩm trên nền tảng, hoặc trả về SELLER_ID_UNAVAILABLE. Tên hay ID do bên gọi khai báo không thay thế được việc xác minh. Không bật tạo đơn thủ công trước khi nghiệm thu hợp đồng tích hợp với kho.

Lỗi và cách xử lý

Cả ba lỗi đều dùng HTTP 400, nhóm VALIDATION_ERROR:

Mã lỗi	Cách xử lý
`MULTIPLE_CHANNELS_NOT_ALLOWED`	Tách mặt hàng theo kênh; bảo đảm kênh ở đường dẫn, nội dung và dòng hàng giống nhau.
`MULTIPLE_SELLERS_NOT_ALLOWED`	Trong mỗi kênh, tách theo người bán thật rồi tạo đơn riêng.
`SELLER_ID_UNAVAILABLE`	Lấy ID sản phẩm/SKU hợp lệ hoặc cơ chế xác minh người bán đáng tin cậy từ kho. Không gửi lại nguyên yêu cầu hoặc suy đoán bằng tên.

Thông báo tiếng Anh nguyên văn do API trả về khi trộn đơn:

A purchase order must contain products from the same channel and seller. Please split the items into separate orders by channel and seller.

Từ chối do phạm vi người bán không được tạo đơn, tạo tác vụ mua hàng, trừ ví hoặc gây thành công một phần. Các quy tắc chống xử lý trùng hiện có vẫn áp dụng. Mỗi đơn được chủ động tách phải có mã nghiệp vụ/khóa riêng; khi thử lại một đơn không thay đổi, hãy dùng khóa ban đầu.

Đơn mua hàng và gửi hàng gộp

Đơn mua hàng là giao dịch nội địa với từng người bán. Hàng từ các đơn riêng có thể nhập kho thành từng kiện, sau đó gộp vào một lô gửi quốc tế nếu đáp ứng điều kiện kho và vận chuyển. Việc gộp không hợp nhất mã đơn mua gốc, cước nội địa hay trạng thái thanh toán, hủy và hoàn tiền.

Yêu cầu đúng: nhiều SKU của một người bán đã xác minh

Kho phải xác nhận độc lập rằng cả hai URL sản phẩm thuộc cùng một người bán có định danh ổn định trên nền tảng. URL ví dụ chỉ minh họa, không phải bằng chứng người bán hay kết quả nghiệm thu production.

{
  "channel": "manual",
  "external_order_id": "MANUAL-SELLER-A-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 41",
      "unit_price": 5000,
      "quantity": 1
    }
  ]
}

Ví dụ sai: người bán thực tế khác nhau

Nếu items[0].product_url thuộc người bán A và items[1].product_url thuộc người bán B, kho phải trả về MULTIPLE_SELLERS_NOT_ALLOWED dù yêu cầu khai báo seller_name: "Seller A". Nếu không xác minh được, trả về SELLER_ID_UNAVAILABLE thay vì chấp nhận dựa trên tên khai báo.

{
  "channel": "manual",
  "external_order_id": "INVALID-MIXED-001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "items": [
    {
      "product_url": "https://example.com/seller-A/shoe",
      "product_name": "Shoes",
      "specification": "Size 40",
      "unit_price": 5000,
      "quantity": 1
    },
    {
      "product_url": "https://example.com/seller-B/shirt",
      "product_name": "Shirt",
      "specification": "M",
      "unit_price": 3000,
      "quantity": 1
    }
  ]
}

Kết quả từ chối của kho phải được phát lại theo hợp đồng mã nghiệp vụ/chống xử lý trùng hiện có, không tạo đơn hay trừ tiền. Đơn đã tạo vẫn giữ hành vi gửi lại, xem chi tiết, thanh toán và hủy tương thích.

POST /v1/orders/manual

Mỗi yêu cầu tạo một đơn cho một nền tảng và một người bán, có thể gồm nhiều sản phẩm của người bán đó. Chỉ mở jd, pinduoduo và poizon; seller_name là bắt buộc. Khác nền tảng hoặc người bán phải tách yêu cầu và mã nghiệp vụ.

Cần Production API Key, quyền order:create, chế độ warehouse và liên kết kho hợp lệ. Không cần OAuth sàn. Chưa hỗ trợ Sandbox. Kho phải triển khai và kiểm tra API thủ công trước khi sử dụng.

Yêu cầu

Authorization: Bearer <PRODUCTION_API_KEY>
Content-Type: application/json
Idempotency-Key: 6c14ce20-cf29-4c25-a9ee-3d36aac94c16

{
  "channel": "manual",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "domestic_shipping_fee": 800,
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "language": "vi",
  "remark": "Please ship together",
  "items": [
    {
      "item_ref": "I001",
      "product_url": "https://example.com/item1",
      "product_name": "Wireless Mouse",
      "specification": "Black",
      "unit_price": 3500,
      "quantity": 2,
      "product_image": null,
      "remark": ""
    }
  ]
}

external_order_id bắt buộc và duy nhất trong đơn thủ công của ứng dụng. Cùng mã và dữ liệu trả về đơn cũ; đổi dữ liệu trả HTTP 409 IDEMPOTENCY_CONFLICT. Mua mới dùng mã mới. Idempotency-Key bắt buộc khi tạo, thanh toán và hủy. HIOBuy sinh order_sn; item_ref có thể bỏ qua. Không nhận mảng sellers hoặc thông tin nền tảng/người bán ở từng dòng.

Trường	Giá trị bắt buộc hoặc giới hạn
`channel`	`manual`
`external_order_id`	1–200
`source_platform`	`jd` / `pinduoduo` / `poizon`
`seller_name`	1–200
`currency` / `monetary_unit`	`CNY` / `CNY_minor`
`domestic_shipping_fee` / `items[].unit_price`	integer ≥ 0
`items` / `items[].quantity`	1–100 / 1–9999

Chi phí từ kho

Số tiền là số nguyên fen CNY: 3500 = CNY 35.00. Kho tính tiền hàng, vận chuyển nội địa, phí mua hàng 5% hiện có và tổng phải trả. Ví dụ không xác định cơ sở, mức tối thiểu hay làm tròn. HIOBuy lưu số tiền và không cộng thêm 5%. Thiếu tiền hoặc ánh xạ sản phẩm thì không thể thanh toán.

{
  "channel": "manual",
  "success": true,
  "order_id": "WH10001",
  "order_sn": "HB202610160001",
  "external_order_id": "EXT-10001",
  "source_platform": "jd",
  "seller_name": "Seller A",
  "status": "wait_payment",
  "currency": "CNY",
  "monetary_unit": "CNY_minor",
  "total": {
    "merchandise": {
      "amount": 7000,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 800,
      "currency": "CNY"
    },
    "procurement_fee": {
      "amount": 390,
      "currency": "CNY"
    },
    "payment": {
      "amount": 8190,
      "currency": "CNY"
    }
  },
  "order_list": [
    {
      "order_id": "WH10001",
      "shipping": {
        "amount": 800,
        "currency": "CNY"
      },
      "lines": [
        {
          "item_ref": "I001",
          "sub_order_id": "WI10001",
          "title": "Wireless Mouse",
          "spec_title": "Black",
          "quantity": 2,
          "unit_price": {
            "amount": 3500,
            "currency": "CNY"
          },
          "line_total": {
            "amount": 7000,
            "currency": "CNY"
          }
        }
      ]
    }
  ],
  "failed_offers": [],
  "request_id": "req_example"
}

Thao tác đơn hiện có

Tạo đơn không trừ ví hoặc bắt đầu mua. Dùng order_id và channel=manual với API thanh toán, hủy, chi tiết và theo dõi nội địa hiện có. Không gửi pay_amount. Sau khi đối chiếu số tiền đã lưu, kho dùng quy trình ví hiện có và chỉ mua khi thanh toán được xác nhận. Hủy không có nghĩa đã hoàn tiền.

{
  "channel": "manual",
  "order_id": "WH10001"
}

{
  "channel": "manual",
  "order_id": "WH10001",
  "cancel_reason": "buyer_request"
}

Thử lại và giới hạn

Khi hết thời gian hoặc chưa rõ kết quả, giữ mã và khóa cũ rồi xem chi tiết. Không tự đổi khóa để trả tiền lần nữa. Chi tiết gồm payment_status, tham chiếu sản phẩm và chi phí. API danh sách và hoàn tiền sàn chưa hỗ trợ manual. Giới hạn: 1–100 dòng, số lượng 1–9999, tên người bán 200 ký tự, tên sản phẩm/quy cách 500, ghi chú 1000, URL HTTP/HTTPS 2048. Không nhận chuỗi tiền hoặc số thập phân.

400 VALIDATION_ERROR · 403 FULFILLMENT_MODE_NOT_SUPPORTED / WAREHOUSE_AUTH_INVALID · 409 IDEMPOTENCY_CONFLICT / ORDER_AMOUNT_CHANGED / ORDER_OPERATION_UNRESOLVED · 502 WAREHOUSE_INVALID_RESPONSE · 503 WAREHOUSE_UNAVAILABLE

Webhooks

procurement.failed / procurement.out_of_stock

{
  "type": "procurement.failed",
  "data": {
    "channel": "manual",
    "order_id": "WH10001",
    "order_sn": "HB202610160001",
    "external_order_id": "EXT-10001",
    "source_platform": "jd",
    "seller_name": "Seller A",
    "status": "partial_failure",
    "reason_code": "OUT_OF_STOCK",
    "items": [
      {
        "item_ref": "I001",
        "sub_order_id": "WI10001",
        "quantity": 1,
        "reason_code": "OUT_OF_STOCK"
      }
    ]
  }
}

Get Support

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

Email support