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

آخرین به‌روزرسانی : ۲۴ اردیبهشت ۱۴۰۲

مقدمه

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

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

تمامی درخواست‌های شما از طریق بخش توسعه‌دهندگان - فراخوانی‌ها قابل مشاهده هستند.
API‌ های زیبال RESTful می‌باشند و درخواست‌ها و پاسخ‌ها به صورت JSON رد و بدل می‌شوند.
Status Code تمامی درخواست‌های موفق،200و تمامی درخواست‌های نامعتبر400و خطاهای داخلی سرور زیبال500می‌باشد که در این صورت شما می‌توانید با توجه بهmessageوresultو بررسی پارامترهای ارسالی، علت بروز خطا را دریابید.
زیبال تنها به درخواست‌هایی که از طرف IP های اعلامی شما ارسال شوند پاسخ خواهد داد.
در صورت دریافت هر گونه خطا از جانب زیبال، پس از بررسی مقادیر ارسالی خود، این خطا را به همراه مقادیر ارسالی و مقادیر پاسخ‌ دریافتی را برای ما ارسال کنید. از امکان بروز خطا توسط زیبال باخبریم و به سرعت در راستای حل مشکل قدم برخواهیم داشت!
تیم فنی زیبال از طریق بخش پشتیبانی سایت، چت آنلاین و ایمیلاین آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید به سوالات شما در سریعترین زمان ممکن پاسخ خواهد داد.

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

احراز هویت

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

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

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

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

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

وب سرویس‌ها

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

IBAN	بله	string	شماره شبا

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

nationalCode	بله	رشته (String)	کد‌ملی
birthDate	بله	رشته (String)	تاریخ تولد

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

cardNumber	بله	رشته (String)	شماره کارت

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

صاحب حساب

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

پارامتر	نوع	توضیحات

name	String	نام صاحب حساب
IBAN	String	شماره شبا
bankName	String	نام بانک
bankAccount	String	شماره حساب

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

cardNumber	بله	رشته (String)	شماره کارت

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

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

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

ocr کارت ملی

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

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

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

mobile	بله	رشته (String)	شماره موبایل
nationalCode	بله	رشته (String)	کد ملی

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

IBAN	بله	رشته (String)	شماره شبا
name	بله	رشته (String)	نام و نام خانوادگی

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

بدنه پاسخ

پارامتر	نوع	توضیحات

message	string	پیغام حاوی نتیجه درخواست
result	int	نتیجه درخواست(جدول Resultها)
data		نشان دهنده تطابق و عدم تطابق شماره شبا و نام صاحب شبا

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

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

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

cardNumber	بله	رشته (String)	شماره کارت

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

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

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

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

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

استعلام اطلاعات شرکت

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

nationalId	بله	رشته (String)	شناسه ملی شرکت

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

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

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

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

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

بدنه درخواست

پارامتر	ضروری	نوع	توضیحات

persianText	بله	رشته (String)	نام فارسی

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

بدنه پاسخ

پارامتر	نوع	توضیحات

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

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

اشیا و مدل‌ها

آدرس

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

پارامتر	نوع	توضیحات

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

اطلاعات شرکت

این شیءاطلاعات شرکت را نشان میدهد.

پارامتر	نوع	توضیحات

nationalId	String	شناسه ملی شرکت
companyTitle	String	نام شرکت
companyRegistrationId	String	شناسه ثبت شرکت
establishmentDate	String	تاریخ ثبت
address	String	آدرس
postalCode	String	کد‌پستی
companyType	String	نوع شرکت
status	String	وضعیت شرکت
extraDescription	String	توضیحات
companyRelatedPeople	String	افراد مرتبط با شرکت
firstName	String	نام
lastName	String	نام‌خانوادگی
nationalCode	String	کد‌ملی
nationality	String	ملیت
personType	String	حقیقی/حقوقی
officePosition	String	سمت

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

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

پارامتر	نوع	توضیحات

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

جدول 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	سرویس دهنده ها برای استعلام در دسترس نیستند

منبع : https://zibal.ir