أفضل الممارسات

​

المصادقة

• أدرج دائماً الأسرار في sensitiveKeys — لا تُرسل إلى المتصفح أبداً
• استخدم OAuth 2.0 مع auto_refresh: true عندما يصدر مزوّدك رموز تحديث
• خزّن أسرار توقيع الويب هوك في بيانات الاعتماد أو auth.config وأشر إليها عبر secretKey
• وثّق القيم التي يجب أن يوفّرها المستأجرون مقابل معرّفات عميل OAuth التي تديرها كرزون

​

الإجراءات

• استخدم renderStrategy: 'auto' حتى تُولَّد النماذج من JSON Schema في parameters
• استخدم مصادر RPC (x-source) للمعرّفات التي لا يجب أن يلصقها المستخدمون يدوياً
• عيّن دائماً x-fallback: 'input' عندما قد تفشل مصادر RPC
• تسلسل الطلبات عندما تحتاج الخطوات اللاحقة معرّفات من استجابات سابقة
• استخدم mapping كمصفوفة على الطلبات الوسيطة، وmapping ككائن على الاستجابة النهائية

​

المشغّلات

• طابق سلسلة الحدث الدقيقة التي ينتجها استخراج الويب هوك
• اكتب نصاً واضحاً لـ label وdescription لمنشئ الأتمتة
• استخدم أسماء أيقونات Lucide لـ icon

​

الويب هوك

• اطلب التحقق بـ HMAC في الإنتاج (hmac-sha256 عند الدعم)
• عيّن transactionId لإزالة تكرار إعادة المحاولة من المزوّد
• استجب بـ response.statusCode: 200 وجسم أدنى — تؤكّد كرزون بسرعة

​

التجارة الإلكترونية

• استخدم المزامنة للاستيراد الجماعي والمعالجات الفورية
• حاذي مفاتيح sync.webhooks.handlers مع triggers[].event
• استخدم joinCodes لمصفوفات الخصم وmapItems لبنود السطر
• استخدم customerExtraction.overrides عندما يختلف JSON العميل لكل حدث

​

الأمان والتقديم

• لا تضمّن أسرار إنتاج المستأجر في JSON المقدَّم
• وثّق حسابات اختبار بيئة الاختبار للمراجعين
• أبقِ docsUrl مشيراً إلى دليل تكاملك للمستخدمين النهائيين
• زد version مع كل تغيير معتمد