Môi trường sandbox và fixtures

Đối tượng: tích hợp triển khai với https://api.hiobuy.com (Workers gateway) — cùng base URL như production.

Auth: fixtures xác định chỉ áp dụng cho khóa API có tiền tố hio_test_* (key_type: test). Khóa production hio_live_* không bao giờ dùng quy tắc trang này — luôn gọi upstream marketplace / kho bình thường.

Tài liệu liên quan: Authentication · Response format · Errors · Rate limits · Products · Orders · Fulfillment · Webhooks

Phạm vi Public API (tóm tắt)

Mục tiêu thiết kế

Đặt tên: sb_{domain}_{scenario}

Ký tự: [a-z0-9_], độ dài ≤ ~48. Không thêm tiền tố sb_ cho id upstream thật trừ khi muốn fixture. Một số tài nguyên fulfillment cũng dùng id ổn định không phải sb_ (ret_*, ucp_*, svc_*, tkt_*, inv_*).

Hai lớp lỗi

Phân biệt lỗi transport/API và trạng thái nghiệp vụ HTTP 200:

• Lỗi API → HTTP 4xx/5xx + error.code (vd. NOT_FOUND, PAYMENT_DECLINED).
• HTTP 200 có trạng thái → vd. variants[].stock = 0, status: wait_payment.

Fixtures sản phẩm (tổng quan)

POST /v1/products/detail

Xem Product detail. Định dạng upstream không hỗ trợ trong sandbox.

Kích hoạt khi id, product_id, url đã parse, mi_id hoặc tao_password resolve thành id sb_*.

curl https://api.hiobuy.com/v1/products/detail \
  -H "Authorization: Bearer hio_test_..." \
  -H "Content-Type: application/json" \
  -d '{"channel":"1688","product_id":"sb_prod_not_found","language":"en"}'

POST /v1/products/search

Áp dụng channel, keyword, page, page_size, language. Bộ lọc 1688 filter / sort / giá chấp nhận nhưng bỏ qua cho hàng mock.

Parse / upload-image / search-by-image / freight / analytics

Fixtures đơn hàng & thanh toán (magic id)

POST /v1/orders/detail

POST /v1/orders/pay

Preview / create

Preview trả tổng minh họa cố định (dòng mẫu ~4500 + cước ~800 minor units). Create phát order_id động tiền tố sbo_* lưu trong sandbox storage — dòng tham chiếu offer_id: sb_prod_offline / sb_prod_no_stock trả 422 như production.

Cancel / logistics / list / purchase query

Theo cancel, trace, detail list: sb_ord_* chưa thanh toán và sbo_* động chưa thanh toán hủy được; fixtures paid/shipped/v.v. trả ORDER_NOT_CANCELLABLE. Logistics trả packages cho mock sb_ord_shipped / completed; unpaid/paid-await-shipment trả packages: []. Danh sách người mua tôn trọng product_name: sb_ord_list_empty cho mock rỗng. Purchase query trả upstream envelopes; bỏ qua pseudo id not-found tương ứng.

Fixtures fulfillment

Lưu ý: các fixture bên dưới chỉ dành cho kiểm thử Sandbox API. Chúng không đại diện cho cấu hình WH-DEV của ứng dụng. Để kiểm thử WH-DEV, hãy dùng Production API key (hio_live_*).

Tất cả endpoint bên dưới yêu cầu khóa hio_test_*. Id động từ create (pkg_*, sbs_*, sbi_*, …) được lưu trong sandbox storage theo khóa.

Balance · quotes · locations · VAS catalog

Shipments

Live warehouse Public id is the numeric PK as a string (e.g. "115"); order_sn is the warehouse order number. Sandbox create returns sbs_*; fixtures below use sb_shp_*.

List path: GET /v1/fulfillment/shipments. Tracking path: GET /v1/fulfillment/shipments/{id}/tracking (language query).

Inbounds (create / cancel)

Create trả package_id động (pkg_*) — không có inbound_id riêng.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

Xem Fulfillment finance.

Fixtures support ticket

Xem Support tickets.

Trigger nền tảng: sandbox_trigger

Chỉ cho phép trên hio_test_*; khóa production im lặng bỏ qua trường.

Kết hợp với id vô hại để body thực tế vẫn validate:

{
  "channel": "1688",
  "product_id": "123456",
  "language": "en",
  "sandbox_trigger": "sb_plat_quota_exceeded"
}

Fixture auth đặc biệt sb_auth_channel_required kết hợp trigger có thể tạo CHANNEL_AUTH_REQUIRED (403) cho hồi quy UI dù quy tắc «authorized by default».

Ảnh chụp trạng thái triển khai

Bảng gian lận sao chép nhanh

sb_prod_not_found          → 404 product missing
sb_prod_offline            → 422 unavailable
sb_prod_no_stock           → 200 detail with zero stock

sb_search_empty            → empty search/items
sb_ord_list_empty          → empty buyer order list filter
img_sandbox_mock           → stable upload-image id

sb_ord_unpaid              → detail wait_payment • pay succeeds • cancel ok
sb_ord_pay_declined        → pay 402 PAYMENT_DECLINED
sb_ord_paid                → pay 409 ALREADY_PAID • trace maybe empty until shipped fixtures
sb_ord_shipped             → detail wait_receive • trace populated
sb_ord_cancelled           → cancelled state • pay conflicts

sb_shp_unpaid / sb_shp_shipped / sb_shp_signed / sb_shp_intercepted → shipment list / detail / intercept
sb_pkg_received / sb_pkg_shipped → package detail / fulfillment timeline
sb_inbound_exists          → inbound create 409 tracking exists
ret_pending_001            → return confirm happy path
ucp_01K2ABCDEF1234567890   → unclaimed claimable
svc_photo_completed        → VAS request completed
tkt_01K2ABCDEF1234567890   → support ticket open

sb_plat_quota_exceeded     → sandbox_trigger → 429 QUOTA_EXCEEDED

Khi thêm fixtures nội bộ, phản ánh sơ đồ đánh số này trong test hồi quy — không bao giờ thay đổi hình dạng JSON standard trong mock.