yara724api/docs/inquiry-participants-frontend-guide.fa.md

راهنمای فرانت‌اند برای ارسال اطلاعات استعلام

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

ساختار کلی درخواست

برای پرونده THIRD_PARTY:

{
  "driver": {
    "nationalCode": "0012345678",
    "birthday": "1370/01/01",
    "hasDrivingLicense": true,
    "licenseNumber": "123456789",
    "licenseType": "1"
  },
  "vehicleOwner": { "sameAs": "DRIVER" },
  "thirdPartyPolicyholder": { "sameAs": "VEHICLE_OWNER" },
  "vehicle": {
    "registrationState": "CURRENT",
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "isNewCar": false
  },
  "sheba": "IR123456789012345678901234"
}

برای پرونده CAR_BODY، نقش بیمه‌گذار بدنه هم الزامی است:

{
  "driver": {
    "nationalCode": "0012345678",
    "birthday": "1370/01/01",
    "hasDrivingLicense": false
  },
  "vehicleOwner": { "sameAs": "DRIVER" },
  "thirdPartyPolicyholder": {
    "nationalCode": "0023456789",
    "birthday": "1360/02/02"
  },
  "carBodyPolicyholder": {
    "nationalCode": "0034567890",
    "birthday": "1350/03/03"
  },
  "vehicle": {
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "isNewCar": false
  },
  "sheba": "IR123456789012345678901234"
}

sheba فقط در routeهایی که قبلاً اطلاعات بانکی را در مرحله استعلام دریافت می‌کردند ارسال می‌شود؛ در V6 مرکز تماس، شماره شبا در این body نیست و بعداً توسط کاربر دریافت می‌شود.

هر استعلام با اطلاعات کدام نقش انجام می‌شود؟

فرانت‌اند فقط اشخاص را با ساختار نقش‌محور ارسال می‌کند؛ انتخاب کد ملی مناسب برای هر سرویس در بک‌اند انجام می‌شود:

استعلام	کد ملی مورد استفاده	شناسه خودرو/بانکی
بیمه شخص ثالث با پلاک یا VIN	thirdPartyPolicyholder.nationalCode	پلاک یا vehicle.vin
بیمه بدنه با پلاک یا VIN	carBodyPolicyholder.nationalCode	پلاک یا vehicle.vin
تطبیق شبا	vehicleOwner.nationalCode	sheba
گواهینامه	driver.nationalCode	driver.licenseNumber

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

در مرحله بانکی بعدی جریان V6، برای پرونده‌های جدید فقط sheba لازم است. بک‌اند کد ملی مالک خودرو را از participants و participantRoles ذخیره‌شده در پرونده تقصیر می‌خواند. فیلدهای قدیمی nationalCodeOfInsurer یا nationalCodeOfOwner فقط برای پرونده‌های تاریخی فاقد اطلاعات نقش‌محور fallback هستند؛ اگر همراه پرونده جدید ارسال شوند باید با مالک ذخیره‌شده یکسان باشند.

پنل‌های کارشناسی اطلاعات کامل اشخاص را در parties[].participants و نگاشت نقش‌ها را در parties[].participantRoles دریافت می‌کنند. اطلاعات راننده حتی اگر در استعلام بیمه یا شبا استفاده نشود در همین ساختار ذخیره و نمایش داده می‌شود.

نقش‌ها و فیلدهای هر شخص

هر نقش باید یکی از این دو حالت را داشته باشد، نه هر دو را:

1. اطلاعات یک شخص جدید؛ یا
2. ارجاع با sameAs به شخصی که قبلاً در همین درخواست معرفی شده است.

فیلد	کاربرد	وضعیت
nationalCode	کد ملی شخص	برای شخص جدید الزامی
birthday	تاریخ تولد جلالی	برای شخص جدید الزامی
fullName	نام نمایشی شخص	اختیاری
sameAs	اتصال این نقش به نقش دیگر	به‌جای اطلاعات شخص جدید
hasDrivingLicense	داشتن گواهینامه راننده	برای نقش راننده الزامی
licenseNumber	شماره گواهینامه	اگر hasDrivingLicense=true الزامی
licenseType	نوع گواهینامه	اگر hasDrivingLicense=true الزامی

مقادیر مجاز sameAs عبارت‌اند از:

• DRIVER
• VEHICLE_OWNER
• THIRD_PARTY_POLICYHOLDER
• CAR_BODY_POLICYHOLDER

برای sameAs هیچ‌کدام از nationalCode، birthday، fullName، اطلاعات گواهینامه یا phoneNumber را در همان آبجکت نفرستید.

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

اطلاعات خودرو و پلاک

فیلد	کاربرد	وضعیت
vehicle.registrationState	وضعیت ثبت رسمی خودرو	CURRENT یا RECENTLY_TRANSFERRED؛ پیش‌فرض CURRENT
vehicle.currentPlate	پلاک رسمی فعلی و شناسه اصلی خودرو	الزامی
vehicle.previousPlate	پلاک قبلی در انتقال اخیر	فقط در RECENTLY_TRANSFERRED
vehicle.previousPolicyholderNationalCode	کد ملی بیمه‌گذار مربوط به پلاک قبلی	فقط در RECENTLY_TRANSFERRED و الزامی
vehicle.vin	شماره شاسی/VIN	در انتقال اخیر الزامی؛ در صورت ارسال دقیقاً ۱۷ کاراکتر
vehicle.isNewCar	نو بودن خودرو	اختیاری

اجزای پلاک:

{
  "leftDigits": "44",
  "centerAlphabet": "ب",
  "centerDigits": "111",
  "ir": "22"
}

leftDigits، centerDigits و ir را می‌توان به‌صورت string یا number فرستاد؛ ارسال string پیشنهاد می‌شود تا صفرهای ابتدایی از بین نروند. centerAlphabet باید حرف فارسی پلاک باشد.

انتقال اخیر

{
  "vehicle": {
    "registrationState": "RECENTLY_TRANSFERRED",
    "currentPlate": {
      "leftDigits": "44",
      "centerAlphabet": "ب",
      "centerDigits": "111",
      "ir": "22"
    },
    "previousPlate": {
      "leftDigits": "55",
      "centerAlphabet": "ج",
      "centerDigits": "222",
      "ir": "33"
    },
    "previousPolicyholderNationalCode": "0098765432",
    "vin": "NAAM01E15HK123456"
  }
}

سیستم ابتدا پلاک فعلی را با کد ملی بیمه‌گذار فعلیِ مرتبط با نوع بیمه استعلام می‌کند. اگر نتیجه ناموجود، منقضی یا فاقد بیمه‌نامه مرتبط باشد، پلاک قبلی را با previousPolicyholderNationalCode امتحان می‌کند. نتیجه پلاک قبلی فقط در صورت تطبیق VIN پذیرفته می‌شود؛ پلاک قبلی هرگز جایگزین پلاک فعلی نمی‌شود.

حتی در route مربوط به VIN، آبجکت vehicle از قرارداد مشترک استفاده می‌کند و currentPlate در قرارداد فعلی الزامی است. مقدار VIN در vehicle.vin قرار می‌گیرد، نه در فیلد سطح بالای vin.

ترتیب پیشنهادی نمایش فرم

1. پلاک فعلی و وضعیت انتقال خودرو را بگیرید.
2. اگر انتقال اخیر بود، پلاک قبلی، کد ملی بیمه‌گذار پلاک قبلی و VIN را بگیرید.
3. اطلاعات راننده و وضعیت گواهینامه را بگیرید.
4. بپرسید مالک خودرو همان راننده است یا شخص دیگری؛ در حالت یکسان از sameAs استفاده کنید.
5. بیمه‌گذار شخص ثالث را از بین راننده، مالک یا شخص دیگر انتخاب کنید.
6. در CAR_BODY همین کار را برای بیمه‌گذار بدنه انجام دهید.
7. خلاصه اطلاعات را به کاربر نشان دهید و سپس درخواست استعلام را ارسال کنید.

مسیرهای اصلی

بدنه درخواست در همه این مسیرها همین ساختار را دارد:

جریان	مسیر پلاک	مسیر VIN
کاربر V2	/v2/blame-request-management/initial-form/:requestId	/v2/blame-request-management/initial-form-vin/:requestId
کارشناس/پرونده‌ساز V3 تا V5	.../run-inquiries/:requestId	.../run-inquiries-vin/:requestId
مرکز تماس V6	/v6/call-center-blame/run-inquiry/:requestId	/v6/call-center-blame/run-inquiry-vin/:requestId

در جریان‌های V3 تا V5، فراخوان اول برای طرف مقصر (FIRST) و فراخوان دوم، فقط در THIRD_PARTY، برای طرف زیان‌دیده (SECOND) است. اطلاعات بیمه‌گذار برای هر دو طرف الزامی است.

تفاوت اطلاعات مقصر و زیان‌دیده

ساختار نقش‌محور اشخاص و خودرو برای هر دو طرف یکسان است، اما ترتیب و قواعد کسب‌وکار آن‌ها تفاوت دارد:

پرونده و طرف	نقش‌ها و رفتار
THIRD_PARTY / FIRST (مقصر)	راننده، مالک و بیمه‌گذار شخص ثالثِ خودروی مقصر ارسال می‌شوند. شبا در این فراخوان لازم نیست. بیمه‌نامه مقصر باید متعلق به شرکت بیمه همین سامانه باشد.
THIRD_PARTY / SECOND (زیان‌دیده)	راننده، مالک و بیمه‌گذار شخص ثالثِ خودروی زیان‌دیده ارسال می‌شوند. این مرحله فقط بعد از امضای مقصر و احراز OTP زیان‌دیده اجرا می‌شود. sheba الزامی است و با کد ملی vehicleOwner اعتبارسنجی می‌شود. بیمه‌گذار زیان‌دیده نیز همیشه باید مشخص باشد.
CAR_BODY / FIRST (بیمه‌گذار/زیان‌دیده بدنه)	هر چهار نقش راننده، مالک، بیمه‌گذار شخص ثالث و بیمه‌گذار بدنه ارسال می‌شوند. sheba در همین فراخوان الزامی است و با کد ملی vehicleOwner اعتبارسنجی می‌شود. استعلام بدنه با کد ملی carBodyPolicyholder انجام می‌شود.

در V2 و V6 که شبا در مرحله جداگانه از کاربر دریافت می‌شود، شبا داخل درخواست استعلام مقصر ارسال نمی‌شود؛ بک‌اند هنگام مرحله بانکی آن را با کد ملی مالک ذخیره‌شده تطبیق می‌دهد.

فیلدهایی که نباید ارسال شوند

این فیلدها دیگر بخشی از قرارداد ورودی نیستند و ارسال آن‌ها باعث خطای اعتبارسنجی می‌شود:

nationalCodeOfDriver
driverBirthday
driverLicense
licenseType                 // در سطح بالا؛ مقدار صحیح داخل driver است
nationalCodeOfInsurer
insurerBirthday
insurerLicense
driverIsInsurer
userNoCertificate
plate                       // در سطح بالا؛ مقدار صحیح داخل vehicle.currentPlate است
plateId
vin                         // در سطح بالا؛ مقدار صحیح داخل vehicle.vin است
isNewCar                    // در سطح بالا؛ مقدار صحیح داخل vehicle.isNewCar است
phoneNumber                 // در participantها
unknown                     // حذف شده؛ بیمه‌گذار همیشه باید مشخص باشد

خطاهای رایج فرانت‌اند

• ارسال vehicleOwner به‌صورت خالی؛ باید شخص جدید یا sameAs باشد.
• استفاده از sameAs همراه با nationalCode یا birthday.
• ارسال carBodyPolicyholder برای THIRD_PARTY.
• ارسال unknown برای هر نقش؛ این فیلد دیگر پذیرفته نمی‌شود.
• فرستادن previousPlate بدون registrationState=RECENTLY_TRANSFERRED.
• فرستادن RECENTLY_TRANSFERRED بدون previousPlate، previousPolicyholderNationalCode یا vin.
• فرستادن previousPolicyholderNationalCode برای خودروی دارای وضعیت CURRENT.
• قرار دادن VIN یا پلاک در سطح بالای body.
• ارسال شماره تلفن در آبجکت شخص.
• تکرار کد ملی راننده یا بیمه‌گذار در مرحله شبا؛ تطبیق شبا همیشه با مالک خودرو انجام می‌شود.

مستند مدل دامنه و جزئیات تصمیم معماری در inquiry-participants-proposal.fa.md قرار دارد.