البداية
المصادقة والمفاتيح
كل طلب إلى الواجهة يحمل مفتاح شريك في الترويسة Authorization. يحدد المفتاح من أنت، وفي أي بيئة، وماذا يحق لك.
إرسال المفتاح#
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 -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_…"
}'{
"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. كل رد ناجح يحمل:
RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 42عند تجاوز الحد يأتي الرد 429 RATE_LIMITED مع الترويسة Retry-After (وفي detail.retryAfterSeconds). انتظر المدة المذكورة ثم أعد المحاولة، ولا تكرر الطلب فوراً.
تدوير المفاتيح وانتهاؤها#
قد يحمل المفتاح تاريخ انتهاء (حتى 730 يوماً) تجده في key.expiresAt. بعده يُرفض بالرمز 401 KEY_EXPIRED.
اطلب مفتاحاً ثانياً للبيئة نفسها.
يعمل المفتاحان معاً، فلا توقف للخدمة.انشر المفتاح الجديد في نظامك.
تحقق بطلب GET /partner/v1/me أن key.id هو الجديد.اطلب إلغاء المفتاح القديم.
يتوقف فوراً، وأي طلب به يُرفض بالرمز UNAUTHENTICATED.
ترتيب الفحوص#
- مفتاح معروف وغير ملغى، وإلا UNAUTHENTICATED (401).
- بيئة المفتاح هي بيئة الخادم، وإلا KEY_ENVIRONMENT_MISMATCH (401).
- غير منتهٍ، وإلا KEY_EXPIRED (401). الشريك نشط، وإلا PARTNER_SUSPENDED (403).
- العنوان ضمن القائمة المسموحة إن وُجدت، وإلا IP_NOT_ALLOWED (403).
- ضمن حد الطلبات، وإلا RATE_LIMITED (429).
- يحمل صلاحيات الطلب، وإلا SCOPE_REQUIRED (403).