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

ما تحتاج إليه

  • مفتاح API يتضمن إذن بيانات البنك، لتطبيق البيئة التجريبية الخاص بك. راجع دليل البدء السريع.
  • وجهة webhook تستقبل أحداث bank.*. راجع webhook الخاص بالبنوك.
  • جدول في قاعدة بياناتك لكل معرّف اتصال للعميل، ومؤشر تغذية التغييرات، وتاريخ انتهاء الموافقة.

الخطوة 1: إنشاء رابط بوصول مستمر

  • access: ongoing يُبقي الوصول مفتوحاً حتى تنتهي الموافقة. consent_days طلبٌ فقط: البنك هو من يحدد التاريخ الفعلي، ويظهر هذا التاريخ على الربط.
  • history_from يطلب السجل منذ تاريخ محدد، مثلاً بداية السنة. استخدم بدلاً منه history_days (من 1 إلى 365) إن فضّلت ذلك، ولا تستخدمهما معاً أبداً. قد يسلّم البنك أقل من ذلك: يُبلغ كل حساب عن history_coverage الخاصة به.
  • ownership.compare: none يتخطى مقارنة صاحب الحساب، فلا حاجة إلى هوية مرجعية. استخدم business لمقارنة صاحب الحساب بشركة موثّقة في Didit.
  • end_user.reference هو معرّفك للعميل. يمكن البحث به، ويتيح لـ Didit التعرّف على العميل نفسه عندما يربط الحسابات نفسها مرة أخرى.
  • أرسل العميل إلى صفحة التحقق المستضافة وأعده إلى منتجك عبر رابط إعادة التوجيه.
احفظ id الرابط مع العميل.

الخطوة 2: انتظار الاتصال

عندما يُكمل العميل العملية، يصل الحدث bank.link.completed ومعه connection_id. أكِّد ذلك، فالمتصفح لا يُعتمد عليه أبدًا:
احفظ connection_id وانتظر الحدث bank.connection.created: عندئذٍ تصبح الحسابات والأرصدة والمعاملات الأخيرة قابلة للقراءة (تكون قيمة sync.initial_status هي succeeded أو partial). يصل بعد ذلك bank.connection.history_complete عند انتهاء استرجاع البيانات السابقة. يوضح history_coverage.oldest_booking_date لكل حساب إلى أي تاريخ وفّر البنك البيانات فعليًا.

الخطوة 3: تحميل النسخة الأولى

يُرجع المؤشر الفارغ كل المعاملات الحالية بالقيمة added مع reset: true. استعرضها صفحة تلو الأخرى، ولا تحفظ المؤشر إلا في النهاية:
  • القراءة الأولى لقطة حقيقية: تُرجع كل معاملة كانت مرتبطة بالاتصال عند بدء القراءة، كل واحدة مرة واحدة فقط بالقيمة added، وبحالتها الحالية، حتى لو تمت مزامنة أثناء استعراض الصفحات.
  • تصل التغييرات التي تحدث أثناء استعراض الصفحات في القراءة التالية من next_cursor: تعود المعاملة التي استلمتها سابقاً بالقيمة modified، وتصل المعاملة الجديدة بالقيمة added.
  • لا تحفظ next_cursor إلا بعد استجابة تحمل has_more: false.
  • إذا فشل استعراض الصفحات في منتصف العملية، فأعد البدء من المؤشر الذي حفظته.
  • اقرأ الأرصدة عبر GET /v3/bank/accounts/{account_id}/balances/.

الخطوة 4: حافظ على تحديث البيانات مع كل webhook

يقوم Didit بمزامنة كل اتصال مستمر نشط تلقائياً بين مرة وأربع مرات في اليوم، حسب البنك (sync.frequency_per_day). عندما تُخزّن المزامنة تغييرات، يصل bank.data.updated مع connection_id وaccount_ids والأعداد. استدعِ خلاصة التغييرات باستخدام المؤشر المخزّن لديك:
  • added هي المعاملات الجديدة، بما فيها المعاملات المعلّقة.
  • modified هي المعاملات التي تغيّرت، بحالتها الحالية. طبّق كل معاملة كعملية إدراج أو تحديث بحسب id: إذا كانت لديك المعاملة فسيتم تحديثها، وإذا لم تكن لديك فستُضاف.
  • removed تحمل reason. تجاهل id غير الموجود لديك. عند ترحيل معاملة معلّقة، تخرج من removed بالقيمة pending_booked ويصل المعاملة المرحّلة في added.
استخدم id المعاملة مفتاحاً لديك، فهو يبقى كما هو عبر القراءات والمزامنات والتجديدات. تحقّق من identity_quality: مع derived، قد يظهر تصحيح من البنك كعنصر واحد في removed وعنصر واحد في added. لا تُفرض أي رسوم على القراءات أبداً، لكن البيانات لا تتغير إلا عند تشغيل مزامنة، لذا تكفي قراءة واحدة لكل webhook. لجلب البيانات بشكل أسرع، استخدم Sync Now: تحديث بيانات البنك عند الطلب.

الخطوة 5: التعامل مع إعادة الضبط

أي مؤشر أقدم من نافذة إعادة التشغيل يُرجع الرد 410 cursor_expired مع bootstrap: true. سجل التغييرات قابل لإعادة التشغيل لمدة 90 يومًا، لذلك يكاد هذا الأمر لا يحدث لمهمة يومية. ابدأ من جديد بمؤشر فارغ، واستبدل نسختك بالنتيجة بدلًا من إضافتها إليها. كل قراءة من مؤشر فارغ تحمل reset: true، لذلك يعالج المسار البرمجي نفسه الاتصال الجديد والمؤشر المنتهي الصلاحية.

الخطوة 6: متابعة انتهاء الموافقة

للموافقة تاريخ انتهاء: consent.expires_at. يرسل Didit الحدث bank.connection.consent_expiring قبل الانتهاء بـ 14 يومًا و7 أيام ويومٍ واحد. استدعِ renew_connection عندما تريد التجديد. تُرجع العملية 409 renewal_not_needed حتى يتبقى 30 يومًا. صفحة يُكمل فيها العميل التجديد غير متاحة بعد. إذا سمح العميل بانتهاء الموافقة، يصبح الاتصال في حالة renewal_required، ولكن ما زال بإمكانك قراءة البيانات التي تمت مزامنتها. التفاصيل موجودة في تجديد موافقة البنك.

الخطوة 7: إيقاف الوصول وحذف البيانات

  • يغادر العميل منتجك: استدعِ revoke_connection لإيقاف القراءة فورًا، أو delete_connection لإيقاف القراءة وحذف البيانات المخزَّنة.
  • يتوقف العميل عن المشاركة مع البنك: يصل الحدث bank.connection.revoked مع ended_by. أوقف تغذية البيانات لذلك الاتصال.

السعر

تتم فوترة الوصول المستمر لكل اتصال نشط شهريًا. يشمل السعر جميع حسابات الاتصال، والأرصدة، والمعاملات، وحتى 365 يومًا من السجل حيثما يوفّره البنك، والمزامنات التلقائية، والمزامنات الفورية ضمن حدود البنك، والتجديدات، وwebhook، وجميع عمليات القراءة. الرابط الذي لا يُكمله أحد مجاني، وكذلك الاتصالات في حالة renewal_required أو paused أو revoked. راجع الأسعار.

قائمة التحقق

  • اتصال واحد لكل عميل ولكل بنك، يُخزَّن مع المؤشر وتاريخ انتهاء الموافقة.
  • معالج webhook يتسم بـ idempotency، ويعتمد معرّف الحدث مفتاحًا له.
  • reset: true يستبدل نسختك ولا يضيف إليها أبدًا شيئًا.
  • معالجة removed مع سبب الإزالة.
  • ربط تذكيرات الموافقة بإشعارك الخاص للعميل.
  • bank.connection.revoked يوقف تدفق البيانات.
  • تجتاز الخطة في البيئة التجريبية.
آخر تعديل في ٢٢ نوفمبر ٢٠٢٦