API و وب سرویس استعلام چک برگشتی

تأمین‌کنندهٔ مصالح ساختمانی پیش از باز کردن حساب اعتباری برای پیمانکاری تازه، یک پرسش دارد: سابقهٔ چک برگشتی هست یا نه؟ این سرویس همین را با یک عدد جواب می‌دهد: data.count، شمار چک‌های برگشتیِ ثبت‌شده برای آن کد ملی. هیچ جدول و فهرستی همراهش نیست.

ورودی دو فیلد است. nationalCode باید ده رقم و دارای رقم کنترل درست باشد. nationalityType یا ۱ است (ایرانی) یا ۲ (اتباع خارجی) و اگر نفرستید، ۱ گرفته می‌شود. مقدار دیگر invalid_input می‌دهد و هزینه ندارد.

صفر را با «پاسخی نیامد» یکی نکنید

count برابر صفر یک پاسخ موفق است و یعنی برای این کد ملی چک برگشتی ثبت نشده. در جاوااسکریپت و PHP صفر «نادرست» حساب می‌شود و شرطی مثل if (!result.count) آدمی را که سابقه ندارد با فراخوانی که شکست خورده یکی می‌کند. ابتدا ok را بررسی کنید و بعد خود عدد را.

ورودی را چگونه آماده کنیم

کد ملی را با ارقام فارسی یا فاصله هم بفرستید، پاک می‌شود؛ ولی شناسهٔ یازده‌رقمی شرکت پذیرفته نمی‌شود و invalid_input می‌گیرد. برای تبعهٔ خارجی، nationalityType را صریح ۲ بگذارید. این سرویس فیلد دیگری برای شناسهٔ اتباع ندارد و همچنان کد ده‌رقمی می‌خواهد.

آنچه این سرویس نمی‌دهد

مبلغ، تاریخ، بانک و شناسهٔ چک‌ها در پاسخ نیست؛ فقط شمارش است. معلوم نمی‌شود کدام چک‌ها برگشته یا تسویه شده‌اند، و سند قاعدهٔ شمارش را هم شرح نمی‌دهد.

این گزارش اعتباری هم نیست. وام، بدهی جاری و امتیاز اعتباری در آن نمی‌آید، و استعلام قضایی ویژهٔ بانک‌ها هم نیست. عدد را یک سیگنال کنار سیگنال‌های دیگر ببینید، نه حکم نهایی دربارهٔ آدم.

هزینه کی کسر می‌شود

هر پاسخ موفق، از جمله count صفر، هزینه دارد چون پرسش واقعاً انجام شده. ورودی نامعتبر، موجودی ناکافی و خطای گذرای مرجع رایگان‌اند. پاسخ 429 هم با Retry-After می‌آید و رایگان است.