بيئة Sandbox والـ fixtures
الجمهور: التكاملات الموجّهة إلى
https://api.hiobuy.com(بوابة Workers) — نفس base URL كما في الإنتاج.
المصادقة: تُطبَّق الـ fixtures الحتمية فقط على مفاتيح API ذات البادئة hio_test_* (key_type: test). مفاتيح الإنتاج hio_live_* لا تستخدم أبداً قواعد هذه الصفحة — بل تصل دائماً إلى upstream marketplaces بشكل طبيعي.
وثائق ذات صلة: Authentication · Response format · Errors · Rate limits · Products · Orders · Webhooks
تغطية Public API (ملخص)
| المجال | Sandbox |
|---|---|
| عام | response_format: upstream مرفوض (standard فقط). حقل currency في body مرفوض كما في prod. sandbox_trigger مسموح لمفاتيح test (fixtures المنصة). Channel OAuth يُعامل كمُصرَّح لـ hio_test_*. تُتخطى الحصص وrate limits لمفاتيح test. |
/v1/products/* | Search وdetail وparse وupload-image وsearch-by-image وfreight estimate وbatch-check وanalytics 1688 مُحاكاة (mock) كما هو موثّق أدناه. امتدادات OpenAPI-only خارج مجموعة handoff لهذا الموقع غير مُحاكاة. |
/v1/orders/* | Preview وcreate وdetail وpay وcancel وlogistics trace وlist وpurchase query مُحاكاة بمعرّفات magic / dynamic. |
/v1/fulfillment/* | غير مُحاكاة في البوابة حالياً — اعتبرها غير متاحة في sandbox. |
| Webhooks | طلبات sandbox لا تُصدِر webhooks. |
أهداف التصميم
| الهدف | المعنى |
|---|---|
| قابل للتكرار | نفس الطلب → نفس الاستجابة (بلا عشوائية في النتائج). |
| موثّق | لكل سيناريو معرّف أو keyword ثابت يمكن البحث عنه في هذه الصفحة. |
| متوافق مع العقد | JSON يطابق حقول مخطط standard من الإنتاج؛ القيم تختلف. |
| Happy path افتراضي | المعرّفات غير المعروفة تعود إلى mocks نجاح عامة. |
| فشل صريح | استخدم معرّفات sb_* أو sandbox_trigger لإجبار الأخطاء / حالات الحافة. |
التسمية: sb_{domain}_{scenario}
| الجزء | القاعدة | أمثلة |
|---|---|---|
| البادئة | دائماً sb_ | sb_prod_not_found |
domain | اسم بصيغة lowercase (prod, search, ord, plat, auth, …) | — |
scenario | snake_case | not_found, pay_declined |
الأحرف: [a-z0-9_]، الطول ≤ ~48. لا تُضِف بادئة sb_ لمعرّفات upstream حقيقية إلا إذا قصدت الـ fixture.
طبقتان من الفشل
ميّز بين أخطاء النقل/API وحالات الأعمال HTTP 200:
- فشل API → HTTP 4xx/5xx +
error.code(مثلNOT_FOUND,PAYMENT_DECLINED). - HTTP 200 مع حالة → مثل
variants[].stock = 0,status: wait_payment.
fixtures المنتجات (مختصر)
POST /v1/products/detail
راجع Product detail. صيغة upstream غير مدعومة في sandbox.
يُفعَّل عندما يُحل product_id أو url المُحلَّلة أو mi_id أو tao_password إلى معرّف sb_*.
| Fixture id | النتيجة | HTTP |
|---|---|---|
(أي معرّف غير sb_) | منتج mock قياسي | 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
تُطبَّق channel وkeyword وpage وpage_size وlanguage. مرشّحات 1688 filter / sort / السعر مقبولة لكنها تُتجاهَل لصفوف mock.
keyword (تطابق تام) | النتيجة |
|---|---|
| نص عادي | قائمة mock بنتائج |
sb_search_empty | items: [], total: 0 |
sb_search_not_found | مرادف للفراغ |
Parse / upload-image / search-by-image / freight / analytics
| Endpoint | ملاحظة sandbox |
|---|---|
| Parse URL | query/path URL يحتوي sb_* يعكس سلوك detail. |
| Upload image | دائماً { "image_id": "img_sandbox_mock" } بعد نجاح التحقق. |
| Image search | keyword: sb_search_empty اختياري يُنتج قائمة فارغة؛ ادمجه مع upload-image لاختبارات التدفق. |
| Advanced — freight estimate | mock الشحن المحلي الافتراضي 800 minor units متوافق مع preview. |
| Advanced — batch-check | يُرجع envelope بأسلوب upstream مع mock mpProducts؛ استخدم sb_prod_not_found في mi_id/item_id لقوائم الاستبعاد. |
| Advanced — top keywords/list / daily-sales-trend | استخدم sb_search_empty على category_id / rank_id حيث موثّق لقوائم فارغة أو حالات 404 detail. |
fixtures الطلبات والدفع (magic ids)
POST /v1/orders/detail
order_id | status نموذجي | ملاحظات |
|---|---|---|
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 | النتيجة | HTTP |
|---|---|---|
sb_ord_unpaid | دفع ناجح → حالة paid منطقية | 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 يُرجع إجماليات توضيحية ثابتة (سطر نموذجي ~4500 + شحن ~800 minor units). Create يُصدِر قيم order_id ديناميكية ببادئة sbo_* محفوظة في sandbox storage — الأسطر التي تشير إلى offer_id: sb_prod_offline / sb_prod_no_stock تُرجع 422 كما في الإنتاج.
Cancel / logistics / list / purchase query
وفق cancel وtrace وdetail list: sb_ord_* غير المدفوعة وsbo_* الديناميكية غير المدفوعة تُلغى؛ fixtures paid/shipped وغيرها تُرجع ORDER_NOT_CANCELLABLE. Logistics يُرجع packages لـ mocks sb_ord_shipped / completed؛ unpaid/paid-await-shipment تُرجع packages: []. قائمة المشتري تحترم product_name: sb_ord_list_empty للـ mocks الفارغة. Purchase query يُرجع upstream envelopes؛ تجنّب pseudo ids الخاصة بـ not-found حسب الحاجة.
محفّزات المنصة: sandbox_trigger
مسموح فقط على hio_test_*؛ مفاتيح الإنتاج تتجاهل الحقل بصمت.
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 |
ادمج مع معرّفات آمنة حتى تمرّ الأجسام الواقعية التحقق:
{
"channel": "1688",
"product_id": "123456",
"language": "en",
"sandbox_trigger": "sb_plat_quota_exceeded"
}fixture auth خاص sb_auth_channel_required مع triggers قد يُنتج CHANNEL_AUTH_REQUIRED (403) لانحدار UI رغم قاعدة «authorized by default».
لقطة حالة التنفيذ
| المرحلة | التغطية | ملاحظات |
|---|---|---|
| Shipped | Product + procurement APIs أعلاه | يعكس subset Public API المنشور على هذا الموقع. |
| Not yet | /v1/fulfillment/* كامل وwebhooks ومسارات OpenAPI-only غير منشورة | لا تعتمد عليها في CI sandbox حتى الإعلان. |
ورقة غش سريعة للنسخ
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_EXCEEDEDعند إضافة fixtures داخلياً، عكس نظام الترقيم هذا في اختبارات الانحدار — لا تُغيّر أبداً أشكال JSON standard داخل mocks.