API و وب سرویس استعلام چک صیادی
مشخصات ثبتشدهٔ یک برگ چک را با شناسهٔ شانزده‌رقمی صیاد برمی‌گرداند تا پیش از پذیرفتن چک، با آنچه روی برگه نوشته شده مقایسه شود.
این سرویس چه می‌کند
فروشندهٔ لوازم خانگی که چک اقساطی میگیرد، چند دقیقه بعد از رفتن مشتری فقط یک برگ کاغذ دارد. اگر شناسهٔ صیاد را همان لحظه به این سرویس بدهد، نام صادرکننده، شبای حساب و تاریخ صدور را از پاسخ می‌خواند و با برگه تطبیق میدهد. ناهماهنگی همان‌جا دیده میشود، نه موقع وصول.
ورودی یک فیلد است: sayadId، شانزده رقم. ارقام فارسی، فاصله و خط تیره پیش از ارسال پاک می‌شوند، پس لازم نیست سمت شما تمیزکاری شود. هر طولی غیر از شانزده رقم همان‌جا invalid_input میگیرد و هزینهای ندارد.
پیش از فراخوان چه چیزی را یکدست کنیم
شناسه را از خود برگه یا بارکد بخوانید و سریال چک را جایش نگذارید. روی برگه چند عدد چاپ شده و منابع آموزشی هم دربارهٔ جای دقیق شناسه یکدست نمی‌نویسند؛ پس در رابط کاربری کنار کادر ورودی یک تصویر نمونه بگذارید. کد ملی صادرکننده لازم نیست. اگر مشتری قدیمی شما هنوز nationalCode می‌فرستد، فراخوان خطا نمی‌گیرد و آن فیلد نادیده گرفته میشود.
در پاسخ چه میآید
data همان پاسخ سرویس مرجع است، بدون دست‌کاری. در نمونهٔ مستند، این کلیدها هستند: name، iban، sayad_id، serial_no، series_no، check_type، issue_date، branch_code، expiration_date و returned_cheques.
دو حالت لبه را از اول در کد پیش‌بینی کنید. expiration_date در نمونه null است، پس خالی‌بودنش خطا نیست. returned_cheques در نمونه رشتهٔ خالی است و مستند معنای مقدارهای دیگرش را نمی‌گوید؛ تصمیم خودکار پذیرش یا رد را به آن گره نزنید.
آنچه این سرویس نمی‌کند
این سرویس پیش‌بینی نمی‌کند که چک در سررسید پاس شود. موجودی حساب در پاسخ نیست و درست‌بودن مشخصات چک، تعهدی برای پرداخت نمی‌سازد.
رنگ اعتباری صادرکننده را هم نمیدهد: در نمونهٔ پاسخ چنین فیلدی نیست. ذی‌نفع فعلی چک و مسیر انتقال‌ها هم در این پاسخ نیامده؛ برای مسیر انتقال، سرویس زنجیرهٔ انتقال جداست و کد ملی صادرکننده می‌خواهد.
هزینه کی کسر میشود
شناسهٔ معتبری که چکی برایش پیدا نشود، پاسخ ok:false با کد not_found و وضعیت ۲۰۰ میگیرد و هزینه دارد، چون پرسش واقعاً از سرویس مرجع شده است. ورودی نامعتبر، موجودی ناکافی، خطای گذرای مرجع (provider_failed_retryable) و در دسترس‌نبودن مرجع رایگاناند. عبور از سقف نرخ هم 429 با Retry-After میدهد و هزینه ندارد.
کجا به کار میآید
- فروشگاه اقساطی لوازم خانگیصندوقدار پیش از تحویل یخچال، شناسهٔ چک مشتری را وارد می‌کند و نام صادرکننده و شبا را با کارت ملی و حساب اعلامی مشتری مقایسه می‌کند. اگر نام یا شبا نخواند، کالا تحویل نمیشود.
- دفتر املاک و چک بیعانهمشاور املاک هنگام گرفتن چک بیعانه، مشخصات ثبتشدهٔ چک را کنار قرارداد پیوست می‌کند. تاریخ صدور و شمارهٔ شبا در پرونده می‌ماند و در اختلاف‌های بعدی مرجع مشترک دو طرف است.
- شرکت لیزینگ و چک ضمانتکارشناس پرونده چک‌های ضمانت را یک‌جا و دسته‌ای از روی بارکد می‌خواند، شناسه‌ها را می‌فرستد و فقط پرونده‌هایی را دستی بررسی می‌کند که نام یا شبای پاسخ با فرم متقاضی نمی‌خواند.
ورودی و خروجی
ورودی
sayadIdstringشناسهٔ صیادشانزده رقم.خروجی
branch_codestring56XXX48check_typestringBANSexpiration_datenullibanstringIR02XXX00XXXXX0049XXXXX001issue_datestring1370/1/1namestringنام صادرکننده چکreturned_chequesstringsayad_idstring12XXXXXXXXX000000serial_nostring95XXX1series_nostring4XXX4قیمت و شرط پرداخت
قیمت هر فراخوان API استعلام چک صیادی ۱۰٬۴۰۰ تومان است.
| تعداد استعلام در ماه | قیمت هر استعلام |
|---|---|
| همهٔ فراخوان‌ها | ۱۰٬۴۰۰ تومان |
آخرین تغییر قیمت:
مبلغ پیش از تماس با سرویس مرجع از موجودی پنل قفل میشود و اگر پاسخی نیاید، آزاد میشود. ورودی نامعتبر، در دسترس نبودن سرویس مرجع و عبور از سقف نرخ هزینهای ندارند. «رکوردی یافت نشد» یک پاسخ معتبر است و هزینه دارد.
کمترین مبلغ شارژ پنل: ۵۰۰٬۰۰۰ تومان
پرسش‌های متداول
شناسهٔ صیادی چند رقم است و کجای برگهٔ چک چاپ شده؟
شناسه شانزده رقم است و سرویس همین طول را میپذیرد. جای دقیقش روی برگه در منابع آموزشی یکدست گزارش نشده، پس نزدیک کد QR و بالای برگه را نگاه کنید و آن را با سریال چک اشتباه نگیرید.
شناسهٔ صیادی را با خط تیره یا ارقام فارسی بفرستم خطا میگیرم؟
نه. ارقام فارسی به لاتین تبدیل میشود و فاصله و خط تیره حذف میشود. فقط اگر پس از پاکسازی شانزده رقم نماند، پاسخ `invalid_input` میآید و هزینهای کسر نمیشود.
در API باید کد ملی صادرکننده را هم بفرستیم؟
نه. ورودی این سرویس فقط `sayadId` است. اگر در فراخوانهای قدیمی `nationalCode` هم هست، نادیده گرفته میشود و فراخوان خطا نمیدهد. کد ملی صادرکننده فقط در سرویس زنجیرهٔ انتقال لازم است.
این استعلام با پیامک ۷۰۱۷۰۱ چه فرقی دارد؟
پیامک را برای یک نفر روی گوشی میزنید و بنا بر راهنماهای عمومی، وضعیت اعتباری صادرکننده را میدهد. این وب سرویس مشخصات ثبتشدهٔ چک را بهصورت JSON برای نرمافزار شما میآورد و رنگ اعتباری صادرکننده در پاسخش نیست.
برای استعلام باید خودم ذی‌نفع چک باشم؟
سمت ما شرط دیگری جز شناسهٔ معتبر نیست و ورودی فقط `sayadId` است. اینکه سامانهٔ مرجع برای چک‌های مشخصی پاسخ بدهد یا نه، از روی این مستندات قابل تضمین نیست؛ اگر پاسخ نیامد، کد خطا را ببینید.
اگر مشخصات چک درست بود، میتوانم مطمئن باشم در سررسید پاس میشود؟
نه. پاسخ فقط مشخصات ثبتشده را میدهد و موجودی حساب یا توان پرداخت صادرکننده در آن نیست. این استعلام جلوی چک جعلی یا ناهماهنگ را میگیرد، نه چک بیموجودی را.
چرا گاهی تاریخ انقضا در پاسخ خالی است؟
در نمونهٔ مستند `expiration_date` برابر `null` است و مستند دلیل خالی‌بودنش را نمی‌گوید. آن را خطا ندانید و به تاریخ صفر یا رشتهٔ خالی تبدیل نکنید؛ در رابط کاربری همان «ثبت نشده» نشان داده شود.
اگر چکی برای شناسه پیدا نشود هزینه کسر میشود؟
بله. پاسخ `not_found` با وضعیت ۲۰۰ برمیگردد و چون پرسش از سرویس مرجع انجام شده، هزینه دارد. ورودی نامعتبر و خطاهای گذرای مرجع رایگاناند. مبلغ دقیق را از تعرفهٔ زنده ببینید.