ورودی‌های استعلام زنجیره چک صیادی: صادرکننده شرکت باشد چه؟

زنجیرهٔ انتقال چک صیادی برخلاف سرویس‌های دیگر فقط یک شناسه نمی‌خواهد؛ باید کد ملی (یا شناسه ملی) صادرکنندهٔ چک را هم بدهید، و گاهی صادرکننده شرکت است. اگر فرم یا یکپارچه‌سازی شما فقط ده رقم می‌پذیرد، همین‌جا شکست می‌خورید.

این مقاله برای توسعه‌دهنده‌ای است که API زنجیره انتقالات چک صیادی را در محصولش می‌گذارد: چه ورودی‌هایی لازم است، شرکت‌ها چه می‌شوند، و وقتی ورودی کم دارید چه کنید.

سه ورودی، یکی پنهان

ورودی‌های این سرویس این‌هاست:

• sayadId: شناسهٔ ۱۶ رقمی صیادی.
• nationalCode: کد ملی یا شناسه ملی صادرکنندهٔ چک.
• chequeType: نوع چک. اگر نفرستید، مقدار پیش‌فرض یک اعمال می‌شود. در فرم ما این فیلد پنهان است و کاربر آن را نمی‌بیند.

نکتهٔ اشتباه‌برانگیز: نام کلید nationalCode است، ولی لزوماً کد ملی ده‌رقمی نیست. این نام برای حفظ سازگاری با یکپارچه‌سازی‌های موجود عوض نشد.

صادرکننده شرکت باشد

شخص حقیقی: کد ملی ده‌رقمی با رقم کنترل معتبر. شخص حقوقی: شناسهٔ ملی یازده‌رقمی شرکت. هر دو در همین فیلد پذیرفته می‌شوند. ورودی ده رقمی نامعتبر یا طول‌های دیگر (مثلاً نه یا دوازده رقم) پیش از تماس با سرویس رد می‌شوند و هزینه ندارند.

یعنی در کد شما شرط اعتبارسنجی باید یکی از دو حالت را بپذیرد:

js const ok = /^\d{10}$/.test(code) ? validNationalCode(code) : /^\d{11}$/.test(code);

این قطعه فقط شکل را نشان می‌دهد؛ برای شناسهٔ ملی شرکت خودتان رقم کنترل جداگانه نیاز دارید یا همان خطای API را مصرف کنید. اگر کد ملی ده‌رقمی را با اعتبارسنج «شناسه شرکت» بسنجید یا برعکس، چکی که معتبر است رد می‌شود.

کد ملی صادرکننده را از کجا بیاوریم

روی برگهٔ چک چاپ نشده است. سه منبع واقع‌بینانه:

1. دارنده قبلی چک، که معمولاً صادرکننده را می‌شناسد.
2. قرارداد یا فاکتور اصلی که چک بابتش صادر شده.
3. خود صادرکننده، در جریان‌هایی که با او مستقیم سروکار دارید.

در رابط کاربری، این را صریح بنویسید. فیلدی که فقط «کد ملی» دارد و نمی‌گوید «کد ملی صادرکننده، نه خودتان»، تیکت پشتیبانی می‌سازد. در فرم ما هم همین توضیح هست: برای شخص حقیقی کد ملی ده‌رقمی و برای شرکت شناسهٔ ملی یازده‌رقمی.

وقتی کد ملی ندارید، چه کنید

پیشنهاد من یک مسیر دو‌پله‌ای است:

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

نام صادرکننده را از پاسخ استعلام نمی‌شود به کد ملی تبدیل کرد؛ حدس‌زدن هم روش نیست. یک اشتباه در کد ملی هم می‌تواند پاسخ «پیدا نشد» بدهد که از غلط‌بودن خود چک قابل‌تشخیص نیست.

شکل پاسخ و تفسیر آن در نرم‌افزار

پاسخ یک آرایه chain است که هر عنصرش role_type و آرایهٔ customers دارد. به‌خاطر اینکه هر حلقه ممکن است بیش از یک مشتری داشته باشد، در جدول خود رابطهٔ یک‌به‌چند بگذارید: حلقه و طرف‌های حلقه، نه یک ستون نام برای هر حلقه. و ترتیب آرایه را ذخیره کنید؛ همان ترتیب مسیر است.

نمایش به کاربر هم ساده‌تر است اگر نقش‌ها را به برچسب فارسی ترجمه کنید، ولی ترجمه را از مستندات بگیرید، نه از حدس. تا آن لحظه برچسب «حلقه ۱، ۲، ۳» از برچسب غلط بهتر است.

هزینه، خطا و تکرار

مثل بقیهٔ سرویس‌ها: ورودی نامعتبر هزینه ندارد، «پیدا نشد» دارد و ok: false با HTTP ۲۰۰ برمی‌گردد، و نبودن پاسخ از سرویس مرجع هزینه ندارد. برای تکرار خودکار، سقف بگذارید و تکرارِ مستقیمِ «پیدا نشد» را نکنید؛ ممکن است ورودی غلط باشد و دوباره هزینه بدهید. هزینهٔ روز را از صفحهٔ تعرفه بخوانید.

ساخت فرم برای کاربر نهایی

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

برچسب دقیق. «کد ملی یا شناسه ملی صادرکنندهٔ چک»، نه «کد ملی». و زیرش یک سطر کمکی که می‌گوید برای شرکت یازده رقم وارد شود.

تشخیص خودکار نوع. طول ورودی (ده یا یازده) نوع را مشخص می‌کند. لازم نیست کاربر بین «حقیقی» و «حقوقی» انتخاب کند؛ فقط پس از طول، اعتبارسنج مناسب را اجرا کنید.

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

مثال فراخوان

bash curl -X POST 'https://<دامنه>/api/v1/sayad-chain/' \ -H 'Authorization: Bearer melli_live_…' \ -H 'Content-Type: application/json' \ -d '{"sayadId": "1234567890123456", "nationalCode": "10101234567"}'

شناسه‌ها نمونه‌ی ساختاری‌اند. در پاسخ موفق data.chain می‌آید و billing.amountRial مبلغ کسرشده را نشان می‌دهد. برای ثبت در حسابداری خودتان، همان فیلد را بخوانید و مبلغ را از جای دیگری حدس نزنید.

چه زمانی تماس بگیریم، چه زمانی صبر کنیم

برای چک تازه، زنجیره معمولاً کوتاه است و تغییرش نادر؛ ولی برای چکی که فعالانه دست‌به‌دست می‌شود، پاسخ ممکن است در عرض ساعت‌ها فرق کند. پاسخی که از کش آمده با source.cached مشخص می‌شود. اگر تصمیم شما به آخرین حلقه وابسته است، پیش از اقدام نهایی فیلد fetchedAt را ببینید.

تفاوت دو خطای ورودی

دو اشتباه شبیه هم را جدا کنید. اول: کد ملی با ساختار نادرست. این پیش از تماس رد می‌شود و هزینه ندارد. دوم: کد ملی ساختاراً درست ولی متعلق به شخص دیگر. این به سرویس می‌رسد و ممکن است «پیدا نشد» بدهد که هزینه دارد. برای کاهش خطای دوم، پیش از ارسال، نام صادرکننده‌ای که از استعلام چک صیادی گرفته‌اید را کنار فیلد نشان دهید و بپرسید «کد ملی همین شخص است؟». این یک تأیید ساده است که اشتباه دوم را بسیار کم می‌کند.

نگهداری در پایگاه داده

برای کد ملی صادرکننده ستون جداگانه نگذارید که بعداً با کد ملی کاربر قاطی شود. نام ستون را issuer_id بگذارید و نوعش را (حقیقی یا حقوقی) از طول بدست آورید یا جدا ذخیره کنید. و مانند هر داده شخصی، در لاگ فقط نسخهٔ پوشانده‌اش را بنویسید. ما هم در ثبت سفارش از همین روش استفاده می‌کنیم.

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

مبلغ و تاریخ چک را نمی‌دهد؛ برای آن استعلام چک صیادی لازم است. وضعیت وصول را نمی‌گوید. و در این مقاله‌ها هم که درباره تفسیر آن نوشته‌ایم، معنای دقیق هر role_type را حدس نمی‌زنیم. خواندن همین زنجیره در راهنمای دارنده دست سوم آمده است.

اگر عجله دارید

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

صفحهٔ زنجیره انتقالات چک صیادی فیلدها و نمونهٔ پاسخ را کنار هم گذاشته است.