forked from Yara724/api
192 lines
8.2 KiB
Markdown
192 lines
8.2 KiB
Markdown
---
|
|
last_updated: 2026-08-09
|
|
tags: [fanavaran, api, read, lookups]
|
|
source: 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:
|
|
|
|
```text
|
|
files/fanavaran-lookups/{clientKey}/
|
|
```
|
|
|
|
Config: `src/fanavaran/fanavaran-lookup.config.ts`
|
|
Service: `FanavaranLookupService`
|
|
Local HTTP: `LookupsController` / `LookupsService` (`src/lookups/`)
|
|
|
|
Fanavaran base (docs often call this **BaseURL1**):
|
|
|
|
```text
|
|
https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0
|
|
```
|
|
|
|
Example catalogue URL:
|
|
|
|
```text
|
|
{BaseURL1}/car/base-info/driving-licence-types
|
|
→ YARA: GET /lookups/driving-licence-types
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```http
|
|
GET /lookups/fanavaran
|
|
GET /lookups/fanavaran/{lookupName}
|
|
```
|
|
|
|
Lists / fetches by name for the **active** `FANAVARAN_CLIENT`.
|
|
|
|
---
|
|
|
|
## 4. Lookups module — Nest routes (`LookupsController`)
|
|
|
|
Auth: Bearer + `AuthGuard`. Active tenant from `FANAVARAN_CLIENT` / `CLIENT_ID`.
|
|
|
|
### 4.1 Cached Fanavaran catalogue (dedicated routes)
|
|
|
|
| Nest route | Fanavaran path |
|
|
|------------|----------------|
|
|
| `GET /lookups/accident-causes` | `/car/base-info/accident-causes` |
|
|
| `GET /lookups/accident-report-type` | `/car/code-list/accident-report-type` |
|
|
| `GET /lookups/vehicle-use-types` | `/car/base-info/vehicle-use-types` |
|
|
| `GET /lookups/dmg-pay-method` | `/car/code-list/dmg-pay-method` |
|
|
| `GET /lookups/driving-licence-types` | `/car/base-info/driving-licence-types` |
|
|
| `GET /lookups/accident-culprit-type` | `/car/code-list/accident-culprit-type` |
|
|
| `GET /lookups/inspection-place` | `/car/code-list/inspection-place` |
|
|
| `GET /lookups/drop-amount-status` | `/car/code-list/drop-amount-status` |
|
|
| `GET /lookups/car-components` | `/car/base-info/car-components` |
|
|
| `GET /lookups/accident-level` | `/car/code-list/accident-level` |
|
|
| `GET /lookups/expert-status` | `/car/code-list/expert-status` |
|
|
| `GET /lookups/vehicle-kinds` | `/car/base-info/vehicle-kinds` |
|
|
| `GET /lookups/person-role` | `/common/code-list/person-role` |
|
|
| `GET /lookups/file-types` | `/common/base-info/file-types` |
|
|
| `GET /lookups/cities` | `/common/base-info/cities` |
|
|
| `GET /lookups/provinces` | `/common/base-info/Provinces` |
|
|
| `GET /lookups/dmg-case-type` | `/car/code-list/dmg-case-type` |
|
|
| `GET /lookups/dmg-history-status` | `/car/code-list/dmg-case-history-status` |
|
|
| `GET /lookups/used-place` | `/car/code-list/used-place` |
|
|
| `GET /lookups/dmg-business-line` | `/car/code-list/dmg-business-line` |
|
|
| `GET /lookups/fanavaran` | catalogue metadata (names + URLs) |
|
|
| `GET /lookups/fanavaran/{lookupName}` | any configured name (incl. `insurance-corp`) |
|
|
|
|
### 4.2 Live inquiry helpers
|
|
|
|
| Nest route | Fanavaran path / notes |
|
|
|------------|------------------------|
|
|
| `GET /lookups/inquiry-by-vin?vin=` | `/car/vehicles/inquiry-by-vin` |
|
|
| `GET /lookups/my-policies?nationalCode=&insuranceLineId=` | `/common/Policies/inquiry-my-policies` |
|
|
| `GET /lookups/third-party-policy/:policyId` | `/car/third-party-car-policies/{id}` |
|
|
| `GET /lookups/body-policy/:policyId` | `/car/vehicle-hull-policies/{id}` |
|
|
|
|
### 4.3 UI accident field helpers (local / mapped)
|
|
|
|
| Nest route | Purpose |
|
|
|------------|---------|
|
|
| `GET /lookups/accident-way` | Accident way options |
|
|
| `GET /lookups/accident-reason` | Accident reason options (+ Fanavaran map when available) |
|
|
| `GET /lookups/accident-type` | Accident type options |
|
|
| `GET /lookups/accident-fields` | Combined way + reason + type |
|
|
|
|
---
|
|
|
|
## 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](./09-error-handling.md)).
|