> ## 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 البنكي: حسابات بمعرّفات ثابتة، وأرصدة مصنّفة، ومعاملات مُرحّلة ومعلّقة، وسجل تغييرات بمؤشر دائم.

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

## الحسابات

`GET /v3/bank/connections/{id}/accounts/` يسرد حسابات الاتصال، و`GET /v3/bank/accounts/{account_id}/` يعيد حسابًا واحدًا.

| الحقل | المعنى |
| - | - |
| `id` | يرتبط بالاتصال ولا يتغير طوال وجوده، بما في ذلك عمليات التجديد. |
| `account_ref` | يحدد الحساب البنكي نفسه عبر الاتصالات ضمن التطبيق والبيئة الواحدة. وهو تجزئة مفتاحية لمعرّفات البنك نفسه، ويكون `null` عندما لا يقدم البنك معرّفًا موثوقًا. |
| `type`, `usage` | `current` أو `savings` أو `card` أو `loan` أو `investment` أو `other`، و`personal` أو `business` أو `unknown`. |
| `identifiers` | رقم IBAN وBIC والمعرّفات الأخرى. تحصل عليها كاملة الجهات المستدعية من جانب الخادم التي تملك إذن بيانات البنك. |
| `holders[]` | كل صاحب حساب مع `name` و`role`، وهو `holder` أو `joint_holder` أو `representative` أو `unknown`. |
| `sync.last_synced_at` | وقت آخر جلب فيه Didit البيانات من البنك، وليس وقت آخر قراءة منك لها. |
| `history_coverage` | ما سلّمه البنك من السجل الذي طلبته: `requested_from` و`oldest_booking_date` و`covered_ranges` و`missing_ranges`، وحالة `status` وهي `complete` أو `partial` أو `empty` أو `unavailable` أو `unknown`. |

استخدم `account_ref` للتعرف على حساب بنكي عندما يعيد الشخص ربطه، واستخدم `id` لكل ما يتعلق بالاتصال الواحد.

## الأرصدة

تُعيد `GET /v3/bank/accounts/{account_id}/balances/` الأرصدة مُصنَّفة حسب النوع مع تواريخ المرجع الخاصة بها.

```json theme={null}
{
  "account_id": "a71f0c2e-...",
  "balances": [
    { "type": "booked", "amount": "18250.34", "currency": "EUR", "reference_date": "2026-11-20" },
    { "type": "available", "amount": "17990.34", "currency": "EUR", "reference_date": "2026-11-21" }
  ],
  "last_synced_at": "2026-11-21T12:04:40Z"
}
```

القيمة في `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`.

```json theme={null}
{
  "id": "8f2b...",
  "status": "booked",
  "booking_date": "2026-11-19",
  "value_date": "2026-11-20",
  "amount": "-1210.00",
  "currency": "EUR",
  "direction": "debit",
  "description": "RECIBO SEGURIDAD SOCIAL",
  "counterparty": { "name": "TESORERIA GENERAL SEG SOCIAL", "iban": "ES7620770024003102575766" },
  "remittance": { "unstructured": ["RECIBO SEGURIDAD SOCIAL 10/2026"], "reference": "0028123456789" },
  "bank_transaction_code": "PMNT-RDDT-ESDD",
  "bank_reference": "2026111900012345",
  "identity_quality": "bank_reference",
  "balance_after": "18250.34",
  "category": "taxes_and_social_security"
}
```

* **`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` في [البيئة التجريبية](https://docs.didit.me/ar/core-technology/bank-verification/sandbox.md) لاختبار شيفرتك مع بنك يرسل بيانات قليلة.

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

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

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

`GET /v3/bank/connections/{id}/transactions/sync/` يُرجع ما تغيّر في جميع حسابات الاتصال منذ `cursor`.

```json theme={null}
{
  "added": [ { "id": "...", "status": "booked", "amount": "-35.00" } ],
  "modified": [],
  "removed": [ { "id": "...", "reason": "pending_booked" } ],
  "has_more": false,
  "next_cursor": "...",
  "reset": false
}
```

* إذا كان المؤشر فارغًا، يُرجع كل المعاملات الحالية كعناصر `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`.

الخطوات التفصيلية موجودة في [تغذية بنكية مستمرة للمحاسبة](https://docs.didit.me/ar/use-cases/bank-data-for-accounting.md).

## الرؤوس

تُعيد كلتا عمليتي قراءة المعاملات الرؤوس `X-RateLimit-*` (600 قراءة و300 كتابة في الدقيقة لكل تطبيق، ويُرجع الطلب 429 مع `Retry-After` عند تجاوز ذلك) و`X-Bank-Last-Synced-At`.
حدود API وحدود البنك الخاصة بجلب البيانات أمران منفصلان: راجع [تحديث بيانات البنك عند الطلب](https://docs.didit.me/ar/use-cases/refresh-bank-data-on-demand.md).


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