الأدلة
المنيو من نظامك
يُكتب الصنف والسعر مرة واحدة في نظامك. نحن نستورده، ونقارنه بما يراه العملاء، وننشره بحسب سياسة النشر المتفق عليها.
سير العمل#
- نظامك ← ليتس بيتزايرسل المنيو أو التغييرات
POST /partner/v1/catalog/imports - ليتس بيتزايربط الرموز ويفحص ويقارن (مسودة)
- ليتس بيتزا ← نظامكنتيجة الاستيراد والمشكلات
- ليتس بيتزايُنشر يدوياً أو تلقائياً حسب السياسة
- ليتس بيتزا ← العميلالموقع والتطبيق يعرضان المنيو الجديد
من يملك ماذا#
| البيان | المرجع |
|---|---|
| الصنف واسمه وسعره وأحجامه وإضافاته وقواعد الاختيار | نظامك (الحقول التي يملكها) |
| الصور وترتيب العرض والأقسام والوسوم والعروض التسويقية | لوحة تحكم ليتس بيتزا |
| رسوم «اصنع بيتزتك» وقواعدها | لوحة تحكم ليتس بيتزا |
| الفروع وأوقات العمل ومناطق التوصيل ورسومه | لوحة تحكم ليتس بيتزا |
الحقول التي يمكن أن يملكها نظامك: 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)، وفي المنيو الكامل الصنف المربوط الذي لم تعد تذكره، يُوقف في فروعك المفعّلة ولا يُحذف أبداً.
{
"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.
{
"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"
}
]
}
}الطلبات المستخدمة#
ما يحمل «قريباً» ليس منشوراً بعد في الواجهة، ويُضاف إلى المرجع فور نشره.
- GET
/partner/v1/catalogالمنيو المنشور ورموزكcatalog:readمتاح - POST
/partner/v1/catalog/importsإرسال المنيو من نظامكcatalog:writeمتاح - GET
/partner/v1/catalog/importsآخر ما أرسلت من منيوcatalog:writeمتاح - GET
/partner/v1/catalog/imports/{id}تقرير استيراد واحدcatalog:writeمتاح - GET
/partner/v1/mappingsرموزك المربوطة بمعرّفاتناcatalog:readمتاح - PUT
/partner/v1/mappingsجدول ربط الرموزmappings:writeمتاح - GET
/partner/v1/branchesفروعك ورموزها لديكbranches:readمتاح