ConnectWiz + API وWebhooks
تكامل يعملالواجهة التي نبيعها هي الواجهة التي نستخدمها
المنصّة كلها موصوفة في عقد OpenAPI واحد تُولَّد منه لوحتنا وتطبيقنا على الجوال — بلا نقاط نهاية خفيّة، وبلا انحراف في الوثائق. وفوقه: مفاتيح Commerce API محدودة الصلاحيات، ومشغّلات webhook مؤمَّنة، ومسارات تستدعي أنظمتكم.
المطوّرون
ماذا يفعل، بالضبط
عقد مرجعيّ واحد
مستند OpenAPI 3 واحد يصف المنصّة؛ وعملاؤنا البرمجيون بلغة TypeScript يُولَّدون منه — فلا تستطيع الوثائق أن تنحرف عن الواقع، لأن الواقع مبنيّ من الوثائق.
مفاتيح Commerce API
مفاتيح يصدرها المستأجر بصلاحيات صريحة — قراءة الكتالوج، وقراءة الطلبات، وكتابة الطلبات — تشغّل واجهة متجركم أو تطبيقكم على محرّك الطلبات نفسه، مع تحديد الأسعار دائمًا على الخادم.
نقاط webhook الواردة، مؤمَّنة
لكل مشغّل webhook في مسار عنوانه وسرّه، وتحقّق بـHMAC على الجسم الخام، وحماية من إعادة التشغيل. والحمولة تستطيع أن تسمّي شخصًا؛ لكنها لا تستطيع أبدًا أن توجّه دواخل المسار.
الصادر عبر المسارات
خطوة REST تستدعي أنظمتكم في اللحظات التي ترسمونها على اللوحة بالضبط — طلب قُدِّم، أو موافقة مُنحت، أو حجز تمّ.
الجانب التقني
مواقف تصميمية في الـAPI، معلَنة
الأسعار لا تأتي من العميل البرمجي أبدًا
طلب الشراء يقول ماذا وكم — أما الاسم والسعر فيُقرآن من الكتالوج في تلك اللحظة، على الخادم، ويُكتبان على البند لقطةً ثابتة. فالطلب المُتلاعَب به لا يستطيع اختراع خصم.
القدرات قبل الاستدعاءات
كل سطح تكامل ينشر عقد قدرات — هل يطابق بالهاتف؟ هل يسرد طلبات الضيوف؟ هل ينشئ طلبات؟ — والاستدعاء بعد «لا» معلَنة يُطلق خطأً فورًا بدل أن يفشل في مكان عميق.
أخطاء تعني شيئًا
طبقة النقل تفرّق بين «غير مصرَّح» و«الخدمة متوقّفة» — فلا تُعرَض «المتجر غير متاح» يومًا على أنها «هذا العميل لم يشترِ شيئًا قط». والأخطاء المسمّاة هي الفارق بين واجهة برمجية ولعبة تخمين.
نقاط webhook محصَّنة ضد إعادة التشغيل
كل حدث وارد يطالب بمفتاح فريد في سجل idempotency قبل المعالجة — فالتسليم المُعاد أو المُكرَّر يموت عند طبقة قاعدة البيانات، لا داخل أتمتتكم.
المفاتيح مُجزَّأة، والأسرار محدودة الصلاحيات
مفاتيح الـAPI تُخزَّن بصيغة تجزئة، ولا يُحَلّ عند الباب سوى التجزئة والصلاحيات — فالصفّ المسرَّب من قاعدة البيانات لا يسمّي مساحة عمل ولا يفتح شيئًا خارج صلاحياته.
المسودّات والتأكيدات صريحة
إنشاء الطلب يأخذ معامل تأكيد صريحًا — فالـAPI العامة افتراضها «مؤكَّد»، ومسارات اللوحة تستطيع تجهيز مسودّات — فيصير سؤال «هل هذا حقيقي؟» حقلًا، لا عُرفًا.
الإعداد
كيف يتم الربط
إصدار مفتاح
أنشئوا مفتاح Commerce API محدود الصلاحيات في اللوحة؛ وألغوه بالسهولة نفسها.
توصيل webhook
أنشئوا مسارًا بمشغّل webhook؛ ووقّعوا الطلبات بسرّه.
الاستدعاء إلى الخارج
أضيفوا خطوات REST حيث تحتاج أنظمتكم أن تعلم.
معًا أفضل
مع ماذا يتكامل
Flows
مشغّلات webhook تبدأ المسارات؛ وخطوات REST تستدعي أنظمتكم في اللحظات التي ترسمونها — فالأتمتة الواردة والصادرة تتشاركان لوحة واحدة.
Commerce
إن محرّك الكتالوج والطلبات الذي خلف الـAPI هو نفسه الذي يستخدمه متجر المحادثة والذكاء الاصطناعي — حقيقة طلب واحدة، وأربعة أبواب.
واجهة متجركم أنتم
تشغّل فرق واجهات متاجر بلا رأس على Commerce API اليوم — وهو المسار الذي توصي به صفحة Shopify بصراحة ريثما يُبنى الموصِّل الأصلي.
الأمان والضمانات
الضمانات المملّة
HMAC على الجسم الخام
التحقّق من webhook يوقّع جسم الطلب الخام بسرّ خاص بكل مشغّل ويقارن في زمن ثابت — ولا يبدأ التحليل إلا بعد الإثبات.
الحمولات بيانات، لا أوامر أبدًا
حمولة webhook تستطيع أن تشير إلى شخص؛ لكنها لا تستطيع أبدًا أن توجّه دواخل مسار، أو تعيد كتابة المطالبات، أو تستدعي أدوات. فالحدّ بين البيانات والتعليمات حدٌّ معماري، لا سلوكي.
حدود معدّل على كل باب
نقاط النهاية العامة تخضع لخنق قياسي، وحدود القراءة مقيَّدة على الخادم — فالعميل البرمجي المسيء يُضعف نفسه، لا المنصّة.
الشروط الدقيقة، دون مواربة
الحدود، مكتوبة
لا تدفّق شامل بعد
تغذية webhook عامة تشترك في كل شيء غير مبنيّة — فالأحداث الصادرة تمرّ اليوم عبر خطوات المسارات. نقولها هنا كي لا تضطر مكالمة مبيعات إلى الإيحاء بغير ذلك.
قراءات محدودة، بالتصميم
القراءات تُرجع حتى 100 صف مع مؤشّر تصفّح — فالـAPI مبنية للتكامل التشغيلي، لا للتصدير بالجملة. واحتياجات الجملة حديث نجريه، لا ثغرة تُستغلّ.
تكامل صادق خير من تكامل صاخب.
كل تكامل في هذه الصفحة موصوف بما يفعله فعلًا: اتجاه المزامنة، وملكية البيانات، والحدود.