الانتقال إلى المحتوى الرئيسي
POST
curl
تبدأ نقطة الـ endpoint المسماة Create a Bank Link من Didit تشغيلًا واحدًا لـ Bank Link على خادمك، لربط بنك أو تجديد اتصال، وتُرجع الرابط المستضاف url. كل حقل له قيمة افتراضية، لذا أصغر طلب هو {} مع ما تريد إضافته. احتفظ بالمعرّف id المُعاد مع مستخدمك، وتحقّق من النتيجة بنفسك عبر الحصول على ربط بنكي أو عبر webhook للحدث bank.link.completed. راجع دليل البدء السريع وBank Link.

التفويضات

x-api-key
string
header
مطلوب

مفتاح API الخاص بتطبيقك، ويمكن الحصول عليه من Developers -> API keys في Business Console. يملك المفتاح الأساسي صلاحية وصول كاملة. يمكن تقييد المفتاح المسمّى: بلا صلاحية، أو قراءة، أو كتابة لكل مورد، ويمكن قصره على بعض سير العمل أو على الجلسات المعتمدة، وعلى قائمة من عناوين IP، وعلى تاريخ انتهاء. يعني الرمز 401 أن المفتاح غير صحيح أو ملغى أو منتهي الصلاحية. ويعني الرمز 403 أنه لم يُرسل أي مفتاح، أو أن المفتاح لا يملك صلاحية لهذا المورد أو الإجراء، أو أن الطلب صدر من عنوان خارج قائمة IP الخاصة به. ويعني الرمز 404 على مسار جلسة أن الجلسة خارج سير عمل المفتاح أو حالاته المسموح بها. يتلقى المفتاح الذي لا يملك وصولًا إلى الوسائط عناوين URL للصور والفيديو وملفات PDF بقيمة null، ويتلقى المفتاح الذي لا يملك صلاحية كتابة الجلسات روابط الجلسات والرموز بقيمة null. راجع https://docs.didit.me/console/api-keys.

الترويسات

Idempotency-Key
string

مفتاح اختياري لأمان إعادة المحاولة تختاره لعملية واحدة، بحد أقصى 255 حرفًا (يصلح UUID). الطلب المكرَّر بالمفتاح نفسه والـ endpoint والاستعلام والمحتوى يُجاب بالاستجابة الأولى نفسها، بالحالة والمحتوى نفسيهما، ولا يُنفَّذ ولا يُحتسب مرة ثانية. استخدام المفتاح نفسه مع endpoint أو استعلام أو محتوى مختلف يعيد 409 مع idempotency_key_reused، وبينما الطلب الأول ما زال قيد التنفيذ يعيد 409 مع idempotency_key_in_progress ومعه Retry-After. لا يُخزَّن الطلب الفاشل (أي 4xx أو 5xx)، لذا يمكنك إرساله مرة أخرى بالمفتاح نفسه. المفاتيح تخص تطبيقك، سواء استدعيت بمفتاح API أو بـ token الوصول. راجع إعادة المحاولة وidempotency.

Required string length: 1 - 255

الجسم

application/json

أنشئ رابطاً بنكياً. أصغر طلب هو {} مع ما تريده، ولكل حقل قيمة افتراضية.

mode
enum<string>
افتراضي:connect

connect (الافتراضي) ينشئ اتصالًا جديدًا. renew يحتاج إلى connection_id ويعيد استخدام إعدادات ذلك الاتصال.

الخيارات المتاحة:
connect,
renew
connection_id
string<uuid>

الاتصال المراد تجديده. فقط مع mode: renew.

access
enum<string>
افتراضي:one_time

one_time (الافتراضي) يقرأ البيانات مرة واحدة. ongoing يُبقي الوصول مفتوحًا حتى تنتهي الموافقة أو يوقفها أحد. عند تحديد institution_id، يرد البنك الذي لا يستطيع إبقاء الوصول مفتوحًا بالخطأ 400 ongoing_access_not_available قبل عرض أي شاشة. وبدونه، يعرض منتقي البنوك البنوك التي تستطيع ذلك فقط.

الخيارات المتاحة:
one_time,
ongoing
country
string

اختياري. إن لم ترسله يختار الشخص من بين الدول التي فعّلها تطبيقك. يجب أن تكون دولة تخدمها Bank Link؛ أي دولة أخرى، بما فيها ZZZ، تُرجع 400 invalid_request مع field: country. يبقى طلب بجسم فارغ صالحا.

Pattern: ^[A-Z]{3}$
institution_id
string

بنك اختياري يُحدد مسبقا من list_institutions، فيتجاوز منتقي البنوك.

Maximum string length: 64
segment
enum<string>
افتراضي:any

يصفّي أداة الاختيار، ويحدد للبنك تسجيل الدخول الذي يُفتح عندما يفصل البنك بين تسجيلات الدخول. القيمة الافتراضية any.

الخيارات المتاحة:
personal,
business,
any
data
enum<string>[]

ما الذي تقرؤه. يُضمَّن accounts دائمًا: الاسم والنوع والعملة والمعرّفات، واسم صاحب الحساب حيث يشاركه البنك. الافتراضي ["accounts"].

Maximum array length: 3
الخيارات المتاحة:
accounts,
balances,
transactions
history_days
integer
افتراضي:90

عدد أيام سجل المعاملات المطلوب، من 1 إلى 365، والافتراضي 90. قد يسلّم البنك أقل من ذلك: يبيّن كل حساب ما سلّمه في history_coverage. لا يمكن إرساله مع history_from.

النطاق المطلوب: 1 <= x <= 365
history_from
string<date>

تاريخ بداية السجل المطلوب، بدلاً من history_days. لا يمكن إرساله مع history_days: إرسال الاثنين معاً يُعيد 400 history_window_ambiguous. التاريخ الأقدم من 365 يوماً، أو التاريخ المستقبلي، يُعيد 400 window_not_available.

extended_history
enum<string>
افتراضي:standard

allow_extra_auth يتيح لبنك يطلب تأكيدًا إضافيًا واحدًا أن يفرج عن السجل الأقدم.

الخيارات المتاحة:
standard,
allow_extra_auth

متاح للوصول المستمر فقط. عدد الأيام التي تطلب فيها من البنك إبقاء الوصول مفتوحا، يوم واحد أو أكثر. القيمة الافتراضية: أطول مدة يسمح بها البنك. يعرض الاتصال التاريخ الذي منحه البنك فعلا في consent.expires_at. مع access: one_time يُرجع 400 invalid_request مع field: consent_days.

النطاق المطلوب: 1 <= x <= 32767
ownership
object

مقارنة اختيارية لصاحب الحساب مع شخص أو شركة.

end_user
object

الشخص أو الشركة التي تربط الحساب.

redirect_url
string<uri>

إلى أين ينتقل المتصفح في النهاية، مع link_id وstatus وstate موقّع (للعرض فقط: الـ webhook وget_link هما المرجع الموثوق). في تطبيق البيئة التجريبية، يُسمح بعنوان http عادي يشير إلى localhost أو 127.0.0.1 أو [::1] (بأي منفذ ومسار، دون بيانات اعتماد ولا جزء تجزئة) دون تسجيل مسبق. أي عنوان آخر يُرجع 400 redirect_url_not_registered، إذ إن تسجيل عناوين أخرى غير متاح حاليًا. وبدون redirect_url يُنهي الشخص العملية في صفحة النتيجة الخاصة بـ Didit.

Maximum string length: 2048
allowed_origins
string<uri>[]

مقبول ولا يُستخدم اليوم: مخصص لـ Bank Link المدمج لدى Didit، وهو غير متاح بعد. مصادر HTTPS، بحد أقصى 50.

Maximum array length: 50
language
string

رمز لغة اختياري مثل es أو pt-BR. وإلا فتُستخدم لغة المتصفح.

Maximum string length: 16
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})?$
vendor_data
string

مرجعك الخاص، ويُعاد في الرابط والاتصال.

Maximum string length: 255
expires_in
integer
افتراضي:3600

مدة صلاحية الرابط بالثواني، من 300 إلى 86400. القيمة الافتراضية 3600.

النطاق المطلوب: 300 <= x <= 86400
duplicates
enum<string>
افتراضي:reuse

reuse (الافتراضي) يُكمل الرابط الذي يشير إلى حسابات تشاركها بالفعل بوصفه تجديداً لذلك الاتصال. allow ينشئ اتصالاً ثانياً مستقلاً.

الخيارات المتاحة:
reuse,
allow
allow_one_time_fallback
boolean
افتراضي:false

مع ongoing، يتيح للشخص المتابعة بقراءة لمرة واحدة لدى بنك لا يستطيع إبقاء الوصول مفتوحًا، بعد تأكيد الوصول المخفّض على شاشة البنك نفسها. يوضح العرض ما تكلفه هذه الخطوة. يُستخدم فقط مع access: ongoing: مع الوصول لمرة واحدة يرد بالخطأ 400 invalid_request مع field: allow_one_time_fallback.

accept_reduced_grant
boolean
افتراضي:false

عندما يمنح البنك أو الشخص أقل مما طلبته، يُكمَل الرابط ولا يُحتسب إلا على النطاقات الممنوحة. وفي غير ذلك ينتهي الرابط بالحالة failed مع reduced_grant دون احتساب أي رسوم.

sandbox
object

للتطبيقات التجريبية فقط: يختار عميل Didit Test Bank. يُتجاهل في تطبيق في بيئة الإنتاج.

الاستجابة

تم إنشاء الرابط.

تشغيل واحد لـ Bank Link لشخص واحد: ربط بنك، أو تجديد ربط. أكِّد الرابط بنفسك باستخدام get_link، ولا تثق أبداً بمعرّف يرسله المتصفح.

id
string<uuid>
مطلوب

معرّف الرابط.

mode
enum<string>
مطلوب
الخيارات المتاحة:
connect,
renew
access
enum<string>
مطلوب
الخيارات المتاحة:
one_time,
ongoing
status
enum<string>
مطلوب

حالة الرابط. الحالات completed وcancelled وexpired وfailed نهائية.

الخيارات المتاحة:
created,
opened,
connecting,
completed,
cancelled,
expired,
failed
url
string<uri> | null
مطلوب

صفحة التحقق المستضافة التي يُوجَّه إليها الشخص. تُعاد فقط عند إنشاء الرابط؛ وتكون null في القراءات اللاحقة لأن الرمز لا يُخزَّن.

client_token
string | null
مطلوب

token الخاص بـ Bank Link المضمّن في Didit، وهو غير متاح بعد: افتح url حالياً. يُعاد عند إنشاء الرابط فقط، وتكون القيمة null في القراءات اللاحقة. له غرض واحد وصلاحية قصيرة، ولا يحمل أي بيانات شخصية. لا تسجّله في السجلات أبداً.

expires_at
string<date-time>
مطلوب

متى يتوقف الرابط غير المستخدَم عن العمل.

connection_id
string<uuid> | null
مطلوب

الاتصال الذي أنشأه هذا الرابط أو جدّده، بمجرد أن تصبح status بقيمة completed.

check_id
string<uuid> | null
مطلوب

نتيجة الملكية لهذا الرابط، عندما يطلب ownership.compare بقيمة غير none.

reused
boolean
مطلوب

true عندما يكتمل الرابط بوصفه تجديداً لاتصال قائم، لأن الشخص يشارك بالفعل هذه الحسابات نفسها بالضبط (duplicates: reuse). لا تُفرض أي رسوم مرتين.

error
object | null
مطلوب

سبب فشل الرابط، عندما تكون status هي failed. وإلا فالقيمة null.

quote
object
مطلوب

سعر الرابط، ويُثبَّت عند إنشائه. يُحتسب الرسم وفق عرض السعر. لا تُحتسب أي رسوم عند عمليات القراءة.

vendor_data
string | null
مطلوب

مرجعك من الطلب.

آخر تعديل في ٢٢ نوفمبر ٢٠٢٦