forked from Yara724/api
fanavaran sales integration docs
This commit is contained in:
139
docs/fanavaran/02-read-apis-lookups.md
Normal file
139
docs/fanavaran/02-read-apis-lookups.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
last_updated: 2026-08-08
|
||||
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`
|
||||
|
||||
---
|
||||
|
||||
## 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. 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](./09-error-handling.md)).
|
||||
Reference in New Issue
Block a user