الجواب القصير. الشريك مستعمل بدور، لا استثناء: يمر بـ الخدمات نفسها التي لتطبيقكم، ولا مسار خاصاً له. وبينه وبين تلك الخدمات، بوابة تطبّق ستة أبواب متطابقة للجميع: اتصال مشفَّر، مفتاح أو رمز لكل شريك قابل للإلغاء، حقوق قراءة وكتابة لكل مورد، حصة في الدقيقة واليوم مع 429 ومهلة إعادة، مخطط منمَّط ومرقَّم، مفتاح عدم تكرار على كل كتابة؛ وكل مرور أو رفض يترك سطراً في السجل. وما يتغير عندكم يصل إليه بـ webhooks موقَّعة، تُعاد بفاصل متزايد ثلاثة أيام، وقابلة للإعادة من بوابة. والنسخة 1 مجمَّدة لا تتغير إلا بالإضافة، باثني عشر شهراً من الدعم مكتوبة. عشرة أسابيع، اثنان منها قبل أن يرى أي شريك شيئاً.
هذا الدليل موجّه إلى المسيّر الذي يطلب منه ناقل أو زبون كبير أو مكتب «وصولاً»، وإلى المؤسس المقيم في فرنسا الذي يجب أن تتصل منصته ببرامج لا يعرفها، وإلى مسؤول الإعلام الآلي الذي يجب أن يرفض الوصول المباشر إلى القاعدة دون تعطيل الشركة. لا يعيد كيف نتصل نحن ببرنامج قائم، الموصوف في دليل الدمج، ولا كيف تُبنى الأدوار داخل التطبيق، الموصوف في دليل الحقوق؛ بل يصف العكس، ما يُبنى حين يتصل الآخرون بكم، ويمدّ صفحتنا عن هندسة البرمجيات.
ما تقوله المنصات الكبرى
المنصات التي تفتح واجهاتها لآلاف الشركاء تنشر قواعدها، وهي تنتقل. في النسخ: منصة تجارة إلكترونية كبرى «تصدر نسخة جديدة من الواجهة كل ثلاثة أشهر»، وتسمّي كل نسخة بتاريخها، وتضمن أنها «لا تتغير طوال مدة دعمها»، وتدعمها «اثني عشر شهراً على الأقل»، وحين يستدعي شريك نسخة لم تعد موجودة «تجيب بأقدم نسخة مستقرة متاحة» بدل رفضه. وما يفرضه ذلك: النسخة لا تتغير إلا بالإضافة، والتالية لها تاريخ إعلان وتاريخ نهاية دعم مكتوبان، والشريك المتأخر يتلقى جواباً لا خطأ.
في الـ webhooks، تقول وثائق منصة دفع كبرى إن الأحداث تُعاد «حتى ثلاثة أيام بفاصل متزايد»، وإنها «لا تضمن تسليم الأحداث بترتيب توليدها»، وإن على خادمكم أن «يعيد رمز 2xx بسرعة قبل أي منطق معقد»، وإن المكررات تُكتشف بمعرّف الحدث لا بالطابع الزمني أبداً. والتوقيع HMAC-SHA256 للنص الخام مسبوقاً بالطابع الزمني، بتسامح افتراضي خمس دقائق ضد الإعادة، ويمكن تدوير السر بتداخل حتى 24 ساعة تصدر خلالها توقيعان. وما يفرضه ذلك: الـ webhook محاولة، والشريك يقرّ ثم يعالج، ويتجاهل ما سبق رؤيته، ويستطيع دائماً إعادة قراءة الحالة عبر الواجهة.
في الحصص، بروتوكول HTTP نفسه يملك الجواب: الرمز 429 «طلبات كثيرة جداً» المعرَّف في RFC 6585، مع ترويسة Retry-After تقول كم ننتظر؛ وفي المفاتيح، تدفق «client credentials» في OAuth 2.0 يصف مبادلة معرّف وسر برمز قصير العمر، لآلة تخاطب آلة. وما يفرضه ذلك: الشريك الذي يتجاوز حصته لا يخسر شيئاً، ينتظر المهلة المذكورة؛ والمفتاح المسروق يُلغى دون مس الآخرين. وما لم نجده: معيار جزائري أو قطاعي للواجهات بين الشركات؛ وما نراه هو وصول إلى القاعدة يُتقاسَم بالبريد، ونقولها ملاحظةً.
وصل شريك، في ست خطوات
قبل الهندسة، مسار الشريك من الطلب إلى مفتاح الإنتاج.
الطلب والعقد: يقول الشريك ما يريد قراءته وكتابته وبأي تواتر، ويوقّع الطرفان ورقة حقوق؛ وهي التي ستحسم النقاشات. حساب ومفتاح اختبار: حساب شريك، مفتاح بيئة تجريبية، بيانات وهمية تشبه الحقيقية، كي يطوّر دون مس شيء. حقوق وحصص مكتوبة: قراءة أو كتابة لكل مورد، استدعاءات في الدقيقة واليوم؛ وهي الخطوة التي تُتخطى دائماً، والتي تمنع تعديل سعر في الثالثة فجراً.
دمج في البيئة التجريبية: يطوّر الشريك وحده بالوثائق، وأخطاؤه في سجله الذي يقرؤه دون أن يتصل بكم. مراجعة: السجل يُعاد قراءته معاً، الأخطاء تُشرح، عدم التكرار يُتحقَّق منه بإعادة إرسال الكتابة نفسها مرتين، الـ webhooks مُقرّ بها. مفتاح الإنتاج: يُفعَّل في تاريخ، بحصة بداية تُرفع عند الطلب، ومراقبة في الأسبوع الأول، وتدوير مخطَّط في العقد. ست خطوات، أربع منها يعمل فيها الشريك وحده: وهذا مقياس الواجهة المصنوعة جيداً.
ثلاثة استدعاءات، سلسلة أبواب واحدة
أمان الواجهة المفتوحة لا يُرى على مخطط بل على ثلاثة استدعاءات حقيقية، وعلى الباب الذي يتوقف عنده كل منها.
الناقل يقرأ الطلبيات الجاهزة للشحن بمفتاح إنتاجه: اتصال مشفَّر، مفتاح معروف، حق قراءة على الطلبيات، حصة محترمة، مخطط النسخة 1، لا كتابة فلا مفتاح عدم تكرار مطلوب؛ يتلقى ثماني وأربعين طلبية ويُسجَّل الاستدعاء باسمه والمسار وزمن الرد. الزبون الكبير يحاول تعديل سعر: مفتاحه صالح، لكن دوره لا يمنحه إلا إنشاء الطلبيات وقراءة فواتيره؛ يُوقَف عند باب الحقوق، يتلقى 403، تُكتب المحاولة ويُنبَّه مخاطبه. لم يُنسَ أي مسار: القاعدة يطبّقها الخادم على كل مورد، كما يصف دليل الحقوق للمستعملين الداخليين.
تطبيق الصندوق يرسل استدعاءه الـ 601 في الدقيقة: يُوقَف عند باب الحصة، يتلقى 429 وRetry-After اثنتي عشرة ثانية؛ لا شيء يضيع، يعيد المحاولة، وإن تكرر ذلك كل يوم تُرفع الحصة كتابةً. والسلسلة متطابقة للجميع، وهي الشيء الوحيد الذي يراه الشريك منكم، وهي الباب نفسه الذي يوضع أمام وكيل ذكاء اصطناعي: الشريك والوكيل فاعلان يقترحان أفعالاً، والخادم يقرر.
«الشريك لا يرى خدمتكم ولا قاعدتكم أبداً؛ يرى ستة أبواب، هي نفسها للجميع، وكل مرور أو رفض يترك سطراً.»
واجهة مفتوحة للشركاء، في خمس طبقات
خلف هذه الاستدعاءات الثلاثة خمس طبقات، وقاعدة في الثالثة تحمل كل الأخرى.
الشريك: نظامه، تطبيقه، برنامجه النصي؛ لا تتحكمون في كوده، تتحكمون فيما يستطيع طلبه وما يتلقاه. البوابة: اتصال مشفَّر، مفاتيح ورموز، حقوق لكل مورد، حصص، مخطط لكل نسخة، عدم تكرار، سجل؛ الطبقة التي تحمي، متطابقة للجميع، والوحيدة التي يرونها. خدماتكم: نفسها التي لتطبيقكم، الطلبيات والتسليمات والفواتير والكتالوج؛ لا مسار «خاص بالشركاء»، وما يستطيع الشريك فعله يستطيعه مستعمل بالدور نفسه ولا أكثر؛ وهذا ما يمنع الواجهة من أن تصير تطبيقاً ثانياً يُصان.
البيانات: لا تُكشف مباشرة أبداً، مرشَّحة بالدور؛ الزبون الكبير لا يرى إلا طلبياته وفواتيره، والناقل لا يرى الأسعار، وإن كانت منصتكم تخدم عدة زبائن فالعزل الموصوف في دليل SaaS متعدد المستأجرين هو الذي يُطبَّق. البوابة والإشراف: وثائق مولَّدة من المخطط، بيئة تجريبية، مفاتيح وأسرار يديرها الشريك بنفسه، سجل استدعاءاته وwebhooks، إعادة؛ ما يقرؤه الشريك وحده بدل أن يتصل بكم، وما تقرؤونه كل أسبوع على شاشة تُبنى مثل لوحة قيادة المسيّر.
ستة شركاء، وما يحق لكل منهم فعله
ورقة الحقوق أنفع وثيقة في المشروع، وتتسع في ستة أسطر.
الناقل يقرأ الطلبيات الجاهزة للشحن والعناوين والفترات، لا الأسعار ولا الهوامش أبداً؛ يكتب حالة التسليم والإثبات والحوادث؛ يتلقى أحداث الشحن والإلغاء؛ وهو الربط الموصوف في دليل منصة التوصيل. الزبون الكبير B2B يقرأ كتالوجه بالأسعار المتفاوَض عليها وطلبياته وفواتيره، لا شيء من الآخرين؛ ينشئ طلبية ويلغيها قبل التحضير؛ وهو بوابة B2B مرئية من نظامه. مكتب المحاسبة يقرأ الفواتير وإشعارات الدائن والتسديدات حسب الفترة، ولا يكتب شيئاً.
الموزّع أو المنصة التجارية يقرأ المخزون المتاح وأسعار الموزّع، ينشئ طلبيات ويحجز مخزوناً ثلاثين دقيقة، ويتلقى تغيرات المخزون والأسعار؛ وهو الوصل الموصوف في دليل المنصة التجارية. تطبيق الصندوق الخارجي يقرأ الكتالوج ويكتب المبيعات والإقفالات كما ينص دليل الصندوق. البنك أو المجمّع لا يقرأ ولا يكتب شيئاً: يرسل webhooks موقَّعة وأنتم تتحققون منها وفق دليل الدفع. وحصص الجدول نقاط بداية؛ تُرفع عند الطلب بتاريخ، ولا تُرفع في صمت أبداً.
حدث يُسلَّم إلى شريك: موقَّع، مُعاد، مُقرّ به، قابل للإعادة
الـ webhooks نصف الواجهة الذي تنساه عروض الأسعار، والنصف الذي يوقظ ليلاً.
الحدث commande.expediee يُنشأ في 10:02 للناقل. المحاولة الأولى: خادمه لا يجيب في عشر ثوانٍ. الثانية، بعد دقيقة: يجيب 500، كان يعيد التشغيل. الثالثة، في 10:12: 200، مُقرّ به. والفاصل بين المحاولات يتزايد، وتستمر المحاولات حتى ثلاثة أيام؛ وبعدها يُوسم الحدث غير مسلَّم ويراه الشريك في بوابته حيث يستطيع إعادته. وفي كل محاولة الترويسة نفسها: معرّف الحدث، الطابع الزمني، توقيع HMAC-SHA256 محسوب بسر الشريك على الطابع الزمني والنص الخام.
عند الشريك، أربعة أفعال تشرحها الوثائق وتتحقق منها المراجعة: التحقق من التوقيع على النص الخام ورفض طابع زمني أقدم من خمس دقائق؛ الرد 200 فوراً والمعالجة بعدها في طابور؛ تجاهل معرّف سبق رؤيته لأن التسليم المكرر يجب ألا يغيّر شيئاً؛ وإعادة قراءة الحالة عبر الواجهة عند الشك، لأن الـ webhook محاولة لا حقيقة. والسر يدور بتداخل أربع وعشرين ساعة يصدر خلالها توقيعان، كي لا يُقطع أي شريك مساء جمعة.
«الـ webhook محاولة لا حقيقة؛ الشريك يقرّ ويعالج ويتجاهل ما سبق رؤيته ويعيد قراءة الحالة عند الشك.»
رأيناه في مكان آخر: المنصات التي تفتح واجهاتها، وما ينتقل
ثلاثة مصادر تقول الجوهر. منصة التجارة التي تنشر نسخة كل فصل وتدعمها اثني عشر شهراً تقول كيف تُغيَّر واجهة دون كسر الشركاء: بالإضافة، وبتواريخ، وبالإجابة عن المتأخرين؛ وما ينتقل هو النسخة 1 المجمَّدة وسياسة الإهمال المكتوبة في العقد. ومنصة الدفع التي تعيد ثلاثة أيام ولا تضمن الترتيب وتطلب 2xx سريعاً تقول كيف تُسلَّم أحداث إلى خوادم لا نتحكم فيها؛ وما ينتقل هو التوقيع والمحاولات ومعرّف الحدث والإعادة. وHTTP وOAuth يقولان كيف نرفض بنظافة وكيف نوثّق آلة؛ وما ينتقل هو 429 بمهلة والمفتاح القابل للإلغاء.
وما لا تقوله هذه المصادر: ما يحق لشركائكم رؤيته عندكم، وكم استدعاءً في الدقيقة يحتمل خادمكم؛ ورقة الحقوق تجيب عن الأول، واختبار الحمل في البيئة التجريبية عن الثاني.
قواعد واجهة يمكن فتحها بلا خوف
ست قواعد تُكتب في الأسبوع الأول. الشريك مستعمل بدور يمر بالخدمات نفسها؛ لا مسار خاصاً. مفتاح لكل شريك، يُلغى وحده، بتدوير مخطَّط. الحقوق يطبّقها الخادم على كل مورد لا الوثائق. حصة لكل شريك، مع 429 ومهلة، تُرفع كتابةً. الـ webhooks موقَّعة ومُعادة وقابلة للإعادة، والشريك يستطيع دائماً إعادة قراءة الحالة. النسخة مجمَّدة: لا تتغير إلا بالإضافة، وللتالية تواريخ.
قاعدة سابعة تخص عرض السعر: «واجهة للشركاء» ليس متطلباً بل جملة؛ المتطلب يُكتب «ورقة حقوق لكل نوع شريك، قراءة وكتابة لكل مورد؛ مفتاح أو رمز لكل شريك، إلغاء، تدوير؛ حصص في الدقيقة واليوم مع 429 وRetry-After؛ مخطط مرقَّم ووثائق مولَّدة من المخطط؛ مفتاح عدم تكرار على كل كتابة؛ سجل لكل استدعاء بالشريك والمسار والنتيجة؛ webhooks موقَّعة HMAC بطابع زمني، محاولات بفاصل متزايد حتى ثلاثة أيام، معرّف حدث، إعادة من البوابة؛ بيئة تجريبية ببيانات وهمية؛ سياسة نسخ باثني عشر شهراً من الدعم؛ لا وصول مباشراً إلى القاعدة»، ويُتحقَّق منه كما يوصي دليل دفتر الشروط. وعرض السعر الذي يقترح «وصول قراءة إلى القاعدة للشريك» اقترح العطل رقم واحد.
ست شركات، وأول شريك تصله
ست شركات نجهّزها كثيراً، ولكل منها أول شريك طلب «وصولاً».
- تاجر الجملة وبوابته، الموصوفان في الدليل المخصص. أكبر تجار تجزئته يطلب من برنامجه الخاص؛ لا يرى إلا أسعاره، والمخزون الذي يحجزه يُحرَّر بعد ثلاثين دقيقة.
- منصة التوصيل، الموصوفة في الدليل المخصص. ثلاثة متاجر إلكترونية ترسل إليها طلبياتها وتتلقى الحالات؛ لكل منها مفتاحه، ولا يرى أي منها الآخرين.
- تاجر الجملة الصيدلاني، الموصوف في دليل سلسلة التبريد. المخبر يقرأ تتبع الدفعات التي سلّمها، لكل دفعة، لا لكل زبون أبداً.
- المنصة التجارية، الموصوفة في الدليل المخصص. البائعون يزامنون المخزون والأسعار من صندوقهم؛ ستمئة استدعاء في الدقيقة لأكبرهم، وحجز مخزون عند الطلب.
- التطبيق المحمول وشركاؤه، الموصوف في دليل التحديثات. قاعدة الإضافة بلا حذف نفسها تخدم نسخ التطبيق القديمة والشركاء: سياسة نسخ واحدة.
- الشركة المُدارة من فرنسا. مكتب المحاسبة في الجزائر العاصمة يقرأ الفواتير والتسديدات كل مساء عبر الواجهة؛ والمؤسس يرى في لوحته من استدعى ماذا، وملف البريد الشهري اختفى.
تقويم 2027
التقويم تقويم واجهة تُفتح في عشرة أسابيع، اثنان منها قبل أن يرى أي شريك شيئاً.
الأسبوع 0 إلى 1 يكتب عقد الواجهة: الموارد، الحقوق لكل نوع شريك، حصص البداية، سياسة النسخ والإهمال؛ موقَّعاً. الأسبوعان 1 إلى 3 يبنيان البوابة أمام الخدمات القائمة: مفاتيح ورموز، حقوق لكل مورد، حصص، سجل؛ لا مسار جديداً. الأسبوع 3 إلى 4 يفتح البيئة التجريبية والوثائق المولَّدة من المخطط، والبوابة التي يدير فيها الشريك مفاتيحه ويقرأ سجله. الأسبوعان 4 إلى 6 يبنيان الـ webhooks: الأحداث، التوقيع، المحاولات بفاصل متزايد، الإعادة.
الأسبوعان 6 إلى 8 يصلان الشريك الحقيقي الأول، ناقلاً أو زبوناً كبيراً، في البيئة التجريبية ثم في الإنتاج، والسجل يُعاد قراءته معاً كل أسبوع. الأسبوعان 8 إلى 10 يجمّدان النسخة 1: لا تتغير إلا بالإضافة، واثنا عشر شهراً من الدعم مكتوبة، والنسخة 2 لن توجد إلا إن اقتضاها تغيير. وكل دفعة تُعرض كما يصف دليل التسليم، ومفتاح عدم التكرار على كل كتابة يتبع مبدأ المزامنة دون اتصال: كتابة أُرسلت مرتين تُعدّ مرة.
ما يُفشل واجهة مفتوحة للشركاء
الواجهات التي نستلمها فشلت دائماً تقريباً لأحد هذه الأسباب.
- الوصول المباشر إلى القاعدة. الشريك يقرأ كل شيء، ويكتب أحياناً، ولا أحد يعرف ماذا.
- مفتاح واحد للجميع. يتسرب عند شريك، فيُقطع الجميع لتغييره.
- حقوق في الوثائق لا في الخادم. «يرجى عدم استدعاء هذا المسار» ليس تحكماً.
- لا حصة. برنامج نصي سيئ الكتابة عند الشريك يستدعي ألف مرة في الثانية، وزبائنكم ينتظرون.
- webhooks بلا توقيع ولا إعادة. أي أحد يستطيع إرسالها، والحقيقية تضيع عند أول انقطاع.
- حقل حُذف بلا تاريخ. ثلاثة شركاء ينهارون في الصباح نفسه، ولم يُنبَّه أي منهم.
- لا بيئة تجريبية. الشريك يختبر في الإنتاج بطلبيات حقيقية، ونكتشف أخطاءه عند الزبائن.
أسئلة شائعة
الأسئلة التي نتلقاها من مسيّرين ومؤسسين ومسؤولي إعلام آلي.
- هل يستطيع شريك الوصول مباشرة إلى قاعدة بياناتنا؟
- لا، وهذه القاعدة الأولى: الشريك مستعمل بدور، يمر بالخدمات نفسها التي لتطبيقكم، خلف بوابة تتحقق من مفتاحه وحقوقه لكل مورد وحصته والمخطط وعدم التكرار، وتسجّل كل استدعاء. والوصول إلى القاعدة يعطي كل شيء للجميع بلا أثر، ولا يُلغى دون كسر كل شيء.
- كيف نحدّ ما يراه كل شريك؟
- بورقة حقوق موقَّعة من الجانبين يطبّقها الخادم على كل مورد: الناقل يقرأ الطلبيات الجاهزة للشحن لا الأسعار، الزبون الكبير لا يرى إلا طلبياته وفواتيره، المحاسب يقرأ ولا يكتب شيئاً. الوثائق تصف هذه الحقوق؛ والخادم يطبّقها، والمحاولة خارج الحقوق تتلقى 403 وسطراً في السجل.
- ماذا يحدث إن استدعى شريك كثيراً جداً؟
- له حصة في الدقيقة واليوم؛ وفوقها يتلقى 429 مع ترويسة Retry-After تقول كم ينتظر، ولا يخسر شيئاً بإعادة المحاولة. وإن تكرر التجاوز تُرفع الحصة كتابةً بتاريخ. وزبائنكم لا يُبطَّؤون أبداً ببرنامج شريك.
- كيف يُنبَّه الشريك حين يتغير شيء عندنا؟
- بالـ webhooks: حدث موقَّع بـ HMAC-SHA256 وطابع زمني، يُرسل إلى عنوانه، يُعاد بفاصل متزايد حتى ثلاثة أيام إن لم يجب 2xx، بمعرّف فريد كي لا يغيّر المكرر شيئاً، وقابل للإعادة من بوابته. ويستطيع دائماً إعادة قراءة الحالة عبر الواجهة: الـ webhook محاولة لا حقيقة.
- ماذا يحدث حين نغيّر واجهتنا؟
- النسخة 1 لا تتغير إلا بالإضافة: حقول أو مسارات جديدة، لا حذف أبداً. وإن لزم تغيير غير متوافق، تُعلَن النسخة 2 بتاريخ، وتبقى النسخة 1 مدعومة اثني عشر شهراً، ويتلقى الشريك المتأخر جواباً لا خطأ. وهي السياسة التي تتبعها منصات التجارة الكبرى، مكتوبة في عقد واجهتكم.
- كم من الوقت لفتح واجهة لشريك أول؟
- عشرة أسابيع: واحد لعقد الواجهة، اثنان للبوابة أمام الخدمات القائمة، واحد للبيئة التجريبية والوثائق، اثنان للـ webhooks، اثنان للشريك الأول في البيئة التجريبية ثم الإنتاج، اثنان لتجميد النسخة 1. ويعمل الشريك وحده معظم هذا الوقت بالوثائق وسجله.