واجهة API لتتبّع النفقات في 2026: أتمت المعاملات والميزانيات بأمان

قد تعيد واجهة API لتتبّع النفقات الاستجابة 200 OK بعدما تسجّل تحويلًا بقيمة 900 دولار إلى حساب الادخار على أنه إنفاق بقيمة 900 دولار. نجح الطلب تقنيًا، لكن مسك الدفاتر فشل.

هذه هي الصعوبة الحقيقية في أتمتة الشؤون المالية الشخصية. إرسال SQL أو JSON عبر HTTPS عمل هندسي معتاد. أما الحفاظ على المعنى الصحيح للحسابات والتحويلات والمصروفات وخطط الميزانية، فهو ما يمنع أتمتة تبدو سليمة من إفساد الدفاتر من دون أن يلاحظ أحد.

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

فيما يلي طريقة بناء سير العمل هذا باستخدام واجهة SQL المقيّدة في Expense Budget Tracker.

نموذج البيانات هو ما يحدد أمان الأتمتة

ابدأ بالحدود المحاسبية، لا بقائمة نقاط النهاية.

المفهوم	معناه	خطأ شائع في الأتمتة
الحساب	المكان الذي يُحتفظ فيه بالمال أو تُسجّل عليه الديون	التعامل مع الرصيد الحالي على أنه معاملة جديدة
قيد دفتر الأستاذ	حركة مالية حدثت فعلًا	خلط المبالغ المخطط لها بالإنفاق الفعلي
التحويل	حركة مالية بين حساباتك الخاصة	احتساب الطرف الصادر مصروفًا
بند الميزانية	خطة لفئة ضمن فترة زمنية	استبدال الخطة بالإنفاق الفعلي ومحو الفرق بينهما
مساحة العمل	نطاق البيانات الخاص بشخص أو مجموعة	كتابة بيانات صحيحة في الدفاتر الخطأ

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

أهم تمييز هنا هو الفرق بين النتائج الفعلية والخطط:

• تسجّل قيود دفتر الأستاذ ما حدث فعلًا.
• تسجّل بنود الميزانية ما كنت تنوي فعله أو ما تخطط له الآن.
• تقارن التقارير بينهما؛ لذلك يجب ألّا تدمجهما عملية الاستيراد.

تعتمد مزايا جدول الميزانية وتتبع الأرصدة في Expense Budget Tracker على هذا الفصل. ويجب على عميل API الحفاظ عليه أيضًا.

ابدأ بالعقد المنشور حاليًا

نقطة الدخول العامة هي وثيقة اكتشاف Expense Budget Tracker. تصف الوثيقة مسار المصادقة الحالي، وتربط بـ مواصفة OpenAPI، وتخبر البرنامج النصي أو الوكيل بما يجب استدعاؤه بعد ذلك.

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

تسلسل الإعداد الحالي هو:

1. حمّل GET https://api.expense-budget-tracker.com/v1/.
2. أرسل بريد المستخدم الإلكتروني إلى العنوان الذي تعرضه الاستجابة في bootstrapUrl.
3. اطلب الرمز المكوّن من 8 أرقام والمرسل عبر البريد الإلكتروني، ثم اتبع إجراء التحقق الذي تعرضه الاستجابة.
4. احفظ ApiKey طويل الأمد خارج ذاكرة الدردشة.
5. حمّل /v1/me، واعرض قائمة /v1/workspaces، واختر مساحة العمل المقصودة.
6. بعد المصادقة، حمّل /v1/schema للاطلاع على العلاقات والأعمدة والعمليات المسموح بها والقيود والإرشادات المتاحة للوكلاء الذين يستخدمون هذا المفتاح.
7. اقرأ البيانات عبر /v1/sql قبل اقتراح أي تعديل.
8. نفّذ التغيير الذي حصل على الموافقة فقط، ثم استعلم عن البيانات المتأثرة مرة أخرى.

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

اكتشف الواجهة وصادِق الاتصال

وثيقة الاكتشاف متاحة للعامة:

curl --fail --silent --show-error \
  https://api.expense-budget-tracker.com/v1/

بعد التحقق، احتفظ بالمفتاح الذي تعيده الخدمة في مخزن أسرار معتمد أو في متغير بيئة محلي. استخدم قيمة نائبة واضحة في الوثائق والبرامج النصية؛ فلا فائدة من مفتاح وهمي يبدو حقيقيًا.

export EXPENSE_BUDGET_TRACKER_API_KEY="<paste-returned-key-here>"

تستخدم الطلبات التي خضعت للمصادقة مخطط التفويض الكامل ApiKey:

curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/me

اجعل اختيار مساحة العمل صريحًا

اعرض مساحات العمل المتاحة لمالك المفتاح، واختر المساحة التي حدّدها المستخدم فعلًا، ثم احفظ هذا الاختيار للمفتاح:

curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/workspaces

export EXPENSE_BUDGET_TRACKER_WORKSPACE_ID="<workspace-id-from-list>"

curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  "https://api.expense-budget-tracker.com/v1/workspaces/$EXPENSE_BUDGET_TRACKER_WORKSPACE_ID/select"

بعد هذا الاختيار، يمكن لطلبات /v1/sql اللاحقة الاستغناء عن X-Workspace-Id. وتظل الترويسة متاحة لتجاوز الاختيار في طلب واحد. تعامل معها على أنها تبديل مقصود، لا وسيلة مريحة مخفية داخل دالة مساعدة: فأسهل طريقة لوضع بيانات صحيحة في المكان الخطأ هي إخفاء سياق مساحة العمل.

افحص المخطط المتاح لهذا المفتاح

يصف مستند OpenAPI طريقة الاتصال بالواجهة. أما /v1/schema، المتاح بعد المصادقة، فيصف نطاق قاعدة البيانات الذي تستطيع مساحة العمل المحددة استخدامه.

curl --fail --silent --show-error \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  https://api.expense-budget-tracker.com/v1/schema

اقرأ الاستجابة كاملة قبل توليد SQL. تحقّق من:

• الأسماء الدقيقة للعلاقات والأعمدة
• العمليات المسموح بها لكل علاقة
• الحقول المطلوبة والقيود
• الإرشادات الخاصة بالتحويلات وغيرها من دلالات الكتابة
• القيود المفروضة على صياغة SQL ودوالها

تحدد استجابة الاكتشاف الحالية العلاقات ledger_entries وbudget_lines وworkspace_settings وaccount_metadata على أنها قابلة للكتابة وفق قواعد الموافقة الحالية. أما العرض المشتق accounts وعلاقات أسعار الصرف التي يتولى العامل إدارتها، فهي للقراءة فقط. وهذا مهم: تغيير رصيد حساب يعني تغيير بيانات دفتر الأستاذ المناسبة، لا تحديث عرض الحسابات المشتق.

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

اقرأ سياقًا كافيًا قبل الكتابة

يبدأ سير العمل الآمن لـ واجهة API للتمويل الشخصي بسؤال بسيط: ما الذي يمثّل الواقع بالفعل داخل مساحة العمل هذه؟

قبل أي عملية استيراد أو تعديل، تأكد من أن:

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

تعتمد الاستعلامات الدقيقة على المخطط الحالي. ولإجراء فحص اتصال صغير، تأكد من اسم العلاقة في /v1/schema، ثم استعلم عن عرض الحسابات المشتق:

curl --fail --silent --show-error \
  -X POST \
  -H "Authorization: ApiKey $EXPENSE_BUDGET_TRACKER_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.expense-budget-tracker.com/v1/sql \
  -d '{"sql":"SELECT * FROM accounts LIMIT 10"}'

تحتوي الاستجابة الحالية على مصفوفة statements، ولكل عبارة فيها الحقول rowCount وreturnedRowCount وtotalRowCount وtruncated. اقرأ هذه الحقول. فنجاح تحليل JSON لا يثبت أنك استلمت مجموعة النتائج كاملة.

أبقِ التحويلات خارج إجماليات النفقات

لنفترض أن 900 دولار انتقلت من الحساب الجاري إلى حساب الادخار. خرج المال من حساب ووصل إلى آخر، لكن الأسرة لم تنفق 900 دولار.

قد يرى برنامج استيراد ضعيف قيد الخصم أولًا ويصنّفه مصروفًا ضمن الادخار. وقد يسجّل برنامج آخر قيدي الخصم والإيداع كمعاملتين منفصلتين، فيضخّم حركة الحساب ويفسد التسوية لاحقًا. أما العميل الجيد لـ واجهة API للمعاملات، فيتعرّف على التحويل قبل الكتابة ويستخدم البنية المترابطة التي يصفها المخطط الحالي.

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

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

لهذا تحتاج واجهة API لإدارة النفقات إلى فهم دلالات دفتر الأستاذ. ولا يأتي التصنيف إلا بعدما يفهم العميل كيف تحرك المال.

أبقِ خطط الميزانية منفصلة عن النتائج الفعلية في دفتر الأستاذ

يجب ألّا تعمل واجهة API للميزانية كمخزن ثانٍ للمعاملات.

تخيّل خطة للبقالة في أغسطس بقيمة 500 دولار، ومشتريات فعلية بقيمة 620 دولارًا. النتيجة المفيدة هي فرق قدره 120 دولارًا. وإذا عدّلت الأتمتة خطة أغسطس إلى 620 دولارًا أثناء استيراد المعاملات، فإنها تمحو القرار الأصلي وتجعل التقرير أقل فائدة.

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

يقرأ سير العمل السليم الخطط والنتائج الفعلية، ويحسب الفرق، ويقترح تغييرًا في ميزانية مقبلة. ولا ينبغي أن يؤدي استيراد المعاملات إلى تعديل الخطة كأثر جانبي.

ضع الموافقة قبل أول تعديل

قبل أن تطلب من شخص الموافقة على عملية كتابة، اعرض مجموعة تغييرات يستطيع تقييمها فعلًا:

• مساحة العمل والحساب المحددان
• العلاقة والنطاق الزمني المتأثران
• عدد صفوف المصدر وعدد قيود دفتر الأستاذ وإجمالياتها المتوقعة
• طريقة التعامل مع التكرارات والتحويلات
• تغييرات الميزانية، إن وجدت، منفصلة عن تغييرات المعاملات
• الاستعلامات التي ستتحقق من النتيجة

عبارة «رتّب شؤوني المالية» ليست موافقة ذات معنى. أما «استورد هذه الصفوف البالغ عددها 64 إلى حساب اليورو الجاري للفترة من 1 إلى 31 يوليو، مع مطابقة أربعة تحويلات وعدم إجراء أي تغيير على الميزانية» فهي أقرب بكثير إلى موافقة واضحة.

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

اختبر بنية الكتابة، ثم استخدم دفعات مدروسة

يسمح عقد OpenAPI المباشر لـ /v1/sql باستقبال عبارة واحدة أو أكثر من عبارات SELECT أو WITH أو INSERT أو UPDATE أو DELETE مفصولة بفواصل منقوطة. دعم العبارات المتعددة مفيد، لكنه ليس سببًا لحشر عملية استيراد كاملة في طلب واحد مبهم.

عند تنفيذ أمر INSERT طويل، أرسل أولًا بنية SQL نفسها مع صف واحد إلى ثلاثة صفوف فعلية من البيانات الموافق عليها. وعند تنفيذ أمر UPDATE طويل، استهدف أولًا صفًا واحدًا شملته الموافقة. استخدم صفوفًا حقيقية من مجموعة التغييرات بدل سجلات مالية وهمية ستضطر إلى حذفها لاحقًا.

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

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

ينص عقد SQL المقيّد الحالي أيضًا على ما يلي:

• ON CONFLICT غير مدعوم
• لا يُسمح إلا باستدعاءات الدوال SUM وCOUNT وMIN وMAX وAVG وCOALESCE
• يجب استخدام ILIKE في عمليات البحث غير الحساسة لحالة الأحرف
• يجب أن تستخدم مرشحات التاريخ نطاقات صريحة بدل دوال التاريخ التي تعمل وقت التنفيذ
• تستخدم القيم النصية الحرفية علامات اقتباس مفردة عادية؛ أما السلاسل النصية المحاطة بعلامات الدولار فهي محظورة

اقرأ هذه القواعد من OpenAPI الحالي ومن /v1/schema كلما أنشأت عميلًا قابلًا لإعادة الاستخدام أو حدّثته. فهي جزء من الواجهة، لا تفاصيل عرضية في التنفيذ.

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

سوِّ الحسابات بعد كل عملية كتابة

يعني نجاح HTTP أن الخادم قبل الطلب. أما التسوية، فتبيّن إن كانت النتيجة المالية صحيحة.

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

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

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

لكل عبارة يعيدها /v1/sql، افحص عدد الصفوف وبيانات اقتطاع النتائج، ثم اقرأ السجلات المتأثرة مجددًا عبر استعلام منفصل. لا تمثل استجابة واجهة API للبيانات المالية سوى دليل واحد. ويجب أن تتفق قيود دفتر الأستاذ والإجماليات ومستند المصدر.

اختر برنامجًا نصيًا أو وكيلًا بحسب المدخلات

يناسب البرنامج النصي الذي ينفّذ قواعد ثابتة تنسيق CSV واحدًا ومستقرًا. أما وكيل الذكاء الاصطناعي، فيفيد عندما تتطلب ملفات PDF أو لقطات الشاشة أو أوصاف التجار غير المتسقة أو قرارات التصنيف قدرًا من التفسير. وفي الحالتين، يجب اتباع تسلسل الاكتشاف والموافقة والتسوية نفسه.

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

تفيد وثيقة الاكتشاف الوكلاء بوجه خاص: إذ يستطيع Claude Code أو Codex أو أي أداة أخرى قادرة على استخدام HTTP أن تبدأ بعنوان URL واحد وتتبع الإجراءات التي تعيدها الخدمة. ويظل المستخدم مسؤولًا عن تقديم رمز البريد الإلكتروني، والموافقة على عمليات الكتابة، والاحتفاظ بـ ApiKey خارج ذاكرة الدردشة.

راجع دليل تتبّع النفقات باستخدام Claude Code لمعرفة طريقة الإعداد من الطرفية، أو الدليل الأوسع حول تتبّع النفقات وإعداد الميزانية بالذكاء الاصطناعي للاطلاع على سير العمل. أما المطورون الذين يريدون التحكم في المنظومة التقنية كاملة، فيمكنهم اتباع دليل متتبّع الميزانية مفتوح المصدر والقابل للاستضافة الذاتية.

قائمة تحقق لأول عملية أتمتة

اتبع هذا الترتيب في مهمة حقيقية واحدة ومحددة:

1. حمّل وثيقة الاكتشاف المباشرة ومواصفة OpenAPI.
2. أكمل المصادقة برمز البريد الإلكتروني واحفظ ApiKey خارج الدردشة.
3. حمّل سياق الحساب، واعرض مساحات العمل، واختر المساحة المقصودة.
4. افحص /v1/schema بعد المصادقة، بما في ذلك العمليات والإرشادات.
5. اقرأ الحساب المستهدف والنطاق الزمني والفئات وسياق الميزانية.
6. اعرض مجموعة تغييرات محددة واحصل على موافقة بشرية.
7. أرسل اختبار الكتابة التمثيلي المطلوب.
8. تابع العمل الموافق عليه في دفعات متسلسلة لا تتجاوز 100 سجل.
9. اقرأ البيانات المتأثرة مجددًا وافحص حدود النتائج.
10. سوِّ الأرصدة والأعداد والتحويلات وإجماليات الميزانية.

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

وبعد ذلك، أتمت الجزء الممل التالي.