بيئة 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 · Fulfillment · Webhooks

تغطية Public API (ملخص)

أهداف التصميم

التسمية: sb_{domain}_{scenario}

الأحرف: [a-z0-9_]، الطول ≤ ~48. لا تُضِف بادئة sb_ لمعرّفات upstream حقيقية إلا إذا قصدت الـ fixture. تستخدم بعض موارد fulfillment أيضاً معرّفات مستقرة غير sb_ (ret_*, ucp_*, svc_*, tkt_*, inv_*).

طبقتان من الفشل

ميّز بين أخطاء النقل/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.

يُفعَّل عندما يُحل id, product_id أو url المُحلَّلة أو mi_id أو tao_password إلى معرّف 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

تُطبَّق channel وkeyword وpage وpage_size وlanguage. مرشّحات 1688 filter / sort / السعر مقبولة لكنها تُتجاهَل لصفوف mock.

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

fixtures الطلبات والدفع (magic ids)

POST /v1/orders/detail

POST /v1/orders/pay

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 حسب الحاجة.

fixtures الـ Fulfillment

ملاحظة: الـ fixtures أدناه لاختبار Sandbox API فقط. لا تمثل إعداد WH-DEV لمستودع تطبيقك. لاختبار WH-DEV، استخدم Production API key (hio_live_*).

تتطلّب جميع نقاط النهاية أدناه مفتاح hio_test_*. تُحفَظ المعرّفات الديناميكية من create (pkg_*, sbs_*, sbi_*, …) في sandbox storage للمفتاح.

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 يُرجع package_id ديناميكي (pkg_*) — لا يوجد inbound_id منفصل.

Packages · tracking · list

Unclaimed packages

Returns

Service requests

Finance (transactions / invoices)

راجع Fulfillment finance.

fixtures تذاكر الدعم

راجع Support tickets.

محفّزات المنصة: sandbox_trigger

مسموح فقط على hio_test_*؛ مفاتيح الإنتاج تتجاهل الحقل بصمت.

ادمج مع معرّفات آمنة حتى تمرّ الأجسام الواقعية التحقق:

{
  "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».

لقطة حالة التنفيذ

ورقة غش سريعة للنسخ

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

عند إضافة fixtures داخلياً، عكس نظام الترقيم هذا في اختبارات الانحدار — لا تُغيّر أبداً أشكال JSON standard داخل mocks.