مفاتيح الواجهة البرمجية والويبهوك

ما تسلّمه للمطوّر: مفتاح واحد باسم واضح، نطاقات قراءة فقط، وتاريخ إبطال.

الامتثال والتوسع

يومًا ما سيقول لك مندوب شحن، أو محاسبك، أو قريب «فاهم في التكنولوجيا»، إن متجرك «عنده API» و«بيدعم الويبهوك». ستشعر أن واجبًا جديدًا وقع عليك. وهذا غير صحيح.

الفكرة كلها في سطرين. وكل ما يُطلب منك فيها أن تنسخ مفتاحًا واحدًا من «التكاملات» ← «مفاتيح الواجهة البرمجية» وتسلّمه للمطوّر.

يعني إيه مفتاح وويبهوك

مفتاح الواجهة البرمجية مثل نسخة من مفتاح المكتب. يستخدمه برنامج خارجي ليقرأ طلباتك أو منتجاتك أو عملاءك أو كمياتك.
الويبهوك مثل جرس. حين يدخل طلب جديد، يرنّ متجرك على عنوان أعطاك إياه المطوّر، ومعه بيانات الطلب.

الكود والتواقيع في جانبه هو. أما جانبك أنت فهو النتيجة والمفتاح.

أولًا: هل تحتاج مطوّرًا أصلًا؟

أغلب «الربط» في مصر بضغطة زر. بكسلات التسويق وروابط الشحن الجاهزة والتحليلات لا تحتاج سطر كود. ابدأ من متجر التطبيقات.

والعمل المخصّص يستحق تكلفته في أربع حالات: ربط بوسطة، فتذهب الطلبات إليها وتعود حالة التسليم وحدها؛ والمحاسبة، فتدخل الطلبات في برنامج محاسبك لسجلات ضريبة القيمة المضافة؛ والتنبيهات لحظة تأكيد طلب بقيمة عالية أو طلب دفع عند الاستلام؛ ومطابقة المدفوعات مع سجل إنستاباي والمحافظ آخر الشهر.

إن لم يكن أيٌّ من هذا وجعًا حقيقيًا عندك، فلا تفعّلها لمجرد أنها موجودة.

بابان لا يمكن الالتفاف عليهما

الصلاحية لمالك المتجر وحده. تفتح صفحة «التكاملات» ← «مفاتيح الواجهة البرمجية» لمالك المتجر، أو لعضو دوره «المالك». وينتقل غيرهم إلى صفحة التحليلات، ومنهم «قائد العمليات». فاحسب أنك ستفعلها بنفسك.

الميزة في خطتي «نمو» (Growth) و«احترافي» (Pro). لا تشملها خطة «انطلاق» (Starter). ويظل عنصر القائمة ظاهرًا ثم ينقلك إلى التحليلات. وإذا كان دورك لا يرى الاشتراك، تفتح الصفحة لكن إنشاء المفتاح يفشل برسالة public_api_webhooks_not_in_plan.

ماذا تسلّم للمطوّر

النتيجة بكلام بسيط. «عايز الطلب لما يتدفع يظهر في برنامج المحاسب».
مفتاح واحد باسم أداته. «التكاملات» ← «مفاتيح الواجهة البرمجية» ← «مفتاح API جديد»، ثم املأ «اسم المفتاح».
النطاقات التي يستخدمها فقط. أربعة نطاقات قراءة محددة لك مسبقًا: «orders:read» و«products:read» و«customers:read» و«inventory:read». وإذا ألغيت تحديد كل شيء، يحصل المفتاح على هذه الأربعة رغم ذلك.
المفتاح نفسه، مرة واحدة. يعرضه ستوريكس كاملًا مرة واحدة فقط — يبدأ بـ «mak_» وطوله 52 حرفًا — ثم يحفظ قيمة تجزئة له. انسخه، وأرسله، واحتفظ بنسختك في مدير كلمات السر.
تاريخ إبطال. المفاتيح لا تنتهي صلاحيتها وحدها. اتفق على تاريخ النهاية وقت التعاقد، لا بعده.

النطاق الذي يخصم من مخزونك

نطاقات القراءة تنظر إلى البيانات. أما «orders:write» فيغيّرها. المفتاح الذي يملكه يستطيع إنشاء طلبات حقيقية في متجرك، فيخصم ستوريكس هذه الأصناف من مخزونك، ويرفض الطلب حين لا تكفي الكمية. أي أن خطأً في سكربت أحدهم يصير صنفًا ناقصًا على رفّك.

لا تمنح نطاق كتابة إلا حين يحتاجه المشروع فعلًا، ثم أبطِل المفتاح بعد انتهاء العمل.

الإبطال، وحدّ العشرين مفتاحًا

زر «Revoke» في صف المفتاح يوقفه عند أول طلب تالٍ، ولا تراجع عن ذلك. والمتجر يحتفظ بـ 20 مفتاحًا فعّالًا كحد أقصى. وإذا ضاع المفتاح فلا أحد يستطيع عرضه عليك مرة أخرى؛ أبطِله وأنشئ غيره. وأبطِله في آخر يوم للمستقل، تمامًا كما تغلق حساب موظف.

ثلاث حقائق عن الويبهوك توفّر عليك خصامًا

عشر ثوانٍ. يجب أن يردّ خادم المطوّر برمز نجاح خلال 10 ثوانٍ. وإلا أعاد ستوريكس المحاولة بعد 30 ثانية، ثم دقيقتين، ثم 10 دقائق، ثم 30 دقيقة، ثم ساعة — ست محاولات. وبعدها ينتظر الإرسال في قائمة الرسائل المتعثرة حتى يعيده أحد.
الاشتراك الصامت قد يكون موقوفًا. قد يوقفه ستوريكس بنفسه حين يبقى الإرسال بطيئًا، أو حين يشير العنوان إلى شبكة محظورة. ويظل الاشتراك الموقوف يظهر «Active» دون أن يستقبل شيئًا، ولا يلغي زر «Enable subscription» هذا الإيقاف. فريق ستوريكس وحده يعيد تشغيله، فراسل الدعم بدل إعادة بناء الربط.
تغيير مفتاح التوقيع فوري. يتوقف المفتاح القديم في الحال، حتى في عمليات الإرسال التي تنتظر إعادة المحاولة. أخبر المطوّر قبل أن تضغط.

مفاتيح الواجهة البرمجية والويبهوك متاحة في خطتي «نمو» و«احترافي» — قارن الباقات لترى ما يستطيع مطوّرك ربطه.

وهذا الدرس إرشاد عام للتجار، وليس استشارة قانونية ولا محاسبية.