بروتوكول التجارة الشامل (Universal Commerce Protocol - UCP)

UCP معيار مفتوح يتيح لعملاء الذكاء الاصطناعي اكتشاف منتجاتك وخدماتك والبحث فيها وشراءها — عبر ملف JSON معياري ومجموعة من نقاط النهاية المهيكلة. هذه الصفحة مرجع شامل لتنفيذ UCP.

مقدمة عن UCP

يلعب UCP دور "القائمة القابلة للقراءة الآلية" لعملك. تمامًا كما يخبر robots.txt زواحف محركات البحث بالأقسام التي يجب زحفها، يخبر ملف UCP عملاء الذكاء الاصطناعي بما يملكه عملك من قدرات ومن أين تُستدعى كل واحدة منها. يجب أن يكون هذا الملف متاحًا دائمًا على العنوان الثابت https://yoursite.com/.well-known/ucp مع استجابة من نوع Content-Type: application/json.

البدء السريع

أسرع طريقة هي استخدام مولّد UCP المجاني: أدخل معلومات عملك والقدرات المطلوبة، وسيتم إنشاء ملف ucp.json كامل وجاهز للنشر. للكتابة اليدوية، استخدم مرجع الحقول والقدرات أدناه.

مرجع ملف ucp.json

{
  "protocol": "ucp/v1",
  "merchant_name": "متجر نموذجي",
  "description": "متجر إلكتروني للأجهزة الرقمية",
  "website": "https://example.com",
  "capabilities": [
    {
      "name": "search_offers",
      "description": "البحث في المنتجات",
      "endpoint": "https://api.example.com/v1/ucp/search",
      "method": "GET"
    }
  ],
  "payment_methods": ["credit_card"],
  "supported_languages": ["ar", "en"],
  "currency": "SAR"
}

مرجع القدرات (Capabilities)

يتضمّن كل عنصر من مصفوفة capabilities: name وdescription وendpoint وmethod. القدرات المعيارية الثماني:

مثال طلب واستجابة: search_offers

GET /v1/ucp/search?query=سماعات&limit=5

200 OK
{
  "results": [
    { "id": "sku_123", "name": "سماعات لاسلكية موديل X", "price": 129.00, "currency": "SAR", "in_stock": true }
  ]
}

مثال طلب واستجابة: initiate_checkout

POST /v1/ucp/checkout
{ "cart_id": "cart_789", "customer": { "name": "...", "phone": "..." } }

200 OK
{ "order_id": "order_456", "status": "pending_payment", "payment_url": "https://..." }

المصادقة

يُبقي UCP ملف manifest نفسه عامًا (بدون حاجة إلى مصادقة لقراءته)، لكن نقاط النهاية التشغيلية يجب أن تكون آمنة:

• اجعل جميع نقاط النهاية متاحة فقط عبر HTTPS
• استخدم رمز API أو Bearer Token لنقاط النهاية الحساسة (الدفع، المحفظة)
• احمِ الطلبات المُغيِّرة (POST) بتوقيع للطلب أو رمز nonce أحادي الاستخدام

الدفع

عادةً ما تبدأ قدرة initiate_checkout معاملة لدى بوابة الدفع الحالية لديك وتُعيد رابط الدفع أو معرّف المعاملة — فـUCP لا يحل محل بوابة الدفع لديك، بل هو طبقة معيارية فوقها. بالنسبة لأي متجر، هذا يعني الاتصال بنفس البوابات الحالية (مثل أي مزود خدمة دفع تستخدمه حاليًا) من خلف نقطة النهاية ذاتها.

معالجة الأخطاء

يجب أن تكون استجابة الخطأ دائمًا بصيغة JSON صالحة، لا صفحة HTML أو نصًا حرًّا:

404 Not Found
{ "error": { "code": "product_not_found", "message": "لم يتم العثور على المنتج المطلوب" } }

الاختبار والتحقق

• curl -i https://yoursite.com/.well-known/ucp — التحقق من استجابة 200 وJSON صالح
• تحقّق من المخرجات باستخدام مدقّق JSON عبر الإنترنت
• اختبر كل قدرة على حدة باستخدام Postman
• تأكّد من إرجاع استجابة JSON مهيكلة حتى في حالات الخطأ

إصدار النسخ

يحمل الحقل protocol الإصدار الحالي (مثل ucp/v1). يجب الإعلان عن التغييرات غير المتوافقة مع الإصدارات السابقة عبر زيادة رقم الإصدار، حتى لا تواجه العملاء التي لا تزال تنفّذ الإصدار القديم أخطاءً غير متوقعة.

الأسئلة الشائعة