البداية
الأعراف المشتركة
قواعد تسري على كل طلب ورد في الواجهة. اقرأها مرة واحدة ووفّر على نفسك كثيراً من الأخطاء.
JSON وUTF-8#
كل الأجسام JSON بترميز UTF-8. النص العربي يصل كما هو دون تحويل. أرسل Content-Type: application/json مع كل طلب كتابة.
المبالغ بالهللة شاملة الضريبة#
كل مبلغ عدد صحيح بالهللة (الريال = 100 هللة)، وشامل ضريبة القيمة المضافة 15٪. لا كسور عشرية ولا أخطاء تقريب.
| في الواجهة | يعني |
|---|---|
4200 | 42 |
1487 | ضريبة داخل 114: 14.87 |
14490 | 144.90 |
مثال من طلب حقيقي التسعير (فرع التخصصي):
{
"subtotal": 9600,
"deliveryFee": 1800,
"total": 11400,
"vat": {
"rateBps": 1500,
"amount": 1487,
"includesDeliveryFee": true
}
}النصوص بلغتين#
كل نص يُعرض للعميل يأتي كائناً فيه العربية والإنجليزية. اعرض اللغة التي يختارها مستخدمك.
{
"ar": "التخصصي",
"en": "At Takhassusi"
}الأوقات#
الأوقات بصيغة ISO 8601 مع فرق التوقيت، مثل 2026-11-19T19:30:12+03:00. الفروع تعمل بتوقيت الرياض. قارن الأوقات بقيمتها لا بنصها.
المعرّفات والرموز الخارجية#
معرّفات ليتس بيتزا ثابتة لا تتغيّر ولا يُعاد استخدامها: الفرع 28، والصنف 649 (مارقريتا كبيرة). رموز نظامك تُربط بها في جدول ربط لكل بيئة، فلا يحتاج أي طرف إلى تغيير معرّفاته.
في الردود يظهر رمزك في حقول مثل externalCode، وقيمته null حتى يُربط.
مفتاح عدم التكرار#
كل طلب كتابة يحمل الترويسة Idempotency-Key (حتى 128 حرفاً). إعادة الطلب بالمفتاح نفسه والجسم نفسه تعيد الرد الأول دون أن تنفّذ شيئاً مرة ثانية. لذلك تستطيع إعادة المحاولة بأمان بعد انقطاع الشبكة.
POST /partner/v1/orders/{id}/ack HTTP/1.1
Authorization: Bearer lpk_test_…
Idempotency-Key: 6f1d2c3e-0b8a-4f5e-9c7d-1a2b3c4d5e6f
Content-Type: application/json| الحالة | الرد |
|---|---|
| بلا مفتاح | IDEMPOTENCY_KEY_REQUIRED |
| المفتاح نفسه والجسم نفسه | الرد الأول كما هو |
| المفتاح نفسه بجسم مختلف | IDEMPOTENCY_KEY_REUSED |
رقم الطلب X-Request-Id#
كل رد يحمل X-Request-Id. تستطيع إرسال رقمك الخاص (من 8 إلى 64 حرفاً من A-Z a-z 0-9 . _ -) لتتبع الطلب من طرف إلى طرف، وإلا أنشأنا رقماً. سجّله مع كل خطأ واذكره للدعم.
الترقيم بالمؤشر#
القوائم الطويلة تُقرأ صفحةً صفحة: يحمل الرد nextCursor، أرسله في الطلب التالي كما هو حتى تصبح قيمته null. المؤشر نص معتم: لا تبنه ولا تفسّره.
{
"items": [
"…"
],
"nextCursor": "eyJhZnRlciI6MTA0Mn0"
}الإصدارات والإيقاف#
الإصدار جزء من المسار: /partner/v1. داخل الإصدار 1 قد نضيف حقولاً وطلبات وأحداثاً وقيماً جديدة، فتجاهل ما لا تعرفه. أي تغيير يكسر التوافق يأتي في /partner/v2 ونعلن عنه مسبقاً.
الطلب الذي سيتوقف يحمل الترويستين Deprecation وSunset (تاريخ التوقف)، ويُذكر في سجل التغييرات.