هل يجب تسليم وثائق API؟
نعم، يجب أن ينص عقد أي مشروع برمجي صراحةً على تسليم وثائق واجهة برمجة التطبيقات (API) كاملة عند التسليم النهائي أو عند كل تحديث جوهري، لأن هذه الوثائق هي الضمان الوحيد لفهم النظام وصيانته وربطه بأنظمة أخرى دون البقاء رهينة للمطوّر الأصلي. تجاهل هذا البند من أكثر أسباب النزاعات وتعطل التطوير شيوعاً بين الشركات في السوق السعودي.
ما المقصود بوثائق API ولماذا تهمّ صاحب العمل
واجهة برمجة التطبيقات، أو API (اختصار Application Programming Interface)، هي مجموعة القواعد والنقاط التي تسمح لبرنامجين مختلفين بتبادل البيانات فيما بينهما، مثل ربط متجرك الإلكتروني بنظام شحن، أو ربط نظام نقاط البيع بمنصة الفوترة الإلكترونية.
وثيقة API هي الدليل المكتوب الذي يشرح كل نقطة اتصال في هذه الواجهة: ما البيانات التي تُرسَل، وما الذي يعود كرد، وما قواعد الحماية والمصادقة. بدون هذا الدليل يصبح النظام "صندوقاً أسود" حتى لو كان الكود نفسه مملوكاً لك.
هذه النقطة تهم بشكل خاص أصحاب المتاجر الإلكترونية في جدة والرياض الذين يحتاجون لاحقاً لربط متاجرهم بشركات شحن جديدة أو بأنظمة محاسبية، وأصحاب العيادات والمنشآت الصحية في الدمام الذين قد يحتاجون لربط نظام الحجز بمنصات التأمين الطبي.
لماذا يتجاهل كثير من العقود هذا البند؟
غالباً لأن صاحب العمل لا يعرف أصلاً أن مثل هذه الوثائق موجودة أو ضرورية، فيركز العقد على "تسليم النظام يعمل" دون تفاصيل فنية. بعض مقدمي الخدمة، من جهتهم، لا يمانعون هذا الإغفال لأنه يبقي العميل معتمداً عليهم في أي تعديل مستقبلي.
عدم ذكر تسليم وثائق API صراحةً في العقد يعني قانونياً أنه ليس التزاماً واجب التنفيذ، حتى لو اعتبره العميل "من البديهيات".
ماذا يجب أن تتضمنه وثيقة API الجيدة؟
لا يكفي أن تحصل على ملف يحمل اسم "توثيق"؛ يجب أن يغطي هذه العناصر الأساسية:
- قائمة نقاط الاتصال (Endpoints): كل رابط يمكن للنظام الخارجي استدعاءه، مع الغرض منه.
- صيغ الطلب والرد: شكل البيانات المُرسَلة والمستقبَلة، عادة بصيغة JSON، مع أمثلة حقيقية.
- آلية المصادقة: كيفية تأمين الاتصال (مفاتيح API، رموز الدخول Tokens) لمنع الاختراق.
- رموز الأخطاء ومعانيها: حتى يستطيع أي مطوّر لاحق تشخيص المشاكل دون العودة للمصدر.
- حدود الاستخدام: عدد الطلبات المسموح بها في الدقيقة أو اليوم، إن وُجدت.
اطلب أن تكون الوثائق بصيغة قابلة للتشغيل مثل Swagger أو Postman Collection، وليست مجرد ملف نصي وصفي، لتتمكن أي جهة تقنية لاحقاً من تجربتها فوراً.
الفرق بين نظام موثَّق ونظام غير موثَّق
| الجانب | نظام مع وثائق API كاملة | نظام بدون وثائق |
|---|---|---|
| تغيير مزوّد الصيانة | سهل، أي شركة تقنية تستطيع الاستمرار | شبه مستحيل دون إعادة هندسة الكود |
| الربط مع أنظمة جديدة (شحن، محاسبة، ERP) | أيام قليلة | أسابيع من الاختبار العشوائي |
| التعامل مع طلبات هيئة الزكاة والضريبة والجمارك لربط الفوترة الإلكترونية | مباشر وسريع | يتطلب إعادة اكتشاف الواجهة من الصفر |
| القيمة السوقية للنظام عند بيع الشركة أو تقييمها | أعلى، لأنه أصل موثَّق | أقل، ويُنظر إليه كمخاطرة |
ربط ذلك بمتطلبات تنظيمية سعودية
في مشاريع الفوترة الإلكترونية التي تُلزم بها هيئة الزكاة والضريبة والجمارك (ZATCA)، يعتمد الربط التقني بشكل كامل على واجهات API محددة المواصفات؛ فأي نظام تجاري يجب أن تُوثَّق طريقة اتصاله بهذه الواجهات بوضوح حتى يستمر الامتثال مع أي تحديث مستقبلي.
كذلك، عندما يتبادل نظامك بيانات عملاء عبر API، فإن ضبط هذا التبادل يدخل ضمن اعتبارات حماية البيانات الشخصية التي تشرف عليها الهيئة السعودية للبيانات والذكاء الاصطناعي (SDAIA)، وتوثيق الواجهة يساعد في إثبات الالتزام عند المراجعة.
كيف تضمن هذا البند في عقدك القادم
- اذكره كبند مستقل: لا تكتفِ بعبارة "تسليم كامل للمشروع"، بل أضف فقرة باسم "تسليم الوثائق الفنية بما فيها API".
- حدّد الصيغة والموعد: اشترط تسليم الوثائق قبل السداد النهائي أو الدفعة الأخيرة.
- اربطها بملكية الكود المصدري: فملكية الكود دون توثيق الواجهة تظل ملكية منقوصة عملياً.
- اطلب تحديثها مع كل تعديل جوهري: أي إضافة أو تعديل على النظام يجب أن يُحدَّث توثيقها بالتوازي.
عند التعاقد على برمجة أنظمة مخصصة مثل نظام CRM لإدارة العملاء أو نظام نقاط بيع، اجعل بند تسليم وثائق الواجهات جزءاً أساسياً من كراسة المواصفات منذ اليوم الأول، لا بنداً تفاوضياً لاحقاً.
ماذا لو كان النظام قائماً بالفعل بدون توثيق؟
الحل ليس مستحيلاً، لكنه يكلّف وقتاً ومالاً إضافياً. يمكن لفريق تقني متخصص إعادة هندسة الواجهة (Reverse Engineering) وكتابة توثيق مستقل بناءً على سلوك النظام الفعلي، وهي خدمة تدخل ضمن أعمال الدعم الفني المستمر لأي منشأة تريد استعادة السيطرة على أنظمتها القديمة.
هذا السيناريو شائع مع الشركات الصغيرة والمتوسطة التي طوّرت أنظمتها الأولى بميزانيات محدودة دون استشارة قانونية أو تقنية كافية، ثم اكتشفت لاحقاً أنها لا تملك فعلياً القدرة على تطوير ما بنته.
تطبيقات الجوال والمتاجر أيضاً تحتاج هذا البند
لا يقتصر الأمر على الأنظمة الداخلية؛ فأي تطبيق جوال يتواصل مع خادم خلفي (Backend)، وأي متجر إلكتروني يتكامل مع بوابات دفع وشركات شحن، يعتمد بالكامل على واجهات API. غياب توثيقها يعني أن أي تطوير مستقبلي للتطبيق، أو ربط المتجر بمنصة جديدة، سيبدأ من الصفر تقريباً.
- وثائق API هي الدليل الفني الذي يجعل نظامك قابلاً للصيانة والربط دون الاعتماد الدائم على مطوّر واحد.
- يجب أن يُذكر تسليمها كبند صريح ومستقل في العقد، مرتبط بموعد التسليم النهائي والدفعة الأخيرة.
- الوثيقة الجيدة تشمل نقاط الاتصال، صيغ البيانات، آلية المصادقة، ورموز الأخطاء.
- غيابها يرفع تكلفة أي تطوير أو ربط مستقبلي، ويقلل القيمة السوقية للنظام نفسه.
- الربط مع أنظمة تنظيمية مثل الفوترة الإلكترونية يتطلب توثيقاً دقيقاً للواجهات المستخدمة.
أسئلة شائعة
نعم، عبر خدمة إعادة توثيق الأنظمة القديمة، حيث يفحص فريق تقني سلوك النظام الفعلي ويكتب وثيقة مطابقة له، وهي خدمة متاحة ضمن باقات الدعم الفني المستمر.
غالباً لا يضيف تكلفة تُذكر إذا كان جزءاً من خطة العمل منذ البداية، لأن التوثيق يُكتب أثناء التطوير نفسه، لا بعد انتهائه.
يجب أن ينص العقد على أن ملكية الوثائق تنتقل كاملة لصاحب العمل مع ملكية الكود المصدري، دون قيود على استخدامها مع أي مزوّد خدمة آخر مستقبلاً.
نعم من حيث المبدأ، فحتى الأنظمة الصغيرة تتكامل غالباً مع بوابات دفع أو شركات شحن أو أنظمة أخرى، وأي تكامل مستقبلي يعتمد على وجود توثيق واضح ولو كان مختصراً.
إذا كنت تخطط لمشروع نظام مخصص أو تطبيق جوال أو متجر إلكتروني جديد، احرص من البداية على أن يشمل عقدك بنداً واضحاً لتسليم وثائق API. فريق بوابة الحلول التقنية يساعدك في صياغة كراسة المواصفات وتسليم توثيق كامل ومحدَّث لكل مشروع؛ اطلب عرض سعر واستشارة مجانية اليوم وابدأ مشروعك على أساس تعاقدي واضح ومحمي.