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": ["iranian_bank_gateway"],
  "supported_languages": ["fa", "en"],
  "currency": "IRR"
}

مرجع قابلیت‌ها (Capabilities)

هر عضو آرایه‌ی capabilities شامل name، description، endpoint و method است. هشت قابلیت استاندارد:

نمونه درخواست و پاسخ: search_offers

GET /v1/ucp/search?query=هدفون&limit=5

200 OK
{
  "results": [
    { "id": "sku_123", "name": "هدفون بی‌سیم مدل X", "price": 4200000, "currency": "IRR", "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 در دسترس باشند
• برای اندپوینت‌های حساس (checkout، wallet)، از توکن API یا Bearer Token استفاده کنید
• درخواست‌های تغییردهنده (POST) را با امضای درخواست یا nonce یک‌بارمصرف محافظت کنید

پرداخت

قابلیت initiate_checkout معمولاً یک تراکنش را نزد درگاه پرداخت فعلی شما آغاز می‌کند و آدرس پرداخت یا شناسه‌ی تراکنش را برمی‌گرداند — UCP جایگزین درگاه پرداخت شما نیست، بلکه یک لایه‌ی استاندارد روی آن است. برای فروشگاه‌های ایرانی، این یعنی اتصال به همان درگاه‌های موجود (مثل زرین‌پال، آی‌دی‌پی یا هر PSP دیگری که در حال حاضر استفاده می‌کنید) از پشت همین اندپوینت.

مدیریت خطا

پاسخ خطا باید همیشه JSON معتبر باشد، نه صفحه‌ی HTML یا متن آزاد:

404 Not Found
{ "error": { "code": "product_not_found", "message": "محصول مورد نظر یافت نشد" } }

تست و اعتبارسنجی

• curl -i https://yoursite.com/.well-known/ucp — بررسی پاسخ ۲۰۰ و JSON معتبر
• خروجی را در یک اعتبارسنج JSON آنلاین بررسی کنید
• هر capability را جداگانه با Postman تست کنید
• مطمئن شوید در حالت خطا هم پاسخ JSON ساخت‌یافته برمی‌گردد

نسخه‌بندی

فیلد protocol نسخه‌ی فعلی را حمل می‌کند (مثلاً ucp/v1). تغییرات ناسازگار با نسخه‌های قبلی باید با افزایش شماره‌ی نسخه اعلام شوند تا ایجنت‌هایی که هنوز نسخه‌ی قدیمی را پیاده‌سازی کرده‌اند، دچار خطای غیرمنتظره نشوند.

سوالات متداول