ما هي واجهة برمجة تطبيقات المحاسبة؟ دليل بلغة مبسطة لبناة المنصات

تعريف بلغة مبسطة لواجهة برمجة تطبيقات المحاسبة، وما يميّزها عن واجهة برمجة تطبيقات الضرائب أو المدفوعات، وما يجب التحقق منه قبل البناء عليها.

واجهة برمجة تطبيقات المحاسبة (accounting API) هي واجهة تتيح لبرنامج ما الاحتفاظ بالدفاتر المحاسبية لبرنامج آخر. يرسل برنامجك حدثاً مالياً عبر بروتوكول HTTP، لتقوم الواجهة بتحويل هذا الحدث إلى قيود يومية مزدوجة ومتوازنة مقابل شجرة الحسابات (chart of accounts)، وتخزينها بطريقة تمنع تعديلها سراً، مع تطبيق المعالجة الضريبية المناسبة، وإرجاع التقارير والمستندات وعمليات التصدير عبر الواجهة ذاتها.

هذا التعريف يقوم بمعظم المهمة، وكل ما يليه في هذه المقالة ما هو إلا نتيجة مباشرة له.

النسخة المختصرة في جملة واحدة

تقبل واجهة برمجة تطبيقات المحاسبة الأحداث المالية من تطبيقك، وتحول كل حدث إلى قيد يومي متوازن، وتخزنه بشكل دائم وغير قابل للتعديل مع معاملته الضريبية والأدلة الثبوتية الداعمة له، وتتيح دفتر الأستاذ والمستندات والتقارير الناتجة كنقاط نهاية قابلة للبرمجة (programmable endpoints).

إذا أطلق منتج على نفسه اسم واجهة برمجة تطبيقات المحاسبة ولكنه لا ينتج قيود يومية، فهو شيء آخر يحمل مسمىً براقاً. هذا ليس سيئاً بالضرورة، بل يعني فقط أنه لن يؤدي المهمة التي توشك على تكليفه بها.

ما لا تمثله واجهة برمجة تطبيقات المحاسبة

تحدث غالباً في المراحل المتأخرة من المشاريع تداولات بين أربع فئات من المنتجات المجاورة وبين واجهات برمجة تطبيقات المحاسبة:

الفئة	ما تفعله	ما لا تفعله
واجهة برمجة تطبيقات احتساب الضرائب (Tax calculation API)	تعيد النسبة الصحيحة أو مبلغ الضريبة للمعاملة	الاحتفاظ بدفاترك، أو تخزين الأدلة الداعمة للقرار طوال فترة الاحتفاظ المطلوبة
واجهة برمجة تطبيقات المدفوعات (Payments API)	تنقل الأموال بين الأطراف وتقدم تقارير عن تلك الحركات	تسجيل العمولة المكتسبة، أو ضريبة القيمة المضافة المستحقة، أو الالتزام تجاه البائع في الفترة بين الدفع وصرف الأموال
واجهة برمجة التطبيقات الموحدة أو المجمعة (Unified or aggregator API)	تقرأ وتكتب البيانات في البرنامج المحاسبي الحالي لعميلك	العمل كنظام أساسي للسجلات، فدفاترك توجد في الأداة التي يستخدمها كل عميل بالفعل
واجهة برمجة تطبيقات التقارير أو ذكاء الأعمال (Reporting or BI API)	تقرأ الأرقام من دفتر أستاذ حالي وتعرضها في رسوم بيانية	إنشاء القيود التي استُمدت منها تلك الأرقام

لكل واحدة من هذه الأدوات استخدامات حقيقية. لكن المنصة التي تحتاج إلى أن تكون نظام التسجيل الأساسي تحتاج إلى واجهة برمجة تطبيقات المحاسبة كقاعدة أساسية تحتها، وليس بديلاً عنها.

الأمور الخمسة التي يجب على واجهة برمجة تطبيقات المحاسبة القيام بها

1. تسجيل قيود متوازنة. يصبح كل حدث مبالغ مدينة وأخرى دائنة تتساوى مجتمعة. فعندما يدفع المشتري 100 يورو في سوق إلكتروني يقتطع عمولة قدرها 15 يورو، يسجل القيد مبلغ 100 يورو في حساب مقاصة (clearing account)، ويدين بـ 85 يورو لحساب مستحقات البائع، ويدين بـ 15 يورو لإيرادات العمولة. هذه ليست مجرد شكليات مساكية، بل هي فحص هيكلي يلتقط فئات كاملة من أخطاء التكامل قبل أن تصل إلى التقارير.

2. الاحتفاظ بالسجل التاريخي. القيد المرحل لا يُعدل. أي خطأ يُصحح عن طريق قيد عكسي متبوع بقيد تصحيحي، وكلاهما مرتبط بالقيد الأصلي. تُقفل الشهور المنتهية بحيث لا يمكن تأريخ أي قيد جديد فيها.

3. تسوية الضرائب. بالنسبة للتجارة داخل الاتحاد الأوروبي، يعني ذلك تحديد مكان توريد الخدمة أو السلعة، وآلية الاحتساب العكسي (reverse charge)، والتحقق من أرقام التسجيل في ضريبة القيمة المضافة مقابل السجل الرسمي، وتخزين الأدلة التي تبرر القرار بجانب المعاملة بدلاً من التخلص منها بعد الحساب.

4. المطابقة مع الأموال الخارجية. الدفاتر التي لا تتقاطع أبداً مع كشف الحساب البنكي تظل مجرد تخمين. يجب على واجهة برمجة تطبيقات المحاسبة استيعاب كشوف الحسابات أو تسويات مزودي الخدمة ومطابقتها مع ما تم تسجليه.

5. التصدير. توفير التقارير، والمستندات، وملفات التدقيق، بتنسيقات يقبلها المحاسب البشري والجهات الضريبية.

المنتج الذي يقوم بالثلاثة الأولى ولا يقوم بالاثنين الأخيرتين سيترك شخصاً ما يعمل على جداول البيانات يدوياً كل شهر.

كيف تبدو عملية الاستدعاء فعلياً

الآليات أبسط من الجانب المحاسبي. ففي واجهة برمجة تطبيقات Nordlet، كل عملية عبارة عن طلب POST بنمط استدعاء إجراء عن بُعد (RPC) وبتنسيق متوقع:

POST /v1/{module}/{resource}/{action}
Authorization: Bearer <api key>
Idempotency-Key: <your event id>

أنت تنشئ فاتورة مبيعات، ثم تصدرها. الإصدار هو اللحظة التي تحدث فيها العملية المحاسبية: يحصل المستند على رقمه المتسلسل دون فجوات، ويتم ترحيل قيد اليومية المتوازن، وتُسجل بنود ضريبة القيمة المضافة معه. منصتك لا تجمع أبدًا المدين والدائن يدوياً.

هناك ثلاثة تفاصيل في ذلك المقتطف تعتير أهم من اسم نقطة النهاية:

نطاق الصلاحيات على المفتاح (The scope on the key): يحمل المفتاح صلاحيات مثل sales:write، لكي يحصل التكامل فقط على الوصول الذي يحتاجه.
مفتاح منع التكرار (The idempotency key): أعد إرسال نفس الطلب بنفس الحمولة وستحصل على الاستجابة المخزنة بدلاً من إنشاء فاتورة ثانية. أرسل نفس المفتاح بحمولة مختلفة وسيتم رفض الطلب بالخطأ idempotency_key_reuse بدلاً من قبوله بهدوء.
الأموال كنصوص (Money as strings): المبالغ عبارة عن نصوص عشرية وليست أرقاماً عشريّة ذات فاصلة عائمة (floating-point)، لأن الأرقام العائمة تفقد السنتات بطرق تظهر بوضوح عند إغلاق السنة المالية.

موقعها في هندسة نظامك

يظل تطبيقك بمثابة واجهة المستخدم ومصدر الأحداث التجارية. وتصبح واجهة برمجة تطبيقات المحاسبة هي النظام المالي الأساسي للسجلات من خلفه. وعادة ما يكون التدفق كالتالي:

يحدث شيء ما في منتجك: طلب شراء، استرداد أموال، عملية صرف، أو تجديد اشتراك.
يتصل الواجهة الخلفية (backend) الخاصة بك بواجهة برمجة تطبيقات المحاسبة مرسلة الحدث ومفتاح منع التكرار.
تقوم واجهة برمجة التطبيقات بترحيل قيد اليومية، وتطبيق ضريبة القيمة المضافة، وإرجاع المعرفات التي تخزنها مقابل سجلاتك الخاصة.
يخبرك خطاف الويب (webhook) مثل sale_invoice.paid عندما تتغير الحالة، لكي تتفاعل مع الأحداث بدلاً من الاستعلام المستمر عنها.
تصل المعاملات البنكية عبر تغذية بنكية أو استيراد كشف حساب ويتم مطابقتها مع المستندات المسجلة.
في نهاية الفترة، يتم إنشاء التقارير والسجلات الضريبية من نفس البيانات، ويتم إقفال الشهر المنتهي.

لا يوجد شيء في هذه القائمة يتطلب من شخص ما فتح تطبيق محاسبي. هذا هو الهدف الأساسي من هذه الفئة.

مقارنتها بالبدائل المتاحة

النهج	الجهد المطلوب للبدء	موقف التدقيق	يتوافق مع حجم المعاملات
جداول البيانات والإدخال اليدوي	الأدنى	ضعيف؛ السجل التاريخي قابل للتعديل	لا
التطبيق المحاسبي مع تصدير ملفات CSV	منخفض	يعتمد بالكامل على الانضباط البشري	بشكل ضعيف؛ يقوم شخص ما باستيراد الملفات
واجهة برمجة تطبيقات مجمعة لدفاتر كل عميل	متوسط	يرث ما تفعله أداة العميل أياً كانت	نعم، ولكنك لا تملك السجل أبداً
واجهة برمجة تطبيقات المحاسبة المضمنة	متوسط	قوي إذا كان دفتر الأستاذ غير قابل للتعديل وفتراته مقفلة	نعم
بناء دفتر الأستاذ الخاص بك	الأعلى	قوي فقط إذا قمت ببناء الضوابط الرقابية أيضاً	نعم، وستقوم بصيانته للأبد

يعد بناء نظامك الخاص خياراً مشروعاً لبعض الفرق. وقد تناولنا ذلك بمزيد من التفصيل في دليلنا حول بناء أو شراء الأنظمة للأسواق الإلكترونية.

ما يجب التحقق منه قبل البناء على واجهة برمجة تطبيقات

هل الرصيد مستمد أم مخزن؟ اسأل عما إذا كان رصيد البائع ناتجاً عن استعلام لخطوط اليومية أم مجرد عمود يقوم شخص ما بتحديثه. واحد فقط من هذين الخيارين ينجو من عملية التدقيق والفحص.
ماذا يحدث عند إعادة إرسال الطلب؟ أرسل نفس الطلب مرتين وقُم بّعد القيود الناتجة.
هل يمكنك تعديل قيد مرحل؟ يجب أن تكون الإجابة لا، مع وجود مسار تصحيح موثق.
هل تؤدي الفترة المقفلة فعلياً إلى رفض ترحيل القيود؟ جرب ذلك في بيئة الاختبار (sandbox). تعيد Nordlet الرمز 409 لأي قيد مؤرخ داخل فترة مقفلة.
كيف يتم تمثيل الأموال؟ هل تُستخدم سلاسل عشرية أم وحدات فرعية صحيحة. تجنب الأرقام العائمة نهائياً.
ما الذي يتضمنه سجل التدقيق؟ الجهة الفاعلة، والإجراء، والكيان، والتغيير نفسه، بطريقة قابلة للاستعلام بدلاً من كونها مدفونة في ملفات السجلات (log files).
ما هي حدود معدل الطلبات (rate limits)؟ تسمح Nordlet بـ 300 طلب في الدقيقة لكل مفتاح لواجهة برمجة التطبيقات، وتعرض رصيدك المتبقي في رؤوس استجابة HTTP. مهما كان الرقم، اعلمْه قبل تصميم آلية المزامنة الخاصة بك.
كيف تستخرج بياناتك؟ التقارير، والمستندات، ودفاتر اليومية، بتنسيقات يمكنك تسليمها لمُحاسب.

كل نقطة من هذه النقاط قابلة للاختبار في فترة ما بعد الظهر مقابل شركة تجريبية في بيئة الاختبار. قوائم ميزات البائعين ليست دليلاً كافياً؛ بل الاختبار القابل للتكرار هو الفيصل.

FAQ

هل واجهة برمجة تطبيقات المحاسبة هي نفس برنامج المحاسبة؟

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

هل ما زلت بحاجة إلى محاسب إذا كنت أستخدم إحداها؟

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

هل يمكنني استخدام واجهة برمجة تطبيقات المحاسبة دون فهم نظام القيد المزدوج؟

جزئياً. تبني واجهة برمجة التطبيقات الجيدة قيود اليومية نيابة عنك بناءً على مستند تجاري مثل الفاتورة. لكنك لا تزال بحاجة إلى فهم ما تعنيه الحسابات عندما تقرأ تقريراً أو تشرح رصيداً لمُدقق حسابات.

ما الفرق بين واجهة برمجة تطبيقات المحاسبة وواجهة برمجة تطبيقات دفتر الأستاذ (ledger API)؟

تسجل واجهة برمجة تطبيقات دفتر الأستاذ الحركات المتوازنة بين الحسابات. أما واجهة برمجة تطبيقات المحاسبة فتقوم بذلك وتضيف الطبقة القانونية فوقه: مستندات ذات ترقيم قانوني، ومعالجة ضريبة القيمة المضافة، والسجلات الضريبية، والأصول الثابتة، وإقفال الفترات، والتقارير التي تتوقعها السلطات القضائية. كل واجهة برمجة تطبيقات محاسبية تحتوي على دفتر أستاذ، ولكن ليس كل دفتر أستاذ يعد نظاماً محاسبياً.

كم يستغرق دمج إحداها؟

بالنسبة لتدفق العمل الأول -إنشاء عميل، وإصدار فاتورة، وتلقي الدفع، ورؤية قيد اليومية- توقع أياماً بدلاً من أسابيع باستخدام حزمة تطوير نرمجة (SDK) مكتوبة الأنماط وبيئة اختبار. أما تكامل الإنتاج الشامل الذي يغطي عمليات الاسترداد، والتصحيحات، والعملات المتعددة، والمطابقة، وإقفال الفترات، فهو عمل أكبر بكثير، ويعتمد التقدير الدقيق على عدد تلك الحالات التي يولدها منتجك فعلياً.