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

البداية

المصادقة والمفاتيح

كل طلب إلى الواجهة يحمل مفتاح شريك في الترويسة Authorization. يحدد المفتاح من أنت، وفي أي بيئة، وماذا يحق لك.

HTTP
GET /partner/v1/me HTTP/1.1
Host: <base address>
Authorization: Bearer lpk_test_…

يُحفظ المفتاح لدينا مشفّراً بدالة SHA-256 ولا يمكن عرضه مرة أخرى. إذا ضاع فاطلب مفتاحاً جديداً.

OAuth 2.0 بدل المفتاح الثابت#

لنظام يفضّل OAuth: اطلب رمز وصول بنوع client_credentials، حيث client_id هو معرّف مفتاحك (key.id في GET /partner/v1/me) وclient_secret هو المفتاح نفسه، في جسم JSON أو نموذج (form) أو بمصادقة Basic. يأتيك رمز lpt_… صالح لساعة واحدة (ولا يتجاوز تاريخ انتهاء المفتاح) بصلاحيات المفتاح نفسها، وترسله في Authorization: Bearer تماماً كالمفتاح.

curl · HTTP Basic
curl -sS -u "$LP_KEY_ID:$LP_API_KEY" \
  -d grant_type=client_credentials \
  "$LP_BASE_URL/partner/v1/oauth/token"
curl -sS -X POST "$LP_BASE_URL/partner/v1/oauth/token" \
  -H "Content-Type: application/json" \
  --data '{
  "grant_type": "client_credentials",
  "client_id": "key_01JD5ZC9",
  "client_secret": "lpk_test_…"
}'
200 · PartnerTokenResponse
{
  "access_token": "lpt_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "branches:read catalog:read catalog:write availability:write orders:read orders:ack orders:status orders:cancel orders:events payments:read reports:read webhooks:manage mappings:write"
}
  • إلغاء المفتاح يوقف رموزه فوراً.
  • الرفض يحمل السبب في detail.error: invalid_client · unsupported_grant_type · invalid_request.
  • اطلب رمزاً جديداً قبل انتهاء expires_in بدقيقة، ولا تطلب رمزاً لكل طلب.

البيئتان لا تختلطان#

البادئةالبيئةيعمل على
lpk_test_…sandboxبيئة الاختبار فقط
lpk_live_…liveالإنتاج فقط

مفتاح على البيئة الأخرى يُرفض بالرمز 401 KEY_ENVIRONMENT_MISMATCH. لذلك لا يمكن لإعداد اختبار أن يغيّر بيانات الإنتاج خطأً. المزيد عن البيئات.

الصلاحيات#

كل مفتاح يحمل قائمة صلاحيات. صلاحيات القراءة لا تغيّر شيئاً، وكل صلاحية كتابة تفتح عائلة واحدة من الطلبات. طلب بلا الصلاحية اللازمة يُرفض بالرمز 403 SCOPE_REQUIRED، وتجد الصلاحيات المطلوبة في detail.required.

الصلاحيةما تسمح بهافتراضية لـ
branches:readقراءة الفروع المسموح بها للمفتاح: الاسم والموقع وطرق الاستلام والإيقاف المؤقت ورمز الفرع لديك.نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)أسطول توصيلمنصة طلباتنظام محاسبةتحليلات وتقاريرنظام آخر
catalog:readقراءة المنيو المنشور: الأقسام والأصناف والأحجام والإضافات والأسعار، مع رموزك لما رُبط منها.نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)منصة طلباتتحليلات وتقارير
catalog:writeإرسال المنيو من نظامك (عندما يكون نظامك مصدر المنيو). يُحفظ مسودةً أو يُنشر بحسب سياسة النشر.نظام تخطيط الموارد (ERP)
availability:writeإيقاف صنف أو إضافة في فرع عند نفادها وإعادتها. لا يلغي إيقافاً وضعه موظفو الفرع.نظام تخطيط الموارد (ERP)نقاط البيع (POS)
orders:readقراءة الطلبات: الطلبات الجديدة بالسحب، وتفاصيل أي طلب يخص فروعك.نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)أسطول توصيلنظام محاسبةتحليلات وتقارير
orders:ackتأكيد استلام الطلب في نظامك، مع رقمك الخاص له إن وُجد.نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)
orders:statusإبلاغ حالة الطلب (قبول، تحضير، جاهز، مع المندوب…) ضمن الحالات المسموحة لك.نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)أسطول توصيل
orders:cancelطلب إلغاء طلب، مثل اتصال العميل بالفرع أو تعذّر التحضير.نظام تخطيط الموارد (ERP)نقاط البيع (POS)
orders:eventsتسجيل وقائع على الطلب دون تغيير حالته، مثل إصدار الإيصال أو تحصيل المبلغ عند الباب.نظام تخطيط الموارد (ERP)نقاط البيع (POS)أسطول توصيل
payments:readقراءة طريقة دفع الطلب وما حُصّل منه وما رُدّ.نظام تخطيط الموارد (ERP)نقاط البيع (POS)نظام محاسبة
reports:readقراءة تقارير المطابقة اليومية: عدد الطلبات ومبالغها لكل فرع.نظام تخطيط الموارد (ERP)نظام محاسبةتحليلات وتقارير
webhooks:manageإدارة اشتراكات Webhook الخاصة بك: العناوين والأحداث والفروع.نظام تخطيط الموارد (ERP)نقاط البيع (POS)أسطول توصيلمنصة طلباتنظام محاسبة
mappings:writeإرسال جدول الربط بين معرّفات ليتس بيتزا ورموز نظامك (الفروع والأصناف والإضافات وطرق الدفع).نظام تخطيط الموارد (ERP)نقاط البيع (POS)شاشة المطبخ (KDS)

العمود الأخير هو ما يحصل عليه المفتاح الجديد لكل نوع نظام ما لم نحدد غير ذلك. نصدر المفتاح بأقل صلاحيات يحتاجها نظامك.

الفروع#

يمكن قصر المفتاح على فروع محددة (حتى 200 فرع). القيمة null في key.branches تعني كل الفروع. أي طلب يخص فرعاً خارج القائمة يُرفض بالرمز 403 BRANCH_NOT_ALLOWED.

قائمة العناوين المسموحة#

عند الطلب نقصر المفتاح على عناوين IP أو نطاقات CIDR محددة (حتى 50 مدخلاً). أرسل لنا عناوين الخروج الثابتة لخوادمك. طلب من عنوان آخر يُرفض بالرمز 403 IP_NOT_ALLOWED. القائمة الفارغة تعني أي عنوان.

حدود الطلبات#

لكل مفتاح عدد طلبات في الدقيقة (بين 10 و6000)، تجده في key.ratePerMinute. كل رد ناجح يحمل:

HTTP
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42

عند تجاوز الحد يأتي الرد 429 RATE_LIMITED مع الترويسة Retry-After (وفي detail.retryAfterSeconds). انتظر المدة المذكورة ثم أعد المحاولة، ولا تكرر الطلب فوراً.

تدوير المفاتيح وانتهاؤها#

قد يحمل المفتاح تاريخ انتهاء (حتى 730 يوماً) تجده في key.expiresAt. بعده يُرفض بالرمز 401 KEY_EXPIRED.

  1. اطلب مفتاحاً ثانياً للبيئة نفسها.

    يعمل المفتاحان معاً، فلا توقف للخدمة.
  2. انشر المفتاح الجديد في نظامك.

    تحقق بطلب GET /partner/v1/me أن key.id هو الجديد.
  3. اطلب إلغاء المفتاح القديم.

    يتوقف فوراً، وأي طلب به يُرفض بالرمز UNAUTHENTICATED.

ترتيب الفحوص#

  1. مفتاح معروف وغير ملغى، وإلا UNAUTHENTICATED (401).
  2. بيئة المفتاح هي بيئة الخادم، وإلا KEY_ENVIRONMENT_MISMATCH (401).
  3. غير منتهٍ، وإلا KEY_EXPIRED (401). الشريك نشط، وإلا PARTNER_SUSPENDED (403).
  4. العنوان ضمن القائمة المسموحة إن وُجدت، وإلا IP_NOT_ALLOWED (403).
  5. ضمن حد الطلبات، وإلا RATE_LIMITED (429).
  6. يحمل صلاحيات الطلب، وإلا SCOPE_REQUIRED (403).