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 bình thường.
Tài liệu liên quan: Authentication · Response format · Errors · Rate limits · Products · Orders · Webhooks
Phạm vi Public API (tóm tắt)
| Khu vực | Sandbox |
|---|---|
| Toàn cục | response_format: upstream bị từ chối (chỉ standard). Trường currency trong body bị từ chối như prod. sandbox_trigger được phép với khóa test (fixtures nền tảng). Channel OAuth coi như đã ủy quyền cho hio_test_*. Bỏ qua quota & rate limits với khóa test. |
/v1/products/* | Search, detail, parse, upload-image, search-by-image, freight estimate, batch-check, analytics 1688 được mock như mô tả bên dưới. Mở rộng chỉ OpenAPI ngoài bộ handoff của site không mock. |
/v1/orders/* | Preview, create, detail, pay, cancel, logistics trace, list, purchase query được mock với magic / dynamic id. |
/v1/fulfillment/* | Chưa mock trên gateway hiện tại — coi là không khả dụng trong sandbox. |
| Webhooks | Đơn sandbox không phát webhooks. |
Mục tiêu thiết kế
| Mục tiêu | Ý nghĩa |
|---|---|
| Lặp lại được | Cùng request → cùng response (không ngẫu nhiên kết quả). |
| Có tài liệu | Mỗi kịch bản có id hoặc keyword ổn định để grep trên trang này. |
| Khớp hợp đồng | JSON khớp trường schema standard từ production; giá trị khác. |
| Happy path mặc định | Id không biết fallback mock thành công chung. |
| Lỗi rõ ràng | Dùng id sb_* hoặc sandbox_trigger để ép lỗi / trạng thái biên. |
Đặt tên: sb_{domain}_{scenario}
| Phân đoạn | Quy tắc | Ví dụ |
|---|---|---|
| Tiền tố | Luôn sb_ | sb_prod_not_found |
domain | Danh từ chữ thường (prod, search, ord, plat, auth, …) | — |
scenario | snake_case | not_found, pay_declined |
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.
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 product_id, url đã parse, mi_id hoặc tao_password resolve thành id sb_*.
| Fixture id | Kết quả | HTTP |
|---|---|---|
(mọi id không phải sb_) | Sản phẩm mock chuẩn | 200 |
sb_prod_not_found | NOT_FOUND | 404 |
sb_prod_offline | PRODUCT_UNAVAILABLE | 422 |
sb_prod_no_stock | Detail ok, stock: 0 | 200 |
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.
keyword (khớp chính xác) | Kết quả |
|---|---|
| văn bản thường | Danh sách mock có kết quả |
sb_search_empty | items: [], total: 0 |
sb_search_not_found | Alias của rỗng |
Parse / upload-image / search-by-image / freight / analytics
| Endpoint | Ghi chú sandbox |
|---|---|
| Parse URL | Query/path URL chứa sb_* phản chiếu hành vi detail. |
| Upload image | Luôn { "image_id": "img_sandbox_mock" } sau khi validation pass. |
| Image search | keyword: sb_search_empty tùy chọn cho danh sách rỗng; kết hợp upload-image cho test luồng. |
| Advanced — freight estimate | Mock cước nội địa mặc định 800 minor units khớp preview. |
| Advanced — batch-check | Trả envelope kiểu upstream với mock mpProducts; dùng sb_prod_not_found trong mi_id/item_id cho danh sách loại trừ. |
| Advanced — top keywords/list / daily-sales-trend | Dùng sb_search_empty trên category_id / rank_id nơi có tài liệu để danh sách rỗng hoặc 404 detail. |
Fixtures đơn hàng & thanh toán (magic id)
POST /v1/orders/detail
order_id | status điển hình | Ghi chú |
|---|---|---|
sb_ord_unpaid | wait_payment | — |
sb_ord_paid | wait_shipment | — |
sb_ord_shipped | wait_receive | — |
sb_ord_completed | completed | — |
sb_ord_cancelled | cancelled | — |
sb_ord_refunding | wait_shipment (refund_status in progress) | — |
sb_ord_not_found | — | 404 |
POST /v1/orders/pay
order_id | Kết quả | HTTP |
|---|---|---|
sb_ord_unpaid | Thanh toán thành công → trạng thái paid logic | 200 |
sb_ord_pay_declined | PAYMENT_DECLINED | 402 |
sb_ord_pay_insufficient | PAYMENT_INSUFFICIENT_FUNDS | 402 |
sb_ord_paid | ORDER_ALREADY_PAID | 409 |
sb_ord_cancelled | ORDER_CANCELLED | 409 |
sb_ord_upstream_timeout | CHANNEL_UPSTREAM_ERROR | 502 |
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.
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.
sandbox_trigger | HTTP | error.code |
|---|---|---|
sb_plat_quota_exceeded | 429 | QUOTA_EXCEEDED |
sb_plat_rate_limited | 429 | RATE_LIMIT_EXCEEDED |
sb_plat_upstream_error | 502 | CHANNEL_UPSTREAM_ERROR |
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
| Giai đoạn | Phạm vi | Ghi chú |
|---|---|---|
| Shipped | Product + procurement API ở trên | Phản ánh tập con Public API trên site này. |
| Not yet | Đầy đủ /v1/fulfillment/*, webhooks, route OpenAPI-only chưa công bố | Đừng dựa vào trong CI sandbox cho đến khi thông báo. |
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_plat_quota_exceeded → sandbox_trigger → 429 QUOTA_EXCEEDEDKhi 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.