Tổng quan fulfillment quốc tế

/v1/fulfillment/* bao gồm logistics quốc tế sau khi hàng vào kho HIOBuy. Mua hàng nội địa: đơn đại mua.

Ứng dụng cần fulfillment kho (ủy quyền cổng thông tin). Ứng dụng tự fulfillment nhận 403 FULFILLMENT_MODE_NOT_SUPPORTED.

Đơn vị tiền tệ {#monetary-unit}

Phản hồi JSON chuẩn trên các route fulfillment có số tiền gồm monetary_unit: "CNY_minor" ở cấp cao nhất. Mọi { amount, currency } dùng fen CNY (1 nhân dân tệ = 100 fen). Xem mô hình phản hồi fulfillment.

Tính khả dụng API {#availability}

Đường dẫn	Trạng thái
`/v1/fulfillment/inbounds/create`	Live kho `simple-store` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/packages`	Live kho `packages/index` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/packages/{package_id}`	Live kho `packages/detail/{id}` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/packages/{package_id}/tracking`	Live kho `packages/logs/{id}` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/unclaimed-packages`	Live danh sách + nhận kiện ở chế độ kho; mock trong sandbox
`/v1/fulfillment/returns`	Mock — tạo / liệt kê / xác nhận / hủy trả hàng cho người bán
`/v1/fulfillment/locations`	Live kho `warehouse` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/value-added-services`	Live kho `services` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/service-requests`	Mock — tạo / liệt kê / chi tiết / xác nhận
`/v1/fulfillment/shipments/{id}/intercept`	Live kho `shipments/set-exceptional` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/shipments`	Live kho `shipments/index` ở chế độ kho; mock trong sandbox
`/v1/fulfillment/shipping/channels`	Danh mục kênh Live ở chế độ kho; mock trong sandbox
`/v1/fulfillment/shipping/quotes`	Báo giá Live ở chế độ kho; mock trong sandbox
`/v1/fulfillment/shipments/*`	Khả dụng (HTTP kho nếu đã cấu hình, nếu không thì mock)
`/v1/fulfillment/balance`	Khả dụng
`/v1/shipments` (cũ)	Ngừng hỗ trợ

Luồng đầu-cuối {#end-to-end-flow}

Tạo đơn đại mua → người bán gửi hàng tới kho
hoặc báo trước nhập kho cho kiện bạn đã kiểm soát
Chi tiết / theo dõi kiện → đo tại kho / ngoại lệ / VAS / timeline
hoặc chi tiết đơn → tracking_numbers[] sau khi nhập từ đại mua
Kênh vận chuyển để xem khả năng, rồi báo giá vận chuyển → chọn quotes[].channel.code
Tạo lô gửi → id / order_sn (PENDING)
Đóng gói và đo cuối tại kho → boxes[], cân nặng / kích thước / cước cuối
Lô gửi sẵn sàng thanh toán (WAIT_PAYMENT) → xem chi tiết; thanh toán quá sớm trả 409 SHIPMENT_NOT_READY_FOR_PAYMENT
Thanh toán lô gửi → trừ ví
Danh sách / chi tiết → hàng nhẹ, hoặc thùng / tệp đóng gói / timeline / số first-mile và last-mile
Tùy chọn: chặn nếu cần giữ lô WAIT_SHIP / SHIPPED
Theo dõi quốc tế → sự kiện quét

Mới với fulfillment kho? Làm theo hướng dẫn kiểm thử WH-DEV để chạy hết quy trình, gồm đóng gói và quyết toán.

Bắt đầu kiểm thử WH-DEV →

Hướng dẫn endpoint

Chủ đề	Đường dẫn	Tài liệu
Báo trước nhập kho	`POST .../inbounds/create`	Nhập kho
Chi tiết / theo dõi / chưa nhận	`GET .../packages/*` · `unclaimed-packages`	Kiện
Trả hàng	`POST/GET .../returns` · confirm/cancel	Trả hàng
Địa điểm	`GET .../locations`	Địa điểm
Dịch vụ gia tăng	`GET .../value-added-services`	VAS
Yêu cầu dịch vụ	`POST/GET .../service-requests` · confirm	Yêu cầu dịch vụ
Kênh vận chuyển	`GET .../shipping/channels`	Kênh vận chuyển
Báo giá vận chuyển	`POST .../shipping/quotes`	Báo giá vận chuyển
Tạo / thanh toán / hủy / chặn	`POST .../shipments/create` · `{id}/pay` · `{id}/cancel` · `{id}/intercept`	Lô gửi
Danh sách lô gửi	`GET .../shipments`	Lô gửi · danh sách
Chi tiết lô gửi	`GET .../shipments/{id}`	Lô gửi · chi tiết
Theo dõi quốc tế	`GET .../shipments/{id}/tracking`	Theo dõi
Số dư ví	`GET /v1/fulfillment/balance`	Số dư
Trường phản hồi	—	Mô hình phản hồi
Thuộc tính hàng	`GET .../item-attributes`	Báo giá vận chuyển

Mua hàng ở chế độ kho

Đường dẫn /v1/orders/* không đổi; Gateway chuyển tiếp tới HIOBuy. API sản phẩm vẫn gọi marketplace trực tiếp.

Theo dõi nội địa: dấu vết logistics đơn (được proxy ở chế độ kho).

Sơ đồ vòng đời {#lifecycle}

Sơ đồ trạng thái: Kiện, Lô gửi, Trả hàng.

Lỗi

FULFILLMENT_MODE_NOT_SUPPORTED, SHIPMENT_CREATE_EXCEPTION, SHIPMENT_CREATE_FAILED, PARCEL_NOT_FOUND, EXTERNAL_ORDER_ID_ALREADY_EXISTS, SHIPMENT_NOT_READY_FOR_PAYMENT, SHIPMENT_ALREADY_PAID, INSUFFICIENT_BALANCE, NOT_FOUND (SHIPMENT_NOT_EXISTS), mã chặn (SHIPMENT_NOT_FOUND, SHIPMENT_NOT_INTERCEPTABLE, SHIPMENT_INTERCEPTION_ALREADY_REQUESTED) — xem Lỗi và Lô gửi.

Get Support

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

Email support