yara724-api/docs/inquiry-participants-frontend-guide.fa.md

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

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

پاسخ کوتاه درباره unknown

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

{
  "thirdPartyPolicyholder": { "unknown": true }
}

قواعد آن:

• فقط برای طرف زیان‌دیده (SECOND) مجاز است؛ برای طرف مقصر (FIRST) خطا برمی‌گردد.
• فقط برای thirdPartyPolicyholder مجاز است؛ برای راننده، مالک یا بیمه‌گذار بدنه مجاز نیست.
• وقتی unknown: true ارسال می‌شود، هیچ فیلد هویتی دیگری در همان آبجکت نفرستید.
• در استعلام پلاکی شخص ثالث، استعلام بیمه‌گذار عمداً skip می‌شود و سیستم نباید شخصی را حدس بزند.
• استعلام‌های راننده، مالکیت خودرو و اطلاعات افراد شناخته‌شده همچنان اجرا می‌شوند.
• اگر هویت بیمه‌گذار مشخص است، اصلاً از unknown استفاده نکنید و اطلاعات واقعی یا sameAs را بفرستید.

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

برای پرونده 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 نیست و بعداً توسط کاربر دریافت می‌شود.

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

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

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

فیلد	کاربرد	وضعیت
nationalCode	کد ملی شخص	برای شخص جدید الزامی
birthday	تاریخ تولد جلالی	برای شخص جدید الزامی
fullName	نام نمایشی شخص	اختیاری
sameAs	اتصال این نقش به نقش دیگر	به‌جای اطلاعات شخص جدید
unknown	نامشخص بودن بیمه‌گذار ثالث	فقط SECOND در THIRD_PARTY
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.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"
    },
    "vin": "NAAM01E15HK123456"
  }
}

سیستم ابتدا پلاک فعلی را استعلام می‌کند. اگر نتیجه ناموجود، منقضی یا فاقد بیمه‌نامه مرتبط باشد، پلاک قبلی را امتحان می‌کند. نتیجه پلاک قبلی فقط در صورت تطبیق 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) است. همین تفاوت تعیین می‌کند که unknown مجاز است یا نه.

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

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

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

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

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

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