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 وحدود البنك الخاصة بجلب البيانات أمران منفصلان: راجع تحديث بيانات البنك عند الطلب.