# Third-party (ثالث) — Fanavaran stage bodies (current YARA)

Snapshot of **what `ClaimRequestManagementService` actually sends** for `THIRD_PARTY` as of this version.

- Base: `POST /car/third-party-car-financial-claims` (GEN.03)
- Damage case: `POST …/{claimId}/dmg-cases` (GEN.12)
- Attachments: `POST …/{claimId}/files` (GEN.07, multipart)
- Expertise: `POST …/{claimId}/expertise` (GEN.08)

**Send rule:** keep keys in the JSON even when the value is `null`. Fanavaran treats omitted keys differently from explicit `null`.

**Source columns**

| Tag | Meaning |
|-----|---------|
| **system** | Hardcoded YARA default / tenant `fanavaranClientConfigs` |
| **lookup** | Fanavaran codebook (`GET /lookups/…`) |
| **inquiry** | Live Fanavaran inquiry (policies, VIN, parties, vehicle GET) |
| **user** | Collected in YARA UI (owner, expert, file-maker) |
| **staff** | FileMaker `ThirdPartyClaimExpertId` / FileReviewer `ThirdPartyExpertiseClaim` on V4/V5; else tenant defaults |
| **derived** | Computed from other fields (dates, sums) |

Parsian tenant defaults used below: `ClaimExpertId=154`, `ExpertiseClaimExpertId=29`, `ClaimFileTypeId=63`, `AccidentCityId=701`, `AccidentReportTypeId=155`, `CulpritTypeId=337`, `CulpritLicenceTypeId=2`, `CompensationReferenceId=167`.

---

## Stage 1 — Base claim (GEN.03)

**Must send (non-null):** `PolicyId`, `ClaimExpertId`, `AccidentDate`, `AnnouncementDate`, `AccidentTime`, `AccidentCauseId`, `AccidentCityId`, `AccidentReportTypeId`, `CulpritTypeId`, `CulpritLicenceTypeId`, `CulpritLicenceNo`, `CulpritLicenceIssuDate`, `DamagedCount`, `EstimateAmount` (> 0), `AccidentLocationAddress`, `HasOtherCulprit`, `IsFatalAccident`, `IsAccidentOutOfBorder`, `IsPlaqueChanged`, `IsLicenseMatchWithVehicleKind`, `IsLicenseReplacement`, `PoliceOfficerId`, `AccidentVehicleUsedId`.

**May be null** (and currently are, unless noted): everything else in the table.

| Field | Persian | Type | Null? | Current source | Notes |
|-------|---------|------|-------|----------------|-------|
| PolicyId | شناسه بیمه‌نامه مقصر | number | **no** | **inquiry** `GET /lookups/my-policies` (guilty national code, line ثالث) | Cached on `fanavaranSync.baseClaim.policyId` |
| ClaimExpertId | کارشناس مسئول پرونده | number | **no** | **staff** FileMaker `ThirdPartyClaimExpertId` on V4/V5, else tenant | GEN.03 role, not expertise |
| AccidentDate | تاریخ حادثه | string (Jalali `yyyy/mm/dd`) | **no** | **user** accident datetime, else blame `createdAt` | |
| AnnouncementDate | تاریخ اعلام | string Jalali | **no** | **derived** = AccidentDate | |
| DocReceivedDate | تاریخ وصول مدارک | string Jalali | **no** | **derived** = AccidentDate | Third-party only (not on hull whitelist) |
| AccidentTime | ساعت حادثه | string `HH:mm` | **no** | **user** / **derived** from createdAt | |
| AccidentLocationAddress | نشانی محل حادثه | string | **no** | **system** `"استان تهران شهر تهران"` | Should later be **user** |
| AccidentCauseId | علت حادثه | number | **no** | **system** `6` | Lookup: `GET /lookups/accident-causes`. Expert `accidentReason.fanavaran` exists but is not yet wired as the sent id |
| AccidentCityId | شهر محل حادثه | number | **no** | **system** `701` تهران | Lookup: `GET /lookups/cities` |
| AccidentReportTypeId | نحوه اعلام حادثه | number | **no** | **system** `155` | Lookup: `GET /lookups/accident-report-type` |
| AccidentVehicleUsedId | نوع کاربری خودرو | number | **no** | **inquiry** VIN / policy vehicle `UsedId`, else tenant `1` | Lookup: `GET /lookups/vehicle-use-types` |
| CulpritTypeId | نوع مقصر | number | **no** | **system** `337` | Lookup: `GET /lookups/accident-culprit-type` (ثالث, not hull) |
| CulpritLicenceTypeId | نوع گواهینامه مقصر | number | **no** | **system** `2` | Lookup: `GET /lookups/driving-licence-types` |
| CulpritLicenceNo | شماره گواهینامه مقصر | string | **no** | **user** party licence if stored, else dummy `9705463515` | Must never be empty |
| CulpritLicenceIssuDate | تاریخ صدور گواهینامه | string Jalali | **no** | **system** `"1394/10/13"` | Should later be **user** |
| EstimateAmount | مبلغ برآورد | number | **no** | **user** expert part prices, else provisional `1000` | Must be > 0 |
| CompensationReferenceId | مرجع جبران | number | **no** | **system** `167` | Tenant default |
| DamagedCount | تعداد زیان‌دیدگان | number | **no** | **system** `1` | |
| HasOtherCulprit | مقصر دیگر دارد؟ | number (ans) | **no** | **system** `0` | Lookup `GET /lookups/ans` |
| IsFatalAccident | فوت دارد؟ | number | **no** | **system** `0` | |
| IsAccidentOutOfBorder | خارج از مرز؟ | number | **no** | **system** `0` | |
| IsPlaqueChanged | پلاک تعویضی؟ | number | **no** | **system** `0` | |
| IsLicenseMatchWithVehicleKind | گواهینامه متناسب؟ | number | **no** | **system** `1` | |
| IsLicenseReplacement | گواهینامه تعویضی؟ | number | **no** | **system** `0` | Third-party uses this name (hull uses `IsLicenseReplaced` and must be null) |
| PoliceOfficerId | افسر پلیس | number | **no** | **system** `1` | |
| ActualPremium | حق بیمه واقعی | number | yes | unused on ثالث create | |
| ArchiveNo | شماره بایگانی | string | yes | — | |
| AuthorityCulpritId | مرجع تعیین مقصر | number | yes | **null** on ثالث | Hull requires this |
| AccidentCulpritId | شناسه مقصر در فناوران | number | yes | **null** on ثالث | Hull fills from parties inquiry |
| ClaimCompletionDate | تاریخ تکمیل | string | yes | — | |
| CostSeparationToDmgSections | تفکیک هزینه به نقاط | number | yes | **null** on ثالث | Hull sends `0` |
| CouponNo | شماره کوپن | string | yes | — | |
| CourtArchiveNo | شماره بایگانی دادگاه | string | yes | — | |
| CustomerFaultPercent | درصد تقصیر بیمه‌گذار | number | yes | **null** on ثالث | Hull sends `100` |
| CulpritLicenceCityId | شهر صدور گواهینامه | number | yes | Lookup `cities` | |
| CulpritLicenceCountryId | کشور صدور گواهینامه | number | yes | Lookup `countries` | |
| CulpritLicenceForeignCityName | شهر خارجی صدور | string | yes | — | |
| DmgAssessorFirstCreationTime | زمان ایجاد ارزیاب | string | yes | — | |
| EntryDate | تاریخ ورود | string | yes | — | |
| GlassBreakReasonId | علت شکست شیشه | number | yes | — | |
| IsOwnerChanged | مالک تغییر کرده؟ | number | yes | **null** | Hull sends `0` |
| IsSurplusArticleEighthLaw | مازاد ماده ۸ | number | yes | — | |
| PlaqueCityId … PlaqueSerial | پلاک (بلوک پایه) | mixed | yes | **null** on GEN.03 ثالث | Plaque belongs on GEN.12 |
| PoliceReportDesc / Seri / Serial | مشخصات کروکی | string | yes | **user** later | |
| PreviousPolicyEndDate | پایان بیمه‌نامه قبلی | string | empty `""` | **system** | |
| StatusChangeDate | تاریخ تغییر وضعیت | string | yes | — | |
| TrackingCode | کد پیگیری | string | yes | — | |
| UnknownCulpritCauseId | علت مقصر ناشناس | number | yes | — | |

**Inquiries used at this stage**

- `GET /lookups/my-policies?nationalCode=&insuranceLineId=` (ثالث)
- Optional VIN → `AccidentVehicleUsedId`

**User input already needed (even if some are still defaulted)**

- Guilty party national code (to find PolicyId)
- Accident date/time
- Expert priced parts (EstimateAmount) when available

---

## Stage 2 — Damage case (GEN.12)

Nested under Fanavaran `claimId` (`Id` from stage 1, never `ClaimNo`).

**Must send (non-null in proven Parsian):** `DriverId`, `VehicleKindId`, `AccidentVehicleUsedId`, `DmgCaseTypeId`, `DmgHistoryStatus`, `FaultPercent`, `InsuranceCorpId`, `LicenceNo`, `LicenceTypeId`, `LicenceIssuDate`, `EstimateAmount`, `Desc`, plaque block (`PlaqueKindId`, `PlaqueSampleId`, left/middle/right/serial), `BeginDate`/`EndDate` when inquiry has them.

If `DriverId` is missing, **submit** (not preview) registers GEN.44 `POST /common/other-people` and stores `otherPersonId`.

| Field | Persian | Type | Null? | Current source |
|-------|---------|------|-------|----------------|
| DriverId | شناسه راننده زیان‌دیده در فناوران | number | **no** on submit | **inquiry** `GET /lookups/inquiry-by-unique-identifier` (national code + Jalali birthday). Fallback **GEN.44** create |
| OwnerId | شناسه مالک | number | yes | currently `null` |
| VehicleKindId | نوع خودرو | number | **no** | **inquiry** VIN vehicle `VehicleKindId`, else **lookup** `GET /lookups/vehicle-kinds` matched to `claim.vehicle.carType` |
| AccidentVehicleUsedId | کاربری | number | **no** | **inquiry** vehicle `UsedId` / use-types, else tenant |
| VIN | شماره شاسی ۱۷ رقمی | string | preferred | **inquiry** plate/VIN inquiry |
| ChassisNo | شماره شاسی | string | preferred | **inquiry** |
| MotorNo | شماره موتور | string | preferred | **inquiry** |
| BuiltYear | سال ساخت | number | preferred | **inquiry** VIN / mapped `PrdDte` |
| PlaqueKindId | نوع پلاک | number | **no** | **inquiry** vehicle GET, else national-plate default |
| PlaqueSampleId | نمونه پلاک | number | **no** | same |
| PlaqueLeftNo | دو رقم سمت چپ | string | **no** | **user** plate / **inquiry** |
| PlaqueMiddleCodeId | حرف پلاک (کد فناوران) | number | **no** | **derived** from plate letter |
| PlaqueRightNo | سه رقم | string | **no** | **user** / **inquiry** |
| PlaqueSerial | ایران | string | **no** | **user** / **inquiry** |
| PlaqueNo | پلاک رشته‌ای | string | preferred | **derived** |
| PlaqueCityId | شهر پلاک | number | yes | **inquiry** vehicle |
| PolicyNo | شماره چاپی بیمه‌نامه زیان‌دیده | string | preferred | **inquiry** ESG/Tejarat mapped |
| PolicyCINumber | کد یکتای بیمه‌نامه | string | preferred | **inquiry** `PlcyUnqCod` |
| BeginDate | شروع پوشش | string Jalali | preferred | **inquiry** |
| EndDate | پایان پوشش | string Jalali | preferred | **inquiry** |
| PreviousPolicyEndDate | پایان بیمه‌نامه قبلی | string | empty ok | **derived** from EndDate |
| InsuranceCorpId | شرکت بیمه زیان‌دیده | number | **no** | **lookup** insurance-corp for tenant |
| DmgCaseTypeId | نوع مورد خسارت | number | **no** | **system** `175` · lookup `dmg-case-type` |
| DmgHistoryStatus | وضعیت سابقه خسارت | number | **no** | **system** `5214` · lookup `dmg-history-status` |
| FaultPercent | درصد تقصیر | number | **no** | **system** `100` |
| DriverIsOwner | راننده همان مالک؟ | number | **no** | **user** `driverIsInsurer` → 1/0 |
| LicenceNo | شماره گواهینامه زیان‌دیده | string | **no** | **user**, else dummy |
| LicenceTypeId | نوع گواهینامه | number | **no** | **system** same as CulpritLicenceTypeId |
| LicenceIssuDate | تاریخ صدور | string Jalali | **no** | **user** birthday used as stand-in, else dummy date |
| LicenceCityId / CountryId / ForeignCityName | محل صدور گواهینامه | mixed | yes | currently null |
| EstimateAmount | برآورد مورد خسارت | number | **no** | **system** provisional constant |
| Desc | شرح قطعات آسیب‌دیده | string | **no** | **user** selected outer parts labels joined with `/` |
| DmgCaseId | (response) | number | — | store as local `dmgCaseId` |

**Lookups:** `vehicle-kinds`, `vehicle-use-types`, `dmg-case-type`, `dmg-history-status`, `insurance-corp`, `file-types` (later), `driving-licence-types`, `ans`.

**Inquiries:** parties by national code + birthday; VIN inquiry; optional vehicle GET; plate inquiry on blame.

---

## Stage 3 — Attachments (GEN.07)

Multipart: field `Param` = JSON, field `Param1` = file bytes. One file per request. Parsian `FileTypeId=63` (سایر مدارک خسارت).

| Field | Persian | Type | Null? | Current source |
|-------|---------|------|-------|----------------|
| FileName | نام فایل | string | **no** | **user** upload name (must match binary name) |
| FileTypeId | نوع مدرک | number | **no** | **lookup** `GET /lookups/file-types` via tenant `ClaimFileTypeId` |
| Files[].FileName / FileTypeId | تکرار متادیتا | object | **no** | same |
| ClaimId | (hull only on Param) | number | hull yes | third-party URL already has claimId |

Files themselves are **user** (documents, damage photos, factors).

---

## Stage 4 — Expertise (GEN.08)

Requires local `dmgCaseId`. `ClaimExpertId` here is the **assessor** role (Parsian `29`), from FileReviewer `ThirdPartyExpertiseClaim` on V4/V5.

| Field | Persian | Type | Null? | Current source |
|-------|---------|------|-------|----------------|
| DmgCaseId | شناسه مورد خسارت | number | **no** | stage 2 response |
| ClaimExpertId | کارشناس ارزیاب | number | **no** | **staff** / tenant `ExpertiseClaimExpertId` |
| DmgAssessmentDate | تاریخ بازدید | string Jalali | **no** | **derived** expert reply `submittedAt` |
| InspectionTime | ساعت بازدید | string `HH:mm` | **no** | **derived** |
| InspectionPlaceId | محل بازدید | number | **no** | **system** `282` · lookup `GET /lookups/inspection-place` |
| RepairWage | اجرت کل | number | **no** | **user** sum of part `salary` |
| ComponentReplacementCost | قطعه کل | number | **no** | **user** sum of part `price` |
| WasteValue | داغی کل | number | **no** | **user** daghi prices |
| DropAmountStatus | وضعیت افت | number | **no** | **system** `5458` · lookup `drop-amount-status` |
| DropAmountAdditionsDeductions | مبلغ افت | number | **no** | **user** `evaluation.priceDrop.total` or `0` |
| ComponentReplacementTaxAndToll | مالیات قطعه | number | **no** | **system** `0` |
| DamagedVehicleCurrentPrice | قیمت روز خودرو | number | yes | **user** price-drop `carPrice` |
| WentDistanceByExpert | مسافت کارشناس | number | yes | currently `null` |
| DmgSections[].DmgSectionId | شناسه نقطه آسیب | number | **no** | **user** catalog `partId` · lookup `car-components` |
| DmgSections[].AccidentLevel | شدت آسیب | number | **no** | **user** `typeOfDamage` or default `5456` · lookup `accident-level` |
| DmgSections[].Desc | شرح | string | **no** | **user** |
| DmgSections[].ComponentReplacementCost | قیمت قطعه | number | **no** | **user** |
| DmgSections[].RepairWage | اجرت | number | **no** | **user** |
| DmgSections[].WasteValue | داغی | number | **no** | **user** |

---

## YARA preview / submit

| Stage | Preview | Submit |
|-------|---------|--------|
| 1 | `GET /v2/fanavaran/{client}/claim-cases/{id}/base-claim/preview` | `POST …/base-claim/submit` |
| 2 | `GET …/damage-case/preview` | `POST …/damage-case/submit` |
| 3 | `GET …/attachments/preview` | `POST …/attachments/submit` |
| 4 | `GET …/expertise/preview` | `POST …/expertise/submit` |

Nested Fanavaran URLs always use stored `claimId` (کد رایانه), never `claimNo`.