ابنِ مع Pico

بدء سريع

1. 1
   شغّل الـ API

   شغّل الـ API على http://localhost:8000 واملأه بـ php artisan migrate --seed.

2. 2
   افتح الـ sandbox

   استخدم sandbox أو استدعِ نقاط widget مباشرة.

3. 3
   سجّل الدخول كتاجر

   لوحة التحكم على http://localhost:3000 باستخدام owner@pico.test / password.

تدفق الـ widget العام يستخدم ثلاث استدعاءات:

# 1. Fetch widget configuration (public, no auth)
curl http://localhost:8000/api/v1/widget/config/pw_sandbox_demo_widget_001

# 2. Start a shopper session
curl -X POST http://localhost:8000/api/v1/widget/sessions \
  -H "Content-Type: application/json" \
  -d '{"public_widget_id":"pw_sandbox_demo_widget_001","locale":"en"}'

# 3. Send a message
curl -X POST http://localhost:8000/api/v1/widget/sessions/<session_id>/messages \
  -H "Content-Type: application/json" \
  -d '{"message":"Waterproof hiking boots under 150"}'

تضمين الـ widget

<script type="module" src="https://cdn.example.com/pico-widget.js"
  data-public-widget-id="pw_sandbox_demo_widget_001"
  data-api-url="http://localhost:8000/api/v1"></script>

يُعرض الـ widget داخل Shadow DOM حتى لا تكسر أنماط موقعك واجهته. يظهر زر الإضافة إلى السلة فقط عندما يبلّغ المتجر المتصل عن القدرة add_to_cart.

دليل Sandbox

Sandbox بيئة مُعلَّمة بوضوح وغير إنتاجية مدعومة بمتجر تجريبي ومنتجات خارجية نموذجية.

• مجهول: أدخل معرّف الـ widget التجريبي pw_sandbox_demo_widget_001 ثم تحدّث.
• مسجّل الدخول: يحمّل الـ sandbox متجرك التجريبي عبر GET /sandbox/config.
• يُعرض كل طلب واستجابة كـ JSON حتى ترى بالضبط ما يعيده الـ API.
• لا شيء هنا يلمس طلبات أو مدفوعات أو كتالوجات إنتاج حقيقية.

صيغة الأخطاء

كل خطأ يستخدم حالة HTTP ونفس جسم JSON. سجّل دائماً request_id عند الإبلاغ عن مشكلة.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request could not be validated.",
    "details": { "message": ["The message field is required."] },
    "request_id": "req_01HXYZ..."
  }
}

details قد يحتوي details على أخطاء حقول، ولا يحتوي أبداً على أسرار أو stack traces.

أدلة التكامل

اربط Pico بمنصة التجارة لديك. تغطي الأدلة بيانات الاعتماد والمزامنة وتضمين الواجهة.