مطوّرو ليتس بيتزاv1.0.0

الأدلة

المنيو من نظامك

يُكتب الصنف والسعر مرة واحدة في نظامك. نحن نستورده، ونقارنه بما يراه العملاء، وننشره بحسب سياسة النشر المتفق عليها.

سير العمل#

  1. نظامك ← ليتس بيتزايرسل المنيو أو التغييراتPOST /partner/v1/catalog/imports
  2. ليتس بيتزايربط الرموز ويفحص ويقارن (مسودة)
  3. ليتس بيتزا ← نظامكنتيجة الاستيراد والمشكلات
  4. ليتس بيتزايُنشر يدوياً أو تلقائياً حسب السياسة
  5. ليتس بيتزا ← العميلالموقع والتطبيق يعرضان المنيو الجديد

من يملك ماذا#

البيانالمرجع
الصنف واسمه وسعره وأحجامه وإضافاته وقواعد الاختيارنظامك (الحقول التي يملكها)
الصور وترتيب العرض والأقسام والوسوم والعروض التسويقيةلوحة تحكم ليتس بيتزا
رسوم «اصنع بيتزتك» وقواعدهالوحة تحكم ليتس بيتزا
الفروع وأوقات العمل ومناطق التوصيل ورسومهلوحة تحكم ليتس بيتزا

الحقول التي يمكن أن يملكها نظامك: names · descriptions · prices · sizes · groups · options · categories · availability. قائمتك في settings.catalog.fields.

النشر#

settings.catalog.publishما يحدث
manualيصبح المنيو مسودة يراجعها شخص في لوحة التحكم وينشرها.
auto_pricesتغيّر الأسعار وحده يُنشر تلقائياً ضمن maxPriceChangePct، وأي تغيير آخر ينتظر المراجعة.
autoيُنشر عند نجاح الفحوص بشرط ألا يختفي أكثر من maxRemovals صنفاً.

تقرير الاستيراد#

كل إرسال يعيد تقريراً (CatalogImport) فيه حالته وسببه، والعدّ، والرموز غير المربوطة (unknown)، وما أُوقف، ونتائج الفحص (issues)، والفرق عمّا يراه العملاء (diff). أرسل المنيو كاملاً full أو التغييرات فقط delta، وdryRun يعيد التقرير دون أن يحفظ شيئاً.

statusالمعنىالأسباب
rejectedفشلت الفحوص فلم يتغيّر شيء. أصلح ما في issues وأعد الإرسال.CHECKS_FAILED
stagedمحفوظ ينتظر مراجعة فريق ليتس بيتزا.REVIEW_REQUIREDNOT_PRICE_ONLYPRICE_CHANGE_TOO_LARGETOO_MANY_REMOVALS
publishedنُشر ويراه العملاء الآن (أو لم يكن فيه تغيير).NO_CHANGE أو بلا سبب
discardedرفضه فريق ليتس بيتزا عند المراجعة.—
supersededحلّ محله منيو أحدث أرسلته قبل مراجعته.—

في التشغيل التجريبي يبدأ السبب بـ DRY_RUN. وإذا لم تكن إعداداتك تجعلك مصدر المنيو فالرد 403 CATALOG_SOURCE_REQUIRED.

  • يتغيّر فقط ما تسمح به settings.catalog.fields. الصور و«اصنع بيتزتك» والترتيب والأقسام تبقى لليتس بيتزا.
  • الصنف المحجوب (blocked)، وفي المنيو الكامل الصنف المربوط الذي لم تعد تذكره، يُوقف في فروعك المفعّلة ولا يُحذف أبداً.
POST /partner/v1/catalog/imports · PartnerMenu
{
  "mode": "full",
  "dryRun": true,
  "categories": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "sortOrder": 0,
      "blocked": true
    }
  ],
  "items": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "descriptionAr": "string",
      "descriptionEn": "string",
      "categoryCode": "string",
      "price": 0,
      "variants": [
        {
          "code": "string",
          "price": 0,
          "blocked": true
        }
      ],
      "groupCodes": [
        "string"
      ],
      "blocked": true
    }
  ],
  "groups": [
    {
      "code": "string",
      "nameAr": "string",
      "nameEn": "string",
      "minSelect": 0,
      "maxSelect": 1,
      "maxPerOption": 1,
      "options": [
        {
          "code": "string",
          "nameAr": "string",
          "nameEn": "string",
          "price": 0,
          "pricesBySize": {
            "medium": 0,
            "large": 0
          },
          "blocked": true
        }
      ]
    }
  ]
}

ربط الرموز#

لا يغيّر أي طرف معرّفاته. كل فرع وقسم وصنف ومجموعة وإضافة وطريقة دفع لدينا يُربط برمزك في جدول ربط لكل بيئة.

  • PUT /partner/v1/mappings كلّه أو لا شيء: سطر خاطئ واحد يرفض الطلب كله بالرمز 422 MAPPINGS_REFUSED ولا يتغيّر شيء. في detail.errors[] لكل سطر مخالف: رقمه (index) والرمز (UNKNOWN_ID أو DUPLICATE_ROW أو CODE_TAKEN) والحقل والقيمة. هذا الرفض لا يُحفظ جواباً لمفتاح Idempotency-Key، فتستطيع إعادة الطلب المصحَّح بالمفتاح نفسه.
  • merge يضيف الأسطر المرسلة ويستبدلها، وreplace يحذف أيضاً ما لم تذكره من الأنواع المرسلة، وdryRun يفحص ويعدّ فقط.
  • الطلب الذي يحمل فرعاً أو صنفاً أو إضافة بلا ربط يصلك مع ذلك، وتجد الناقص في external.unmapped.
422 · PartnerError
{
  "code": "MAPPINGS_REFUSED",
  "message": {
    "ar": "رُفض طلب الربط كاملاً ولم يتغيّر شيء: راجع detail.errors.",
    "en": "The mapping request was refused whole and nothing changed: see detail.errors."
  },
  "field": null,
  "retryable": false,
  "requestId": "req_01JD7Q8W3K2M",
  "detail": {
    "errors": [
      {
        "index": 3,
        "code": "UNKNOWN_ID",
        "field": "id",
        "value": "99999"
      }
    ]
  }
}

الطلبات المستخدمة#

ما يحمل «قريباً» ليس منشوراً بعد في الواجهة، ويُضاف إلى المرجع فور نشره.