ما هي واجهة برمجة تطبيقات دفتر القيد المزدوج للأسواق الإلكترونية؟
تسجل واجهة برمجة تطبيقات دفتر القيد المزدوج حركة الأموال في الأسواق الإلكترونية في شكل قيود يومية متوازنة وغير قابلة للتعديل، لتعرف دائماً من له ماذا ولماذا.
قد تبدو السوق الإلكترونية مزدهرة في جدول orders (الطلبات) الخاص بها، ومع ذلك تكون حساباتها المالية خاطئة تماماً. يقول الطلب إنه "مدفوع". وتُظهر لوحة تحكم البائع رصيداً. ولكن لا يوجد أي شيء في ذلك الجدول يثبت حجم النقد الذي تحتفظ به المنصة، أو المبلغ المستحق لكل بائع، أو نسبة إيرادات العمولة من الدفع، أو قيمة ضريبة القيمة المضافة واجبة الدفع الآن. وتأتي واجهة برمجة تطبيقات دفتر القيد المزدوج (double-entry ledger API) لتسجيل تلك النتائج المالية بشكل صحيح، معاملة متوازنة تلو الأخرى.
باختصار وبكل بساطة: واجهة برمجة تطبيقات دفتر القيد المزدوج هي نظام محاسبي قابل للبرمجة. يُرسل تطبيقك إليها حدثاً مالياً، مثل دفعة مُحصّلة أو عملية صرف مُعتمدة، فيقوم دفتر القيد بتسجيل هذا الحدث كدفتر يومية يحتوي على مدين ودائن متساويين موزعين عبر حسابات محددة. وهي لا تقوم بنقل الأموال، بل تسجل الحقيقة حول الأموال التي انتقلت إلى مكان آخر.
ماذا يعني "دفتر القيد المزدوج" هنا
دفتر القيد (Ledger) هو سجل للتغيرات التي تطرأ على الحسابات، وليس جدولاً يحفظ آخر رصيد فقط. ويعتمد دفتر القيد الفعّال على ثلاث أفكار مترابطة:
- الحساب (Account): مركز مالي مُسمّى، مثل مستحقات معالج الدفع، أو مستحقات البائع، أو إيرادات العمولة، أو ضريبة القيمة المضافة مستحقة الدفع.
- المعاملة أو القيد اليومي (Transaction / Journal): حدث مالي ذي وحدة واحدة (atomic) يحتوي على عدة أسطر متوازنة.
- البند أو القيد (Entry / Posting): سطر مدين أو دائن منفرد داخل تلك المعاملة.
والثابت الأساسي الذي يربط كل التصميمات ببعضها بسيط للغاية: إجمالي المدين يساوي إجمالي الدائن، في كل معاملة وكل عملة. وعادةً ما ترفض واجهات برمجة تطبيقات دفاتر القيد أي عملية كتابة غير متوازنة قبل وصولها إلى وحدة التخزين. وتُعرّف وثائق Modern Treasury معاملات دفتر القيد بأنها تتضمن حسابين أو أكثر مع وجود مدين واحد على الأقل ودائن واحد على الأقل بمجاميع متساوية، وتتعامل مع المعاملة المُرحّلة باعتبارها غير قابلة للتعديل (immutable).
ولا يعني القيد المزدوج بالضرورة وجود صفين اثنين تماماً. فغالباً ما تتطلب عملية البيع الواحدة في السوق الإلكترونية قيماً مدينة واحدة وعدة قيود دائنة. وهذا هو الجانب الذي غالباً ما يساء فهمه.
لماذا تحتاج الأسواق الإلكترونية إلى دفتر قيد وليس مجرد جدول مدفوعات
تحتفظ السوق الإلكترونية بعدة علاقات مالية في نفس اللحظة؛ حيث يدفع المشتري، ويُسوية معالج الدفع، وقد تتحكم المنصة مؤقتاً في الأموال، بينما يكسب البائع حصة معينة وتحتفظ المنصة بالعمولة، وتصبح الضريبة مستحقة الدفع، وقد يتم احتجاز احتياطي. وفي وقت لاحق، تُخرج عملية الصرف الأموال، بينما تؤدي عمليات الاسترداد (refunds) أو المبالغ المستردة نتيجة اعتراض (chargebacks) إلى عكس جزء من ذلك.
يمكن لجدول payments (المدفوعات) أن يخبرك بالحالة التجارية للطلب، لكنه لا يستطيع إخبارك بدقة بما يلي:
- حجم مستحقات معالج الدفع أو النقد المتاح
- المبلغ المستحق لكل بائع
- حجم الإيرادات الخاصة بالمنصة
- قيمة ضريبة القيمة المضافة المستحقة، وفي أي دولة
- المبلغ المحتجز مقابل عمليات الاسترداد أو النزاعات
- ما إذا كانت عملية الصرف قد خفضت التزام البائع الصحيح أم لا
- ما إذا كانت تسويات معالج الدفع تتطابق مع ما توقعته المنصة
يضع دليل Nordlet لواجهات برمجة تطبيقات دفتر القيد المزدوج لمحاسبة الأسواق الإلكترونية الخطوط الفاصلة بوضوح: تصف جداول التطبيق حالة المنتجات، بينما يسجل دفتر القيد العواقب المالية لتلك الحالة. كما يؤكد على نقطة تستحق التكرار، وهي أن تقارير معالجة الدفع تُعد مدخلات لعملية المطابقة وليست دفاتر قيد مزدوج كاملة.
عملية بيع نموذجية في السوق الإلكترونية
لنفترض أن مشترياً دفع مبلغ 100 يورو، وأن البائع يستحق 85 يورو، وعمولة المنصة تبلغ 15 يورو. ولغرض التوضيح، دعنا نتغاضى عن ضريبة القيمة المضافة ورسوم المعالج.
| الحساب | مدين | دائن | السبب |
|---|---|---|---|
| مستحقات معالج الدفع | 100 يورو | معالج الدفع يدين للمنصة بالمبلغ المحصل | |
| مستحقات البائع | 85 يورو | المنصة تدين للبائع | |
| إيرادات العمولة | 15 يورو | المنصة كسبت عمولتها | |
| الإجمالي | 100 يورو | 100 يورو | متوازن |
التصنيف الهام هنا هو أن مبلغ 85 يورو المستحق للبائع يمثل التزاماً (liability) وليس إيراداً للمنصة. ووفقاً للإطار المفاهيمي للمعايير الدولية لإعداد التقارير المالية (IFRS)، الالتزام هو تعهد حالي لتحويل مورد اقتصادي. ولا ينبغي للسوق الإلكترونية الإبلاغ عن حصيلة مبيعات البائع الكاملة كدخل خاص بها لمجرد أن المشتري دفع من خلالها. وبغض النظر عما إذا كنت تعمل كوكيل، أو أصيل، أو كمورّد اعتباري، فإن المعالجة تتغير بينما يظل آلية دفتر القيد ثابتاً.
عندما يصبح البائع مؤهلاً للصرف، لا يتم تسجيل أي إيراد جديد، بل تقوم بتسوية الالتزام:
| الحساب | مدين | دائن |
|---|---|---|
| مستحقات البائع | 85 يورو | |
| البنك أو حساب المقاصة للصرف | 85 يورو | |
| الإجمالي | 85 يورو | 85 يورو |
إذا اقتطع معالج الدفع رسوماً بقيمة 3 يورو قبل التسوية، تصبح حركة النقد قيداً من ثلاثة أسطر: 97 يورو نقداً في البنك، و3 يورو كمصروفات معالجة، و100 يورو خارجة من مستحقات معالج الدفع. كل تغيير في المركز المالي له مصدر وجهة.
كيف تعمل واجهة برمجة التطبيقات، خطوة بخطوة
1. يكتشف تطبيقك حدثاً تجارياً. يتم تحصيل دفعة، أو تلبية طلب، أو الموافقة على صرف أموال، أو إصدار استرداد، أو فتح نزاع، أو وصول تسوية. وما زال قاعدة بياناتك هي المسؤولة عن الحالة التشغيلية، بينما يسجل دفتر القيد الأثر المالي.
2. ترسل طلباً منظماً. يحمل هذا الطلب عادةً نوع الحدث، المبلغ والعملة، معرف الطلب أو الدفع، معرفات المشتري والبائع، العمولة، بيانات الضرائب، الحسابات المعنية، تواريخ الاستحقاق والترحيل، مفتاح منع التكرار (idempotency key)، والبيانات الوصفية (metadata) التي تربط السجلات بمعالج الدفع والمنتجات. يوضح نموذج واجهة برمجة التطبيقات العامة لشركة Nordlet طلب بيع افتراضي يتضمن معرف البائع، نوع البيع، المبلغ، العملة، ودولة ومعدل ضريبة القيمة المضافة.
3. تتحقق واجهة برمجة التطبيقات من صحة البيانات. تتأكد من توازن المدين والدائن، ووجود الحسابات وقابليتها للترحيل، ودعم العملة، واستخدام معالجة الوحدات الصغرى الدقيقة للمبالغ، وعدم إعادة استخدام مفتاح منع التكرار لنتيجة مختلفة، وأن الفترة المحاسبية مفتوحة، ووجود البيانات الوصفية المطلوبة. أي فشل في التحقق لا يترك وراءه أي قيد يومي جزئي.
4. يتم الترحيل بصورة ذرية (atomically). تُكتب المعاملة الكاملة كوحدة واحدة. لا ينبغي أبداً أن تتمكن من تسجيل الطرف المدين بينما يفشل الطرف الدائن المقابل. بالنسبة للسوق الإلكترونية، قد يؤدي الانقسام الجزئي إلى ظهور رصيد بائع وهمي بدون نقدية مقابلة، أو حجز عمولة بدون الالتزام تجاه البائع.
5. تُستمد الأرصدة والتقارير من دفتر القيد. بعد الترحيل، يمكنك قراءة أرصدة الحسابات، والأرصدة المعلقة والمتاحة للبائع، وميزان المراجعة، وأنشطة دفتر الاستاذ العام، وملخصات ضريبة القيمة المضافة، والسجل التاريخي اعتباراً من تاريخ سابق. يجب أن يكون رصيد البائع قابلاً لإعادة الإنشاء من القيود، وعدم الاعتماد على حقل قابل للتعديل.
6. تخبرك خطافات الويب (webhooks) بتحديثات منتجك. تُرسل إليك أحداث مثل sale_invoice.paid (تم دفع فاتورة البيع)، أو قيد مُرحّل، أو مبلغ متاح للصرف، أو استثناء مطابقة. تعامل معها بشكل متكرر دون آثار جانبية (idempotently). خطاف الويب هو مجرد إشعار، وليس إذناً بتطبيق الحدث المالي للمرة الثانية. تتناول اصطلاحات واجهة برمجة التطبيقات النطاقات، ومفاتيح منع التكرار، وأشكال الأخطاء، وتوقيع خطافات الويب بالتفصيل.
أرصدة البائعين ليست مجرد رقم واحد
توقع العديد من الأسواق الإلكترونية في المشاكل عندما تتعامل مع رصيد البائع كرقم واحد. ينبغي أن تستقر الأموال في حالات محددة:
| الحالة | المعنى |
|---|---|
| معلق (Pending) | قد يكون البائع مستحقاً، لكن شروط الإفراج لم تتحقق بعد |
| متاح (Available) | مؤهل لعملية الصرف |
| محجوز (Reserved) | مُستقطع مقابل الاسترداد، أو المرتجعات، أو النزاعات |
| مسدد (Paid out) | تم تسوية الالتزام عبر التحويل |
| سالب (Negative) | تتجاوز المبالغ المستردة، أو النزاعات، أو الرسوم الأموال المتاحة |
وتعكس نماذج معالجي الدفع هذا التباين. يتيح تدفق العمليات المنفصلة للرسوم والتحويلات في Stripe للمنصة فرض رسوم على حسابها الخاص، ثم تحويل أجزاء إلى الحسابات المرتبطة، مع استقرار الرسوم والاسترداد والنزاعات على رصيد المنصة. بينما يُميز نموذج السوق الإلكترونية لدى Adyen بين حسابات أرصدة المستخدمين، التي تحتفظ بالأموال حتى الصرف، وبين حساب رصيد خاضع للمسؤولية يمكنه استيعاب الأرصدة السالبة الناتجة عن عمليات الاسترداد أو النزاعات. وتُعد هذه المدخلات مفيدة لدفتر القيد الخاص بك، لكنها لا تمثل نموذجك المحاسبي الكامل.
عمليات الصرف وأرباح البائعين تحدث في أوقات مختلفة
يمكن للبائع أن يحقق أرباحاً يوم الإثنين ويتقاضى أمواله في الإثنين التالي. وبين هذين الموعدين، يتم تلبية الطلب، واحتجاز احتياطي، وإنشاء دفعة صرف، وتسوية معالج الدفع لها مطروحاً منها الرسوم، ووصول الإيداع البنكي. ولابد لدفتر القيد أن يحافظ على كل مرحلة بدلاً من الكتابة فوق الطلب بحالة "مدفوع" نهائية. وهذا ما يتيح لك تفسير فروق التوقيت بين نشاط الطلب، واستحقاق البائع، والتسوية، وبدء عملية الصرف، والاستلام البنكي.
عمليات الاسترداد والنزاعات: عكس القيود، وليس إعادة كتابتها
الاسترداد والنزاعات هي أحداث جديدة مرتبطة بالدفعة الأصلية. وفي دفتر القيد غير القابل للتعديل، تقوم بالتصحيح عن طريق إنشاء قيد عكسي يليه قيد مُصحح، ليبقى السجل الأصلي مرئياً لأغراض المراجعة. تتعامل Modern Treasury مع المعاملات المُرحّلة باعتبارها ثابتة وتدعم مفاتيح منع التكرار لمنع تكرار الكائنات عند إعادة المحاولة.
عادةً ما تؤدي عملية الاسترداد إلى تقليل النقد أو مستحقات المشتري، وعكس مستحقات البائع، وقد تعكس جزءاً من العمولة وفقاً للسياسة المتبعة، وتعديل الضريبة، واستهلاك احتياطي الاسترداد. بينما يقلل النزاع من النقد أو مستحقات معالج الدفع، وقد يعيد فتح مبلغ مستحق على البائع أو المنصة، ويسجل مصروفات نزاع ورسوم المعالج، وينقل الأموال عبر حساب احتياطي.
المطابقة: ربط دفتر القيد بالأموال الحقيقية
يمكن أن يكون دفتر القيد متوازناً داخلياً ومع ذلك يكون خاطئاً فيما يتعلق بالعالم الخارجي. تقارن المطابقة السجلات الداخلية بالدلائل الخارجية مثل: تقارير تسوية معالج الدفع، الكشوفات البنكية، ملفات الصرف، سجلات الاسترداد والنزاعات.
دورة العمل القابلة للتنفيذ تبدو كالتالي:
- استيراد التسوية أو الدفعة البنكية.
- مطابقة كل سطر مع طلب، أو دفعة، أو استرداد، أو رسوم، أو صرف، أو نزاع.
- مقارنة الإجمالي المتوقع، الاستقطاعات، الاحتياطيات، والمصافي.
- ترحيل الحركات المؤكدة إلى دفتر القيد.
- إرسال العناصر غير المطابقة إلى حساب معلق مُسمّى (suspense account).
- التحقيق في الاستثناءات.
- إقفال الفترة المحاسبية.
تصف مواد المطابقة الخاصة بشركة Nordlet هذا الأمر بدقة، من خلال استيراد دفعات التسوية، ومطابقة خطوط الرسوم والاسترداد، وتوجيه الإيصالات غير المطابقة إلى حساب معلق بدلاً من تخمين الفاتورة. هناك عمليتا تحقق مهمتان ولا تحل إحداهما محل الأخرى: يتحقق التحقق من القيد المزدوج مما إذا كان كل قيد يومي متوازناً، بينما تسأل المطابقة عما إذا كانت تتفق مع معالج الدفع، والبنك، والحدث التجاري.
تفاصيل تصميمية تقرر ما إذا كنت قد نفذت هذا بالشكل الصحيح
منع التكرار (Idempotency). اربط المفتاح بحدث مستقر، مثل payment_captured:pi_123. تعيد إعادة المحاولة النتيجة الأصلية، وليس قيداً ثانياً.
الذرية (Atomicity). إما أن ترحل جميع أسطر الحدث الواحد معاً أو لا يرحل أي منها.
الثبات والعكس (Immutability and reversals). لا يمكن تعديل السجل التاريخي المُرحّل من خلال التحديثات العادية. بل تُنشئ التصحيحات قيوداً مرتبطة تحافظ على المبلغ الأصلي، والتاريخ، والتصنيف، والسبب، واسم المنشئ.
دقة الأموال. لا تستخدم الأرقام الثنائية الفاصلة العائمة (floating point). استخدم وحدات صغرى صحيحة للأعداد أو عشريات دقيقة، وعملة صريحة، وقاعدة تقريب حتمية للتقسيمات. إذا قمت بتقسيم 100 يورو بين البائعين والرسوم بدون قاعدة واحدة، فسوف يكسر سنت ضائع توازنك.
تواريخ الاستحقاق مقابل تواريخ الترحيل. تختلف تواريخ دفع المشتري، وكسب البائع، وتسوية البنك، وترحيل القيد. إن دمج هذه التواريخ معاً يجعل التقارير الدورية وتوقيت الضرائب غير موثوقين.
العملات المتعددة. يجب أن يتوازن المدين والدائن داخل العملة الواحدة. يتطلب التحويل حدث سعر صرف صريح مع حسابات للرسوم، والتقريب، وأي مكاسب أو خسائر في أسعار الصرف (FX). قبول حقل currency (العملة) لا يحول دفتر القيد إلى محرك صرف أجنبي.
ما لن تقوم به واجهة برمجة تطبيقات دفتر القيد نيابة عنك
لن تقرر واجهة برمجة التطبيقات شجرة الحسابات (chart of accounts) الخاصة بك. سيتعين عليك أنت تحديد ما إذا كنت أصيلاً أم وكيلاً، ومتى يتم اكتساب العمولة، وأي طرف يتحمل رسوم معالج الدفع، وكيف تؤثر عمليات الاسترداد على العمولة، وكيف يتم حساب ضريبة القيمة المضافة والإبلاغ عنها. إرشادات Nordlet الخاصة تتمثل في رسم تدفقات الأموال أولاً، ثم مسودة شجرة الحسابات، ومراجعتها بواسطة محاسب، ثم تنفيذ دورة كاملة واحدة بدءاً من الطلب وصولاً إلى الصرف والمطابقة قبل التوسع.
ولن تحل مسائل الضرائب. تعتمد ضريبة القيمة المضافة على موقع المشتري والبائع، ونوع المنتج، وحالة التسجيل، وقواعد المورد الاعتباري؛ حيث يوضح دليل ضريبة القيمة المضافة في الاتحاد الأوروبي ما يستخرجه المحرك وما يشير إليه للمراجعة البشرية. تركز تغطية Nordlet لضريبة القيمة المضافة على الاتحاد الأوروبي والمنطقة الاقتصادية الأوروبية (EEA)، لذا فهي لا تمتد لتشمل ضريبة المبيعات الأمريكية أو الفوترة الإلكترونية في أمريكا اللاتينية. ولن تحل الغموض التشغيلي أيضاً، مثل ما إذا كانت فترة الإرجاع قد انتهت، أو ما إذا كان ينبغي حظر عملية الصرف، أو ما إذا كانت الدفعة احتيالية. تلك قرارات تخصك وحدك، ويسجل دفتر القيد النتيجة المالية لها.
أين تقع شركة Nordlet
Nordlet هي واجهة برمجة تطبيقات محاسبية مصممة للمنصات والأسواق الإلكترونية، وتتميز بدفتر قيد مزدوج غير قابل للتعديل، ومدفوعات، ومعالجة ضريبة القيمة المضافة في الاتحاد الأوروبي، ونقاط نهاية REST، وحزم تطوير البرمجيات المكتوبة بأنواع محددة (typed SDKs)، وخطافات ويب يمكن الوصول إليها من خلال واجهة واحدة. وتتمثل ميزتها البارزة في دمج المحاسبة داخل منتجك الخاص بدلاً من استخدام صفحة دفع خارجية. وقت كتابة هذه السطور، يتوفر المنتج في مرحلة الوصول المبكر مع بيئة تجريبية لشركاء التصميم، لذا يجب اعتباره مثالاً قوياً لهذه الفئة مع تقييم نضج الإنتاج، ووقت التشغيل، والتغطية القضائية لحالتك الخاصة قبل الالتزام.
بالنسبة لمطوري الأسواق والمنصات، فإن النموذج الذهني المفيد هو الفصل بين حركة الدفع والحقيقة المالية. يقوم معالج الدفع الخاص بك بتحريك الأموال، بينما تسجل واجهة برمجة تطبيقات دفتر القيد المزدوج من له ماذا، وما الذي كسبته، وما تحمله من ضرائب واحتياطيات، وما إذا كان العالم الخارجي يطابق دفاتر حساباتك.
الأسئلة الشائعة (FAQ)
هل واجهة برمجة تطبيقات دفتر القيد المزدوج هي نفسها معالج الدفع؟
لا. يقوم معالج الدفع بالترخيص، والتحصيل، والتسوية، ودفع الأموال أحياناً. بينما تسجل واجهة برمجة تطبيقات دفتر القيد العواقب المحاسبية لتلك الأحداث. تستخدم معظم الأسواق الإلكترونية الاثنين معاً؛ معالج مثل Stripe أو Adyen للحركة، ودفتر قيد للحسابات.
هل يمكنني فقط استخدام لوحة تحكم معالج الدفع كدفتر أستاذ عام؟
يمكنك المحاولة، ولكنها ستفشل في المراجعة عاجلاً أم آجلاً. تُظهر تقارير معالج الدفع الرسوم، والرسوم، والتحويلات، والتسويات، لكنها عادة لا تمثل التزاماتك الكاملة تجاه البائعين، أو التزاماتك الضريبية، أو المصروفات بخلاف معالج الدفع، أو التسويات المحاسبية. تعامل معها كمدخل للمطابقة فقط.
هل يعني دفتر القيد المتوازن أن دفاتري صحيحة؟
فقط بمعنى أن قيودك تلبي قاعدة المدين والدائن. فالمعاملة المتوازنة تماماً يمكن إدراجها في الحساب الخاطئ، أو للبائع الخاطئ، أو بمعالجة ضريبية خاطئة. التوازن أمر ضروري، لكنه ليس كافياً بمفرده. والمطابقة هي ما يلتقط الباقي.
إذا كان دفتر القيد غير قابل للتعديل، فكيف أصلح الأخطاء؟
أنت تقوم بترحيل قيد عكسي ثم قيد مُصحح. يبقى السجل الأصلي مرئياً، وهذا هو الغرض الأساسي. يحمي الثبات مسار المراجعة، ولكنه لا يحبس أخطاءك.
هل تجعلني واجهة برمجة التطبيقات المحاسبية متوافقاً مع اللوائح تلقائياً؟
لا. فهي تفرض الهيكل المحاسبي وتنتج سجلات قابلة للاستخدام. ومع ذلك، يظل الامتثال القانوني معتمداً على ولايتك القضائية، ودورك التعاقدي، والمعالجة الضريبية، لوائح الدفع، وإجراءات اعرف عميلك (KYC) ومكافحة غسيل الأموال (AML)، والتزامات إعداد التقارير.