التحقق من الآيبان

تتحقق من رقم الحساب المصرفي الدولي (IBAN) وتُرجع صيغه ومعلومات الدولة المصرفية.

نظرة عامة#

تفحص lookup/iban الآيبان الممرَّر في المعامل iban. تتأكد من رمز الدولة والطول وأرقام التحقق، ثم تُرجع isValid والآيبان بثلاث صيغ داخل formats (machine وhuman وobfuscated) وكائن country يضم الاسم ورموز ISO وIANA والعملة والبنك المركزي وهل الدولة في الاتحاد الأوروبي أو منطقة SEPA وطول الآيبان المتوقع وحالة SWIFT.

متى تستخدمه#

• لالتقاط الأخطاء الإملائية في نماذج السحب أو الاسترداد قبل فشل التحويل.
• للتأكد من توافق دولة البنك مع الدولة التي صرّح بها العميل.
• لتخزين آيبان منسّق ونظيف، أو عرض صيغة obfuscated في واجهتك بدل الرقم الكامل.

قراءة النتيجة#

• isValid هو الحكم. القيمة false تعني طولًا خاطئًا للدولة أو دولة غير معروفة أو فشل المجموع الاختباري، فاطلب من المستخدم إعادة الإدخال.
• formats.machine هي السلسلة المدمجة لقاعدة بياناتك وواجهات المصارف، وformats.human تقسّمها إلى مجموعات من أربعة للعرض.
• country.isSEPA وcountry.isEU تساعدانك في تحديد قنوات التحويل والرسوم المنطبقة.
• يحدد الحقل bank المصرف من رمز المصرف الوطني داخل الآيبان: code وname وnameAr وswift (مع mergedInto إن كان المصرف قد اندمج لاحقًا في آخر، مثل سامبا في SNB). ويشمل السعودية والإمارات والكويت والبحرين وقطر والأردن، وقيمته null لبقية الدول وللرمز غير المعروف وللآيبان غير الصالح.
• التحقق يعني ثلاثة أمور: سلامة الصيغة والطول للدولة، ونجاح المجموع الاختباري، والتعرف على رمز المصرف (حيث لدينا جدول). ولا يمكنه تأكيد وجود الحساب أو ملكيته للشخص؛ فلا نظام عام يستطيع ذلك لأنه يتطلب خدمة التحقق من الحسابات لدى المصرف نفسه. فأبقِ إجراءات التحقق المعتادة قبل الصرف.

ملاحظات#

• تُحتسب طلبًا واحدًا. وضع الاختبار يُرجع بيانات وهمية مجانًا دون أحداث.
• ليست ضمن الباقة القياسية؛ متاحة في التجربة والمميّزة والدفع حسب الاستخدام. وبدون صلاحية يصلك الخطأ 117 (feature_not_available).
• يمكن لـالقواعد المخصصة في مجموعة الآيبان اختبار الآيبان ودولته وصلاحيته وتعليمه كصالح أو غير صالح، وتُسرد النتيجة في custom_rules_applied.
• يُطلَق حدث invalid_iban للآيبان غير الصالح ويُرسل إلى الويب هوك.
• القيمة المفقودة أو غير الصحيحة تُرجع الخطأ 122 (invalid_iban) مع HTTP 200.

الطلب#

• صادِق بمعامل key أو بترويسة Authorization: Bearer.
• تُحتسب طلباً واحداً.
• متاحة في: تجربة مجانية المميّزة الدفع حسب الاستخدام

المعاملات#

تقبل كل خدمة أيضاً format, lang, mode, userID, callback. راجع الخيارات.

أمثلة برمجية#

curl -G "https://gurdx.cretip.com/api/lookup/iban" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "iban=SA0380000000608010167519"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/iban?'.http_build_query(['key' => 'YOUR_API_KEY', 'iban' => 'SA0380000000608010167519']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","iban":"SA0380000000608010167519"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/iban?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/lookup/iban", params={"key": "YOUR_API_KEY", "iban": "SA0380000000608010167519"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

الاستجابة#

نجاح#

{
    "data": {
        "isValid": true,
        "formats": {
            "machine": "BE71096123456769",
            "human": "BE71 0961 2345 6769",
            "obfuscated": "BE** **** **** 6769"
        },
        "country": {
            "name": "Belgium",
            "IANA": "be",
            "ISO3166": "BE",
            "currency": "EUR",
            "centralBank": {
                "url": "http://www.nbb.be/",
                "name": "National Bank of Belgium"
            },
            "membership": "eu_member",
            "isEU": true,
            "length": "16",
            "isSEPA": true,
            "swiftOfficial": true
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        },
        "bank": null
    },
    "status": "success",
    "executionTime": 1
}

خطأ#

تُسلَّم الأخطاء بحالة HTTP 200 — افحص دائماً حقل status.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

حقول الاستجابة#