الانتقال إلى المحتوى الرئيسي
تُخزّن واجهة Didit لبيانات البنوك الحسابات والأرصدة والمعاملات الخاصة بكل اتصال، وتُقدّمها عبر نقاط نهاية للقراءة مع ترقيم الصفحات (cursor في القوائم، وpage_token في قراءات المعاملات). المبالغ سلاسل نصية عشرية، مع حقل منفصل للعملة currency وفق معيار ISO 4217، والتواريخ بتنسيق ISO 8601، والدول بتنسيق ISO alpha-3. عمليات القراءة لا تخضع للفوترة أبداً.

الحسابات

GET /v3/bank/connections/{id}/accounts/ يسرد حسابات الاتصال، وGET /v3/bank/accounts/{account_id}/ يعيد حسابًا واحدًا. استخدم account_ref للتعرف على حساب بنكي عندما يعيد الشخص ربطه، واستخدم id لكل ما يتعلق بالاتصال الواحد.

الأرصدة

تُعيد GET /v3/bank/accounts/{account_id}/balances/ الأرصدة مُصنَّفة حسب النوع مع تواريخ المرجع الخاصة بها.
القيمة في type هي booked أو available أو expected، ويحمل iso_type رمز ISO 20022 الخاص بالبنك عندما يوفره البنك.

المعاملات

تقرأ GET /v3/bank/accounts/{account_id}/transactions/ نطاقًا من التواريخ. يقبل date_from وdate_to (تواريخ تقويمية كما يسجّلها البنك، وكلاهما شامل)، وstatus (booked أو pending، وكلاهما افتراضيًا)، وlimit (حتى 500)، وpage_token. ترتّب النتائج تنازليًا حسب effective_date، ثم حسب id.
  • id معرّف تمنحه Didit، ويُحفظ عند أول ظهور للحركة. تحتفظ الحركة بالمعرّف نفسه عبر القراءات والمزامنات والتجديدات.
  • identity_quality يوضّح قوة هذا الضمان. bank_reference وroute_id ثابتان. أما derived فيعني أن الحركة جرت مطابقتها بمحتواها، لذلك قد يظهر تصحيح البنك على شكل عنصر واحد بحالة removed وعنصر آخر بحالة added.
  • status قيمته booked أو pending. تحمل المعاملة المعلّقة معرّفًا خاصًا بها. عندما يقيّدها البنك، تصل المعاملة المقيّدة بحالة added، وتصل المعاملة المعلّقة بحالة removed مع reason: pending_booked، ويُضبط pending_id فقط عندما يربط البنك بينهما.
  • amount موقّع: القيمة السالبة تعني أن المال خرج. ويكرّر direction الإشارة نفسها.
  • bank_reference مرجع القيد الثابت الذي يمنحه البنك، ويكون null عندما لا يوفّره البنك. ولا تختلقه Didit أبدًا.
  • category تصنيف تضعه Didit بنفسها، عندما يكون التصنيف مناسبًا.
  • التصحيح الذي يجريه البنك على معاملة مقيّدة يظهر بحالة modified. أما المعاملة العكسية فهي معاملة جديدة، ويُضبط reverses_id عندما يربط البنك بينهما.

الحقول التي لا يرسلها البنك تكون null

كل حقل لا يرسله البنك تكون قيمته null. تسرد المؤسسة الحقول التي يُعرف أنها ترسلها في transaction_fields، إلى جانب pending_transactions وpending_linkage وbalance_types وhistory_days_max، حتى لا يكتشف أحد الفجوات لأول مرة في بيئة الإنتاج. استخدم عميل الاختبار sparse_fields في البيئة التجريبية لاختبار شيفرتك مع بنك يرسل بيانات قليلة.

التنقل بين صفحات نطاق التواريخ

واصل القراءة باستخدام page_token ما دامت القيمة has_more تساوي true. يثبّت الرمز لقطة القراءة لمدة ساعة واحدة: لا تشمل اللقطة الإضافات التي تظهر بعد الصفحة الأولى، ويُعاد كل صف بحالته الحالية، والصف الذي يُحذف أثناء التنقل يخرج من الصفحات اللاحقة ويظهر في تغذية التغييرات. إذا انتهت صلاحية الرمز، يُرجع الطلب 410 page_expired، فأعد القراءة من استعلامها الأصلي.

تدفق التغييرات

GET /v3/bank/connections/{id}/transactions/sync/ يُرجع ما تغيّر في جميع حسابات الاتصال منذ cursor.
  • إذا كان المؤشر فارغًا، يُرجع كل المعاملات الحالية كعناصر added مع reset: true. استبدل نسختك بها بدلًا من إضافتها إليها.
  • واصل التصفح باستخدام page_token ما دامت قيمة has_more هي true. لا تخزّن next_cursor إلا بعد استجابة تكون فيها has_more: false. وإذا فشل التصفح في منتصفه، فأعد البدء من المؤشر الذي خزّنته.
  • المؤشر غير شفاف، ومرتبط بالاتصال والبيئة. سجل التغييرات قابل لإعادة التشغيل لمدة 90 يومًا. المؤشر الأقدم من ذلك يُرجع 410 cursor_expired مع bootstrap: true: ابدأ من جديد بمؤشر فارغ، واستبدل نسختك.
  • قيمة removed[].reason تكون واحدة من: pending_booked أو pending_expired أو bank_removed أو access_removed.
الخطوات التفصيلية موجودة في تغذية بنكية مستمرة للمحاسبة.

الرؤوس

تُعيد كلتا عمليتي قراءة المعاملات الرؤوس X-RateLimit-* (600 قراءة و300 كتابة في الدقيقة لكل تطبيق، ويُرجع الطلب 429 مع Retry-After عند تجاوز ذلك) وX-Bank-Last-Synced-At. حدود API وحدود البنك الخاصة بجلب البيانات أمران منفصلان: راجع تحديث بيانات البنك عند الطلب.
آخر تعديل في ٢٢ نوفمبر ٢٠٢٦