> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# التغذية البنكية المستمرة للمحاسبة: الأرصدة والمعاملات

> بناء تغذية يومية للأرصدة والمعاملات لكل عميل باستخدام Didit: ربط مستمر، وwebhooks، وسجل تغييرات بمؤشر، وإنهاء الموافقة.

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

يأخذك هذا الدليل من الصفر إلى مصدر بيانات يومي لعميل واحد.
يعمل الكود نفسه مع كل عميل: اتصال واحد لكل عميل ولكل بنك.

## ما تحتاج إليه

* مفتاح API يتضمن إذن بيانات البنك، لتطبيق البيئة التجريبية الخاص بك. راجع [دليل البدء السريع](https://docs.didit.me/ar/core-technology/bank-verification/quickstart.md#الخطوة-1-إنشاء-مفتاح-api-بصلاحية-bank-data).
* وجهة webhook تستقبل أحداث `bank.*`. راجع [webhook الخاص بالبنوك](https://docs.didit.me/ar/core-technology/bank-verification/webhooks.md).
* جدول في قاعدة بياناتك لكل معرّف اتصال للعميل، ومؤشر تغذية التغييرات، وتاريخ انتهاء الموافقة.

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

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "segment": "business",
    "data": ["accounts", "balances", "transactions"],
    "history_from": "2026-01-01",
    "consent_days": 180,
    "ownership": { "compare": "none" },
    "end_user": { "reference": "client-7731", "email": "ana@example.com" },
    "redirect_url": "http://localhost:3000/bank/return",
    "vendor_data": "client-7731"
  }'
```

* `access: ongoing` يُبقي الوصول مفتوحاً حتى تنتهي الموافقة. `consent_days` طلبٌ فقط: البنك هو من يحدد التاريخ الفعلي، ويظهر هذا التاريخ على الربط.
* `history_from` يطلب السجل منذ تاريخ محدد، مثلاً بداية السنة. استخدم بدلاً منه `history_days` (من 1 إلى 365) إن فضّلت ذلك، ولا تستخدمهما معاً أبداً. قد يسلّم البنك أقل من ذلك: يُبلغ كل حساب عن `history_coverage` الخاصة به.
* `ownership.compare: none` يتخطى مقارنة صاحب الحساب، فلا حاجة إلى هوية مرجعية. استخدم `business` لمقارنة صاحب الحساب بشركة موثّقة في Didit.
* `end_user.reference` هو معرّفك للعميل. يمكن البحث به، ويتيح لـ Didit التعرّف على العميل نفسه عندما يربط الحسابات نفسها مرة أخرى.
* أرسل العميل إلى [صفحة التحقق المستضافة](https://docs.didit.me/ar/integration/bank-link/hosted-link.md) وأعده إلى منتجك عبر [رابط إعادة التوجيه](https://docs.didit.me/ar/integration/bank-link/return-to-your-site.md).

احفظ `id` الرابط مع العميل.

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

عندما يُكمل العميل العملية، يصل الحدث `bank.link.completed` ومعه `connection_id`.
أكِّد ذلك، فالمتصفح لا يُعتمد عليه أبدًا:

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

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

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

يُرجع المؤشر الفارغ كل المعاملات الحالية بالقيمة `added` مع `reset: true`.
استعرضها صفحة تلو الأخرى، ولا تحفظ المؤشر إلا في النهاية:

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?limit=500" \
  -H "x-api-key: $DIDIT_API_KEY"
```

```python theme={null}
cursor, page_token = stored_cursor or "", None
while True:
    params = {"limit": 500, "page_token": page_token} if page_token else {"cursor": cursor, "limit": 500}
    page = get(f"/v3/bank/connections/{connection_id}/transactions/sync/", params)
    if page["reset"] and not page_token:
        wipe_local_copy(connection_id)       # replace, never append
    apply(page["added"], page["modified"], page["removed"])
    if not page["has_more"]:
        store_cursor(connection_id, page["next_cursor"])
        break
    page_token = page["next_page_token"]
```

* القراءة الأولى لقطة حقيقية: تُرجع كل معاملة كانت مرتبطة بالاتصال عند بدء القراءة، كل واحدة مرة واحدة فقط بالقيمة `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: [تحديث بيانات البنك عند الطلب](https://docs.didit.me/ar/use-cases/refresh-bank-data-on-demand.md).

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

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

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

للموافقة تاريخ انتهاء: `consent.expires_at`.
يرسل Didit الحدث `bank.connection.consent_expiring` قبل الانتهاء بـ 14 يومًا و7 أيام ويومٍ واحد.

استدعِ [`renew_connection`](https://docs.didit.me/ar/standalone-apis/bank-connection-renew) عندما تريد التجديد. تُرجع العملية `409 renewal_not_needed` حتى يتبقى 30 يومًا.
صفحة يُكمل فيها العميل التجديد غير متاحة بعد.

إذا سمح العميل بانتهاء الموافقة، يصبح الاتصال في حالة `renewal_required`، ولكن ما زال بإمكانك قراءة البيانات التي تمت مزامنتها.
التفاصيل موجودة في [تجديد موافقة البنك](https://docs.didit.me/ar/use-cases/renew-bank-consent.md).

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

* يغادر العميل منتجك: استدعِ [`revoke_connection`](https://docs.didit.me/ar/standalone-apis/bank-connection-revoke) لإيقاف القراءة فورًا، أو [`delete_connection`](https://docs.didit.me/ar/standalone-apis/bank-connection-delete) لإيقاف القراءة وحذف البيانات المخزَّنة.
* يتوقف العميل عن المشاركة مع البنك: يصل الحدث `bank.connection.revoked` مع `ended_by`. أوقف تغذية البيانات لذلك الاتصال.

## السعر

تتم فوترة الوصول المستمر لكل اتصال نشط شهريًا.
يشمل السعر جميع حسابات الاتصال، والأرصدة، والمعاملات، وحتى 365 يومًا من السجل حيثما يوفّره البنك، والمزامنات التلقائية، والمزامنات الفورية ضمن حدود البنك، والتجديدات، وwebhook، وجميع عمليات القراءة.
الرابط الذي لا يُكمله أحد مجاني، وكذلك الاتصالات في حالة `renewal_required` أو `paused` أو `revoked`.
راجع [الأسعار](https://docs.didit.me/ar/getting-started/bank-verification-pricing.md#بيانات-البنك-والوصول-المستمر).

## قائمة التحقق

* [ ] اتصال واحد لكل عميل ولكل بنك، يُخزَّن مع المؤشر وتاريخ انتهاء الموافقة.
* [ ] معالج webhook يتسم بـ idempotency، ويعتمد معرّف الحدث مفتاحًا له.
* [ ] `reset: true` يستبدل نسختك ولا يضيف إليها أبدًا شيئًا.
* [ ] معالجة `removed` مع سبب الإزالة.
* [ ] ربط تذكيرات الموافقة بإشعارك الخاص للعميل.
* [ ] `bank.connection.revoked` يوقف تدفق البيانات.
* [ ] تجتاز الخطة في [البيئة التجريبية](https://docs.didit.me/ar/core-technology/bank-verification/sandbox.md#خطة-اختبار-جيدة).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.