تنفيذ الرموز الترويجية والخصومات

يوفّر هذا الدليل المرجع الفني لواجهة برمجة التطبيقات ومخططات حمولات البيانات للتعامل مع الرموز الترويجية والخصومات في الإصدار 2026-04-08 من بروتوكول Universal Commerce Protocol (UCP).

قبل إنشاء نقاط النهاية، تأكَّد من مراجعة نظرة عامة على الرموز الترويجية و الخصومات للاطّلاع على المفاهيم عالية المستوى والثوابت الرياضية وقواعد معالجة الأخطاء.

استكشاف المحتوى

لتلقّي رموز الخصومات من Google، عليك الإعلان عن إمكانية استخدام الخصومات في ملفك الشخصي. في الإصدار 2026-04-08، تتحقّق المنصّات مما إذا تم توسيع إمكانية الدفع قبل إرسال رموز الخصومات.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08",
          "extends": ["dev.ucp.shopping.checkout"],
          "spec": "https://ucp.dev/2026-04-08/specification/discount",
          "schema": "https://ucp.dev/2026-04-08/schemas/shopping/discount.json"
        }
      ]
    }
  }
}

التأثير في البنود الإعلانية والمجاميع

تظهر الخصومات المطبّقة في حقول الدفع الأساسية باستخدام نوعَين مختلفَين من المجاميع. إذا كان لأحد الخصومات allocations تشير إلى بنود إعلانية، يساهم ذلك في items_discount. تساهم الخصومات بدون عمليات تخصيص أو التي يتم تخصيصها للشحن أو الرسوم في discount.

نوع الخصم	نوع المجموع	مكان الظهور
خصم على البند الإعلاني	items_discount	line_items[].totals[type=items_discount]
خصم على مستوى الطلب	discount	totals[type=discount]

متطلبات الإصدار:

بالنسبة إلى الإصدار 2026-04-08، يجب أن تستخدم إدخالات الخصومات في totals[] و line_items[].totals[] قيمًا سالبة لعكس تأثيرها على الإيصال. تبقى المبالغ داخل مصفوفتَي discounts.applied وallocations دائمًا أعدادًا صحيحة موجبة.

أمثلة على واجهة برمجة التطبيقات للعروض الترويجية المطبّقة تلقائيًا

تعرض الأمثلة التالية الخصومات المطبّقة تلقائيًا. لا تحتوي حمولات الطلبات على مصفوفة discounts.codes، ولكن تتضمّن الردود "automatic": true وتحذف الحقل code.

خصم على مستوى السلعة يتم تطبيقه تلقائيًا

خصم بنسبة% 10 على مستوى الموقع الإلكتروني يتم تطبيقه تلقائيًا على بند إعلاني معيّن.

مثال على الطلب:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1
    }
  ]
}

مثال على الردّ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "Sneakers", "price": 10000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 10000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 9000}
      ]
    }
  ],
  "discounts": {
    "applied": [
      {
        "title": "10% Off Sitewide Sale",
        "amount": 1000,
        "automatic": true,
        "method": "each",
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1000}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 9000}
  ]
}

خصم على مستوى الطلب يتم تطبيقه تلقائيًا

قاعدة ترويجية (مثل "خصم بقيمة 10 دولارات أمريكية على الطلبات التي تزيد قيمتها عن 50 دولارًا أمريكيًا") يتم تطبيقها على الطلب ككل بدون تخصيصات محدّدة على مستوى البند الإعلاني.

مثال على الطلب:

{
  "line_items": [ ... ]
}

مثال على الردّ:

{
  "line_items": [ ... ],
  "discounts": {
    "applied": [
      {
        "title": "$10 Off Orders Over $50",
        "amount": 1000,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 6000},
    {"type": "discount", "display_text": "Order Promo", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 5000}
  ]
}

أمثلة على واجهة برمجة التطبيقات للعروض الترويجية التي يطبّقها المستخدم

تعرض الأمثلة التالية الخصومات التي يتم تفعيلها عندما يُدخل المستخدم رمزًا ترويجيًا. تتضمّن حمولات الطلبات الرموز المطلوبة، وتعرض الردود هذه الرموز مع تخصيص المبالغ المطبّقة.

خصم على مستوى الطلب

خصم ثابت يتم تطبيقه على إجمالي الطلب. لا يلزم إجراء عمليات تخصيص، ويتم تطبيق الخصم على الطلب ككل ويستخدم type: "discount".

مثال على الطلب:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"]
  }
}

مثال على الردّ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ]
}

خصومات مختلطة (على مستوى السلعة والطلب)

يعرض هذا المثال نوعَي الخصم: خصم على مستوى السلعة (خصم بنسبة% 20) يتم تخصيصه للبنود الإعلانية، وخصم تلقائي على الشحن على مستوى الطلب.

مثال على الطلب:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20"]
  }
}

مثال على الردّ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 2000 },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -800},
        {"type": "total", "amount": 3200}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 800,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 800}
        ]
      },
      {
        "title": "Free shipping on orders over $30",
        "amount": 599,
        "automatic": true
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 4000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -800},
    {"type": "discount", "display_text": "Order Discounts", "amount": -599},
    {"type": "fulfillment", "display_text": "Shipping", "amount": 0},
    {"type": "total", "display_text": "Total", "amount": 2601}
  ]
}

رمز خصم مرفوض

عندما يكون الرمز غير صالح، يتم عرضه في codes ولكن يتم حذفه من applied. يتم إبلاغ الرفض باستخدام warning في مصفوفة messages[].

مثال على الطلب:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"]
  }
}

مثال على الردّ:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SAVE10", "EXPIRED50"],
    "applied": [
      {
        "code": "SAVE10",
        "title": "$10 Off Your Order",
        "amount": 1000
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 5000},
    {"type": "discount", "display_text": "Order Discount", "amount": -1000},
    {"type": "total", "display_text": "Total", "amount": 4000}
  ],
  "messages": [
    {
      "type": "warning",
      "code": "discount_code_expired",
      "path": "$.discounts.codes[1]",
      "content": "Code 'EXPIRED50' expired on December 1st"
    }
  ]
}

خصومات مجمّعة مع عمليات تخصيص

يتم تطبيق خصومات متعدّدة مع تفاصيل كاملة لعمليات التخصيص.

ملاحظة: يحدّد الحقلان priority وmethod ترتيب عملية الاحتساب.

مثال على الطلب:

{
  "line_items": [ ... ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"]
  }
}

مثال على الردّ:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "title": "T-Shirt", "price": 6000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 6000},
        {"type": "items_discount", "amount": -1500},
        {"type": "total", "amount": 4500}
      ]
    },
    {
      "id": "li_2",
      "item": { "title": "Socks", "price": 4000 },
      "quantity": 1,
      "totals": [
        {"type": "subtotal", "amount": 4000},
        {"type": "items_discount", "amount": -1000},
        {"type": "total", "amount": 3000}
      ]
    }
  ],
  "discounts": {
    "codes": ["SUMMER20", "EXTRA5"],
    "applied": [
      {
        "code": "SUMMER20",
        "title": "Summer Sale 20% Off",
        "amount": 2000,
        "method": "each",
        "priority": 1,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 1200},
          {"path": "$.line_items[1]", "amount": 800}
        ]
      },
      {
        "code": "EXTRA5",
        "title": "Extra $5 Off",
        "amount": 500,
        "method": "across",
        "priority": 2,
        "allocations": [
          {"path": "$.line_items[0]", "amount": 300},
          {"path": "$.line_items[1]", "amount": 200}
        ]
      }
    ]
  },
  "totals": [
    {"type": "subtotal", "display_text": "Subtotal", "amount": 10000},
    {"type": "items_discount", "display_text": "Item Discounts", "amount": -2500},
    {"type": "total", "display_text": "Total", "amount": 7500}
  ]
}