yara724-api/docs/fanavaran/02-read-apis-lookups.md

last_updated, tags, source

last_updated	tags	source
2026-08-08	fanavaran api read lookups	fanavaran-module-docs

02 — Read APIs & Lookups

All read calls use the same business headers as write APIs (authenticationToken, CorpId, ContractId, Location).

Lookup responses are tenant-specific. Cache directory:

files/fanavaran-lookups/{clientKey}/

Config: src/fanavaran/fanavaran-lookup.config.ts
Service: FanavaranLookupService
Local HTTP: LookupsController / LookupsService

---

1. Policy inquiry (guilty party)

Item	Value
Endpoint	GET /Api/BimeApi/v2.0/common/Policies/inquiry-my-policies
Query	InsuranceLineId=5 (third-party), NationalCode={insurerNationalCode}
Usage	Resolve PolicyId for GEN.03
Selection	selectLatestActiveFanavaranPolicy — latest non-expired by EndDate
Cache	fanavaranSync.baseClaim.policyId (resolve-once)
Force refresh	Manual preview forceRefreshPolicy=true only

Errors (YARA messages):

• No policies → contact admin
• Latest expired → cannot send
• Invalid PolicyId/EndDate → contact admin

Do not treat UI resolvePolicy=true as cache-bust (deprecated; ignored for re-inquiry).

---

2. Driver / person inquiry

Used when building GEN.12 to resolve DriverId.

Item	Value
Endpoint	GET /Api/BimeApi/v2.0/common/parties/inquiry-by-unique-identifier
Usage	resolveDriverFanavaranId(clientKey, nationalCode, birthday, driverIsInsurer) via FanavaranLookupService
Cache	fanavaranSync.damageCase.driverId and blameCase.parties[].person.fanavaranDriverId

Prefer cache before live call.

---

3. Remote lookup catalogue

Base: https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0

Name	Fanavaran path	Local YARA route	Used for
accident-causes	/car/base-info/accident-causes	GET /lookups/accident-causes	Accident cause options
accident-report-type	/car/code-list/accident-report-type	GET /lookups/accident-report-type	Defaults / UI
vehicle-use-types	/car/base-info/vehicle-use-types	GET /lookups/vehicle-use-types	Vehicle use
dmg-pay-method	/car/code-list/dmg-pay-method	GET /lookups/dmg-pay-method	Pay method
driving-licence-types	/car/base-info/driving-licence-types	GET /lookups/driving-licence-types	Licence type
accident-culprit-type	/car/code-list/accident-culprit-type	GET /lookups/accident-culprit-type	Culprit type
inspection-place	/car/code-list/inspection-place	GET /lookups/inspection-place	GEN.08
drop-amount-status	/car/code-list/drop-amount-status	GET /lookups/drop-amount-status	GEN.08
car-components	/car/base-info/car-components	GET /lookups/car-components	DmgSectionId
accident-level	/car/code-list/accident-level	GET /lookups/accident-level	Section severity
expert-status	/car/code-list/expert-status	GET /lookups/expert-status	Expertise status
vehicle-kinds	/car/base-info/vehicle-kinds	GET /lookups/vehicle-kinds	GEN.12 VehicleKindId
person-role	/common/code-list/person-role	GET /lookups/person-role	Roles
insurance-corp	/common/code-list/insurance-corp	via fanavaran + resolve	GEN.12 InsuranceCorpId
file-types	/common/base-info/file-types	GET /lookups/file-types	GEN.07 FileTypeId
cities	/common/base-info/cities	GET /lookups/cities	City ids
provinces	/common/base-info/Provinces	GET /lookups/provinces	Provinces
dmg-case-type	/car/code-list/dmg-case-type	GET /lookups/dmg-case-type	GEN.12
dmg-history-status	/car/code-list/dmg-case-history-status	GET /lookups/dmg-history-status	GEN.12
used-place	/car/code-list/used-place	GET /lookups/used-place	Used place
dmg-business-line	/car/code-list/dmg-business-line	GET /lookups/dmg-business-line	Business line

Generic accessor

GET /lookups/fanavaran
GET /lookups/fanavaran/{lookupName}

Lists / fetches by name for the active FANAVARAN_CLIENT.

---

4. Other read helpers (LookupsController)

Route	Purpose
GET /lookups/inquiry-by-vin	VIN inquiry via Fanavaran
GET /lookups/my-policies	Policies for national code
GET /lookups/third-party-policy/:policyId	Policy by id
GET /lookups/body-policy/:policyId	Body policy by id
GET /lookups/accident-reason|way|type|fields	UI accident fields (Tejarat static + Fanavaran map)

---

5. Insurance corp resolve

Item	Value
Env	INSURANCE_CORP_ID = Persian Caption in insurance-corp list
Method	FanavaranLookupService.resolveInsuranceCorpId(clientKey)
Behavior	Fetch list once, match caption → numeric Id, cache
Parsian proven	InsuranceCorpId=329 (for that deployment caption)

---

6. Vehicle kind resolve

Item	Value
Input	Local claimCase.vehicle.carType (sedan/suv/…)
Method	Match Fanavaran vehicle-kinds Caption keywords
Cache	fanavaranSync.damageCase.vehicleKindId
Parsian proven	VehicleKindId=6704 on sample case

---

7. How lookups are used in project

1. First call for a tenant fetches from Fanavaran (authenticated).
2. Writes JSON under files/fanavaran-lookups/{client}/.
3. Subsequent reads prefer cache file.
4. Claim payload builders call getFanavaranLookupRows(clientKey, name) when mapping ids.
5. Outer car parts catalogue can align with Fanavaran car-components (FANAVARAN_CAR_PARTS_CATALOG / helpers).

Dependency: Auth must succeed for cold cache. Transient “try again later” triggers tenant backoff (see 09-error-handling.md).