مستندات وب سرویس‌های استعلامی زیبال

مقدمه

به راهنمای وب سرویس‌های زیبال خوش آمدید. این مستندات جهت آسانی استفاده شما از سرویس‌های زیبال جمع آوری شده‌اند. در صورت بروز هر گونه سوال با تیم فنی زیبال تماس بگیرید. وظیفه همکاران ما پاسخ به پیام‌های شما در اسرع وقت می‌باشد.

لطفا قبل از پیاده‌سازی به نکات زیر توجه نمایید:

تمامی درخواست‌های شما از طریق بخش توسعه‌دهندگان – فراخوانی‌ها قابل مشاهده هستند.

API‌ های زیبال RESTful می‌باشند و درخواست‌ها و پاسخ‌ها به صورت JSON رد و بدل می‌شوند.

Status Code تمامی درخواست‌های موفق،200 و تمامی درخواست‌های نامعتبر 400 و خطاهای داخلی سرور زیبال 500 می‌باشد که در این صورت شما می‌توانید با توجه به message و result و بررسی پارامترهای ارسالی، علت بروز خطا را دریابید.

زیبال تنها به درخواست‌هایی که از طرف IP های اعلامی شما ارسال شوند پاسخ خواهد داد.

در صورت دریافت هر گونه خطا از جانب زیبال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط زیبال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!

تیم فنی زیبال از طریق بخش پشتیبانی سایت، چت آنلاین و ایمیل info@zibal.ir به سوالات شما در سریعترین زمان ممکن پاسخ خواهد داد.

مستندات وب سرویس‌ها

احراز هویت

زیبال از طریق هدر Authorization جهت احراز هویت درخواست‌ها استفاده می‌کند.

به این ترتیب تمامی درخواست‌های شما بایستی حاوی هدر به شکل زیر باشد: Authorization: Bearer {{ACCESS TOKEN}}

شما میتوانید با مراجعه به حساب کاربری/توسعه دهندگان/گزینه API Token ها، ACCESS TOKEN مربوط به خود را ایجاد نمایید.

هر پنل کاربری می‌تواند بینهایت ACCESS TOKEN از زیبال با دسترسی به API های متفاوت دریافت کند.

امکان محدودسازی برای IP های دلخواه و همچنین ایجاد محدودیت در سطح دسترسی ACCESS TOKEN ها با مراجعه به پنل کاربری امکان پذیر می‌باشد.

وب سرویس‌ها

استعلام شماره شبا

از این پایانه می‌توانید جهت استعلام نام دارنده شماره شبای ارسالی استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/ibanInquiry

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
IBAN	بله	string	شماره شبا
separated	خیر	boolean	تفکیک نام و نام خانوادگی

نمونه JSON ارسالی شما برای این پایانه در صورت false بودن پارامتر separated

{
    "IBAN": "IR120620000000246388553648"
}

نمونه JSON ارسالی شما برای این پایانه در صورت true بودن پارامتر separated

{
    "IBAN": "IR120620000000246388553648",
    "separated":true,
}

استعلام اطلاعات هویتی

‌از این پایانه می‌توانید برای استعلام اطلاعات هویتی فرد با توجه به کد‌ملی و تاریخ تولد وی استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/nationalIdentityInquiry

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
nationalCode	بله	رشته (String)	کد‌ملی
birthDate	بله	رشته (String)	تاریخ تولد
genderInquiry	خیر	boolean	استعلام جنسیت

بدنه پاسخ

نمونه JSON ارسالی شما برای این پایانه

{
    "nationalCode": "00XXX61745",
    "birthDate": "1374/11/23"
}

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	اطلاعات هویتی فرد
gender	عدد (int)	جنسیت

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "matched": true,
        "firstName": "امير",
        "lastName": "صادقی بارانی",
        "fatherName": "حميد",
        "alive": true
    }
}

تبدیل شماره کارت به شبا

‌از این پایانه می‌توانید برای تبدیل شماره کارت به شماره شبا استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/cardToIban

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
cardNumber	بله	رشته (String)	شماره کارت

نمونه JSON ارسالی شما با ورودی trackId برای این پایانه

{
    "trackId": "68710287",
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	اطلاعات صاحب شماره کارت ارسالی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "name": "نام صاحب حساب",
        "IBAN": "IRXXXXXXXXXXX",
        "bankName": "بانک آینده",
    }
}

صاحب حساب

این شیء اطلاعات صاحب حساب را نشان میدهد.

پارامتر	نوع	توضیحات
name	رشته (String)	نام صاحب حساب
IBAN	رشته (String)	شماره شبا
bankName	رشته (String)	نام بانک
bankAccount	رشته (String)	شماره حساب

استعلام نام صاحب کارت

‌از این پایانه می‌توانید برای استعلام نام صاحب کارت استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/cardInquiry

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
cardNumber	بله	رشته (String)	شماره کارت

نمونه JSON ارسالی شما با ورودی trackId برای این پایانه

{
    "cardNumber": "6362XXXXXXX11",
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نام صاحب کارت

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "name": "نام صاحب کارت"
    }
}

استعلام کد پستی

‌از این پایانه می‌توانید برای استعلام کد پستی‌های خود استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/postalCodeInquiry

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
postalCode	بله	رشته (String)	کد پستی مورد نظر

نمونه JSON ارسالی شما برای این پایانه

{
    "postalCode": "123456789",
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	آدرس	اطلاعات آدرس کد پستی ارسالی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "address": {
            "province": "تهران",
            "town": "تهران",
            "district": "امیرآباد",
            "street": "خیابان کارگر شمالی",
            "street2": "خیابان شهید محمد فرشی مقدم [16]",
            "number": 0,
            "floor": "همکف",
            "sideFloor": "113 شرقی",
            "buildingName": "مرکز رشد پارک علم و فناوری",
            "description": "ساختمان شماره 1"
        }
    }
}

ocr کارت ملی

‌از این پایانه می‌توانید برای دریافت اطلاعات کارت ملی از روی تصویر کارت ملی استفاده نمایید.

در درخواست ارسال خود ضروری است تا حداقل تصویر یک سمت کارت ملی یا دو سمت آنرا ارسال نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/nationalCardOcr

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
nationalCardBack	بله (یا ارسال عکس پشت کارت ملی)	رشته (String)	عکس پشت کارت ملی
nationalCardFront	بله (یا ارسال عکس جلو کارت ملی)	رشته (String)	عکس جلو کارت ملی

نمونه cURL ارسالی شما برای این پایانه

{
    curl --location 'http://localhost:8000/v1/facility/nationalCardOcr' \
    --form 'nationalCardBack=@"/path/to/file"' \
    --form 'nationalCardFront=@"/Users/mohammad/Documents/fatemi.jpg"'
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	مشخصات صاحب کارت ملی

نمونه JSON پاسخ زیبال برای این پایانه و جلو کارت ملی

{
    "result": 1,
    "message": "موفق",
    "data": {
        "result": true,
        "firstName": "عين الله",
        "lastName": "متقی زاده",
        "fatherName": "عبداله",
        "nationalCode": "0370362063",
        "birthDate": "1369/07/11",
        "expirationDate": "1353/07/15",
        "facePhoto": "عکس صاحب کارت ملی به فرمت base64",
        "city": "قم",
        "province": "قم"
    },
    "meta": null,
    "error": null
}

نمونه JSON پاسخ زیبال برای این پایانه و پشت کارت ملی

{
    "result": 1,
    "message": "موفق",
    "data": {
        "result": true,
        "serialCard": "3g35188796",
        "nationalCode": "0370362063"
    },
    "meta": null,
    "error": null,
}

عکس کارت ملی

از این پایانه می‌توانید جهت دريافت عکس کارت ملي استفاده نمایید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/nationalCardImage

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
nationalCode	بله	رشته (String)	کد ملی مورد نظر
birthDate	بله	رشته (String)	تاریخ تولد مورد نظر

نمونه JSON ارسالی شما برای این پایانه

{
    "nationalCode": "00XXX61745",
    "birthDate": "1374/11/23"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	عکس کارت ملی در فرمت base64

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "image": "image_in_base64_format"
}

تطابق کدملی و شماره‌ موبایل

‌با استفاده از این وب‌سرویس می‌توان مالکیت سیم‌کارت و کد‌ملی را بررسی کرد.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/shahkarInquiry

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
mobile	بله	رشته (String)	شماره موبایل
nationalCode	بله	رشته (String)	کد ملی

نمونه JSON ارسالی شما برای این پایانه

{
    "mobile":"092XXX7725",
    "nationalCode": "1285XXX561"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نشان دهنده تطابق و عدم تطابق شماره موبایل و کدملی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "message": "موفق",
    "data": {
        "matched": true
    },
    "result": 1
}

تطابق شماره کارت و نام صاحب کارت

با استفاده از این وب سرویس می‌توانید از تطابق شماره کارت و نام صاحب شبا مطلع شوید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/checkCardWithName

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
cardNumber	بله	رشته (String)	شماره کارت
name	بله	رشته (String)	نام و نام خانوادگی

نمونه JSON ارسالی شما برای این پایانه

{
    "mobile":"092XXX7725",
    "nationalCode": "1285XXX561"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نشان دهنده تطابق و عدم تطابق شماره کارت و نام صاحب شبا

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "matched": true
    }
}

تبدیل شماره کارت به شماره حساب

از این وب‌سرویس جهت تبدیل شماره کارت به شماره حساب می‌توانید استفاده کنید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/cardToAccount

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
cardNumber	بله	رشته (String)	شماره کارت

نمونه JSON ارسالی شما برای این پایانه

{
    "cardNumber": "636XXX1100119421"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	اطلاعات حساب شماره کارت ارسالی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "name": "جعفر صادق رستمي",
        "bankAccount": "4600000XXX660",
        "bankName": "مسکن"
    }
}

تبدیل شماره حساب به شماره شبا

از این وب‌سرویس جهت تبدیل شماره حساب به شماره شبا می‌توانید استفاده کنید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/accountToIban

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
bankAccount	بله	رشته (String)	شماره حساب
bankCode	بله	رشته (String)	کد مخصوص هر بانک

نمونه JSON ارسالی شما برای این پایانه

{
    "bankAccount": "4600000XXX660",
    "bankCode": "062"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	شماره شبا مربوط به شماره حساب ارسالی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "IBAN": "IR700620000000XXX295898001"
    }
}

تطابق کد‌ملی و شماره کارت

با استفاده از این وب سرویس می‌توانید از تطابق کد‌ملی و شماره کارت مطلع شوید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/checkCardWithNationalCode

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
nationalCode	بله	رشته (String)	کد‌ملی
birthDate	بله	رشته (String)	تاریخ تولد
cardNumber	بله	رشته (String)	شماره کارت

نمونه JSON ارسالی شما برای این پایانه

{
    "nationalCode": "1285XXX561",
    "birthDate": "1377/07/19",
    "cardNumber":"6362XXXXXXX11"
}

لطفا دقت کنید که این سرویس تطابق کدملی و کارت را بررسی میکند و ارسال تاریخ تولد به منزله انجام تطبیق تاریخ تولد با کدملی نمی باشد و ممکن است این سرویس با تاریخ تولد اشتباه هم پاسخ را به درستی برگرداند.

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نشان دهنده تطابق و عدم تطابق کد‌ملی و شماره کارت

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "matched": true
    }
}

تطابق کد‌ملی و شماره شبا

با استفاده از این وب سرویس می‌توانید از تطابق کد‌ملی و شماره شبا مطلع شوید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/checkIbanWithNationalCode

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
nationalCode	بله	رشته (String)	کد‌ملی
birthDate	بله	رشته (String)	تاریخ تولد
IBAN	بله	رشته (String)	شماره شبا

لطفا دقت کنید که این سرویس تطابق کدملی و شبا را بررسی میکند و ارسال تاریخ تولد به منزله انجام تطبیق تاریخ تولد با کدملی نمی باشد و ممکن است این سرویس با تاریخ تولد اشتباه هم پاسخ را به درستی برگرداند.

نمونه JSON ارسالی شما برای این پایانه

{
    "nationalCode": "1285XXX561",
    "birthDate": "1377/07/19",
    "IBAN":"IR70XXX0000000303795898001"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نشان دهنده تطابق و عدم تطابق کد‌ملی و شماره شبا

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "matched": true
    }
}

تبدیل نام فارسی به انگلیسی

از این وب‌سرویس جهت تبدیل تبدیل نام فارسی به انگلیسی می‌توانید استفاده کنید.

اطلاعات درخواست

POST https://api.zibal.ir/v1/facility/persianToFinglish

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات
persianText	بله	رشته (String)	نام فارسی

نمونه JSON ارسالی شما برای این پایانه

{
    "persianText": "محمد نادری"
}

بدنه پاسخ

پارامتر	نوع	توضیحات
message	رشته (String)	پیغام حاوی نتیجه درخواست
result	عدد (int)	نتیجه درخواست
data	object	نام تبدیل شده به انگلیسی

نمونه JSON پاسخ زیبال برای این پایانه

{
    "result": 1,
    "message": "موفق",
    "data": {
        "finglishText": "mohammad naderi"
    }
}

اشیا و مدل‌ها

آدرس

این شیء آدرس را نشان میدهد.

پارامتر	نوع	توضیحات
province	رشته (String)	استان
town	رشته (String)	شهر
district	رشته (String)	منطقه
street	رشته (String)	خیابان اصلی
street2	رشته (String)	خیابان فرعی
number	رشته (String)	پلاک
floor	رشته (String)	طبقه
sideFloor	رشته (String)	واحد
buildingName	رشته (String)	نام ساختمان
description	رشته (String)	توضیحات

مشخصات صاحب کارت ملی

این شیءمشخصات صاحب کارت ملی را نشان میدهد.

پارامتر	نوع	توضیحات
firstName	رشته (String)	نام صاحب کارت ملی
lastName	رشته (String)	نام خانوادگی صاحب کارت ملی
fatherName	رشته (String)	نام پدر صاحب کارت ملی
nationalCode	رشته (String)	کد‌ملی
birthDate	رشته (String)	تاریخ تولد صاحب کارت ملی
expirationDate	رشته (String)	تاریخ انقضاء کارت ملی
facePhoto	رشته (String)	تصویر صاحب کارت ملی
city	رشته (String)	شهر
province	رشته (String)	استان
serialCard	رشته (String)	سریال کارت ملی

لیست کد بانک‌ها

این شیء کد‌های مخصوص به هر بانک را نشان میدهد.

نام بانک	کد مخصوص بانک
صنعت و معدن	011
ملت	012
رفاه	013
مسکن	014
سپه	015
کشاورزی	016
ملی	017
تجارت	018
صادرات	019
توسعه صادرات	020
پست بانک	021
توسعه تعاون	022
قوامین	052
کارآفرین	053
پارسیان	054
اقتصاد نوین	055
سامان	056
پاسارگاد	057
سرمایه	058
سینا	059
قرض الحسنه مهر	060
شهر	061
آینده	062
انصار	063
حکمت ایرانیان	065
دی	066
ایران زمین	069
رسالت	070
موسسه اعتباری کوثر	073
خاورمیانه	078
موسسه اعتباری نور	080

جدول Result

Status Code تمامی درخواست‌های موفق، 200 و تمامی درخواست‌های ناموفق 400,403,500 می‌باشد.

result	توضیحات
1	موفق
2	API Key به درستی ارسال نشده است.
3	API Key صحیح نیست.
4	اجازه دسترسی به این سرویس صادر نشده‌است.
5	callbackUrl نامعتبر است.
6	مقدار ورودی نامعتبر است
7	IP ارسال‌کننده درخواست نامعتبر می‌باشد.
8	API Key غیرفعال است.
9	حداقل مبلغ باید 1000 ریال باشد.
21	شماره شبای وارد شده معتبر نیست. (26 کاراکتر و شروع با IR و بدون خط تیره (-) و فاصله)
29	موجودی کیف‌پول کارمزد برای این عملیات کافی نیست
44	با ورودی های داده شده شبای مورد نظر یافت نشد
45	سرویس دهنده ها برای استعلام در دسترس نیستند