العقد للغات الأخرى
كل ما يحتاجه تنفيذ بـ PHP أو Python أو Go ليخاطب دكان تماماً كالحزمة الرسمية: مستند OpenAPI، ومتجهات الاختبار، والغلاف، ومخطط الإعداد.
هذه الصفحة لمن ينفّذ دعم دكان خارج Node: حزمة PHP، أو عميل Python، أو خدمة Go. في نهايتها تعرف الأعمال الأربعة التي تثبّت العقد، وأين يُنشر كل منها، وكيف تثبت أن تنفيذاً ما يطابق الحزمة الرسمية بايتاً ببايت.
تُولَّد الحزمة الرسمية @dukkan.one/app-sdk وتُختبر من هذه الأعمال نفسها، فالتنفيذ الذي يعيد إنتاجها يتصرّف بالطريقة نفسها. لا شيء هنا خاص بـ Node.
الأعمال الأربعة#
| العمل | يُنشر على | يثبّت |
|---|---|---|
| مستند OpenAPI | /platform-api-v1.yaml |
كل عملية ومخطط وخطأ، وقائمة المواضيع بنطاقاتها المطلوبة (x-dukkan-topic-scopes)، ومخطط حمولة كل موضوع (x-dukkan-topic-payloads)، ومصفوفة حالات الطلب (x-dukkan-order-status-transitions)، والمراجعة المؤرّخة (x-dukkan-api-version). |
| متجهات الاختبار | /contracts/v1/index.json |
القيم المتوقعة للتوقيع وPKCE وJSON القانوني والغلاف ودلالات أخطاء نقطة نهاية الرموز. |
| مخطط الإعداد | /contracts/v1/dukkan.app.schema.json |
JSON Schema لملف dukkan.app.toml، لتتحقق أداة بأي لغة من الملف نفسه. |
| الغلاف | Webhooks ومتجه envelope.json |
الجسم الموقّع الذي يشترك فيه كل تسليم. |
يسرد index.json كل ملف مع sha256 الخاص به ومراجعة الواجهة التي ينتمي إليها. ثبّت تلك البصمات في مستودعك؛ أي تغيير هو تغيير عقد مراجَع في جانب دكان ويظهر في سجل التغييرات.
متجهات الاختبار#
كل ملف متجهات مجموعة مدخلات مع القيمة التي تحسبها المنصّة. يكون التنفيذ صحيحاً عندما تتطابق كل قيمة متوقعة تماماً.
| الملف | ما يثبته |
|---|---|
webhook-signing.json |
hex(HMAC-SHA256(secret, timestamp + "." + body)) على عدة أجسام، منها غير ASCII وحساسة للمسافات، مع أسماء الترويسات الدقيقة. |
pkce.json |
تحديات S256 لمحقّقات معطاة وأبجدية المحقّق. |
canonical-json.json |
التسلسل بمفاتيح مرتّبة وبلا مسافات في كل عمق، وsha256 الذي تقارنه المنصّة عندما يصل Idempotency-Key نفسه بجسم مختلف. |
envelope.json |
غلاف إنتاج وغلاف test: true، مسلسلين، مع أغلفة يجب رفضها (api_version خاطئ، أو install_id ناقص، أو sequence غير صالح). |
oauth-errors.json |
رموز أخطاء نقطة نهاية الرموز، ومهلة الـ 30 ثانية لإعادة استخدام رمز التحديث، والحقول التي يحملها النجاح. |
idempotency-key.json |
اشتقاق Idempotency-Key الحتمي (namespace-sha256(قائمة JSON من مساحة الاسم والأجزاء))، فتبقى المهمة المنقولة بين اللغات تعيد الكتابة المسجّلة نفسها. |
curl -s https://developer.dukkan.one/contracts/v1/vectors/webhook-signing.json | head -c 400تشغّل الحزمة الرسمية هذه المتجهات في حزمة اختباراتها؛ وينبغي أن تفعل أي نسخة منقولة الشيء نفسه في CI ليُكتشف أي انحراف في أي من الجانبين قبل أن يراه تاجر.
سلوك لا تستطيع المتجهات تثبيته#
بعض القواعد تتعلق بالتسلسل لا بالقيم. النسخة الأمينة تنفّذها كلها:
- التجديد تحت قفل. تلغي المنصّة التثبيت عندما يُقدَّم رمز تحديث مدوَّر مرة ثانية. سلسِل التجديدات لكل تثبيت عبر العمليات؛ أعد قراءة الرمز المخزّن داخل القفل وتجاوز التجديد عندما تكون نسخة شقيقة دوّرته أصلاً. يحصل
invalid_grantعلى إعادة قراءة واحدة تحديداً قبل تعليم التثبيت على أنه يحتاج إعادة اتصال. - تحقّق على البايتات الخام ثم حلّل. لا تُعِد التسلسل أبداً. ارفض الطوابع الزمنية خارج 5 دقائق والأجسام الأكبر من 256 KB قبل لمس JSON.
- اربط بـ
install_idالموقّع. ترويسةX-Dukkan-Install-Idتلميح للبحث؛ وinstall_idفي الغلاف هو الفيصل، ويجب أن يكون التثبيت الذي تحقّق سرّه. - أزل التكرار على
idالموقّع، لا على ترويسة التسليم، وأجب ضمن المهلة قبل المعالجة. - تحمل كل كتابة
Idempotency-Key، معاداً عبر محاولاتك أنت؛ ولا تُعاد سوى القراءات والكتابات الآمنة للتكرار عند429و5xx، مع احترامRetry-After. - تبقى المبالغ أعداداً صحيحة. قِس بـ
decimalsالخاص بكل قيمة؛ والقسمة الوحيدة عند العرض (المبالغ). - إصدارات إضافية. يجب ألا تفشل الحقول والمواضيع غير المعروفة في التحليل (مرجع الواجهة).
توليد عميل#
يصرّح مستند OpenAPI بـ operationId لكل عملية، فينتج أي مولّد أسماء دوال ثابتة (listOrders وupdateOrderStatus وupsertWebhookSubscription). يُولَّد العميل المنمّط في الحزمة الرسمية من المعرّفات نفسها؛ ويعرض مرجع حزمة التطبيقات السطح الناتج الذي تستطيع نسخة منقولة أن تعكسه واحداً لواحد.