forked from Yara724/api
s.hajizadeh
0f9f702a00
Track the tester and env template in git so a new tenant can be exercised without a YARA claim; keep filled client env files (secrets, national codes) ignored. Co-authored-by: Cursor <cursoragent@cursor.com>
102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
---
|
|
last_updated: 2026-08-17
|
|
tags: [fanavaran, documentation, parsian, third-party-claim]
|
|
source: fanavaran-module-docs
|
|
---
|
|
|
|
# Fanavaran Integration — Technical Reference
|
|
|
|
مرجع فنی یکپارچهسازی یارا با سرویسهای فناوران برای ثبت خسارت مالی ثالث خودرو.
|
|
|
|
**Template tenant:** `parsian` (proven end-to-end, 2026-08-03 — claim `CL68535` / publicId `A00153`)
|
|
**Also configured:** `tejaratno` (production shape), `moallem` (auth seeded; expert/file-type ids TBD)
|
|
|
|
## Goals
|
|
|
|
1. Document every Fanavaran API used in claim registration
|
|
2. Clarify per-insurer dependencies
|
|
3. Identify reusable pieces
|
|
4. Map YARA ↔ Fanavaran integration points
|
|
5. Enable onboarding a new insurer from this docs set alone
|
|
|
|
## Document index
|
|
|
|
| # | Document | Covers |
|
|
|---|----------|--------|
|
|
| 1 | [01-write-apis.md](./01-write-apis.md) | Auth + GEN.03 / GEN.12 / GEN.07 / GEN.08 write APIs |
|
|
| 2 | [02-read-apis-lookups.md](./02-read-apis-lookups.md) | Policy inquiry, driver inquiry, lookups |
|
|
| 3 | [03-constants.md](./03-constants.md) | Shared vs tenant constants |
|
|
| 4 | [04-tenant-matrix.md](./04-tenant-matrix.md) | Shared ✅ / tenant-specific ✅ matrix |
|
|
| 5 | [05-claim-flow.md](./05-claim-flow.md) | Full claim flow + sequence diagrams |
|
|
| 6 | [06-yara-integration.md](./06-yara-integration.md) | Module / service / controller / function map |
|
|
| 7 | [07-data-mapping.md](./07-data-mapping.md) | YARA field → Fanavaran field |
|
|
| 8 | [08-dependencies.md](./08-dependencies.md) | Mongo, files, env, SMS, audit |
|
|
| 9 | [09-error-handling.md](./09-error-handling.md) | Errors, retry, backoff, logging |
|
|
| 10 | [10-testing.md](./10-testing.md) | Test scenarios, **manual flow-test script**, proven case |
|
|
| 11 | [11-onboard-new-client.md](./11-onboard-new-client.md) | Checklist to add a new insurer |
|
|
|
|
## Related sources (code)
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `src/core/config/fanavaran-client.config.ts` | Tenant keys, seed auth + defaults |
|
|
| `src/fanavaran/` | Auth, lookup, audit, YARA HTTP surface |
|
|
| `src/claim-request-management/claim-request-management.service.ts` | Payload build + staged submit orchestration |
|
|
| `src/claim-request-management/fanavaran-policy-selection.ts` | Latest active policy selection |
|
|
| `src/lookups/` | Local lookup HTTP façade over Fanavaran |
|
|
| `.agents/skills/fanavaran-apis/references/third-party-cases.md` | Agent-oriented implementation rules |
|
|
| `docs/external-api-curls.md` | Ready-to-run curl sequences |
|
|
| `scripts/fanavaran-auth.sh` | Token helper |
|
|
| `scripts/fanavaran-flow-test.sh` | Manual Fanavaran-only staged submit (see [10-testing.md](./10-testing.md)) |
|
|
| `scripts/data/fanavaran-flow.env.example` | Env template for the flow-test script |
|
|
|
|
## Architecture (one glance)
|
|
|
|
```text
|
|
YARA claim flow (THIRD_PARTY only)
|
|
│
|
|
├─ auto / manual stage triggers
|
|
│
|
|
▼
|
|
ClaimRequestManagementService
|
|
├─ FanavaranAuthService (GetAppToken → Login, cache until Tehran midnight)
|
|
├─ FanavaranLookupService (lookups + insurance-corp resolve)
|
|
├─ FanavaranAuditService (fanavaranAuditLogs)
|
|
└─ FanavaranClientConfigService (Mongo fanavaranClientConfigs)
|
|
│
|
|
▼
|
|
Fanavaran API Manager
|
|
https://apimanager.iraneit.com/BimeApiManager/api
|
|
```
|
|
|
|
## Stages (order)
|
|
|
|
| Stage | Fanavaran doc | Local ids stored |
|
|
|-------|---------------|------------------|
|
|
| Auth | EITAuthentication | token cache (`fanavaranAuthTokens`) |
|
|
| Policy inquiry | inquiry-my-policies | `fanavaranSync.baseClaim.policyId` |
|
|
| Base claim | GEN.03 | `claimId`, `claimNo` |
|
|
| Damage case | GEN.12 | `dmgCaseId`, `driverId`, … |
|
|
| Attachments | GEN.07 | `fanavaranSync.attachments.files[]` |
|
|
| Expertise | GEN.08 | `expertiseId` |
|
|
|
|
Soft-ensure: later stages create earlier ones if missing (damage → base; expertise → damage → base).
|
|
|
|
## Secrets policy
|
|
|
|
This documentation **does not** embed live secrets. Auth values (`appName`, `secret`, `username`, `password`) live in:
|
|
|
|
1. Mongo collection `fanavaranClientConfigs` (runtime source of truth after boot seed)
|
|
2. Seed fallback: `SEED_FANAVARAN_CLIENT_PROFILES` in `fanavaran-client.config.ts`
|
|
|
|
Use `scripts/fanavaran-auth.sh <client>` or System Settings admin APIs to inspect/update tenant config.
|
|
|
|
## Activate a tenant
|
|
|
|
```bash
|
|
FANAVARAN_CLIENT=parsian # or tejaratno | moallem
|
|
INSURANCE_CORP_ID='...' # Persian caption matching Fanavaran insurance-corp lookup
|
|
```
|
|
|
|
Optional: `CLIENT_ID=8` maps to `parsian` when `FANAVARAN_CLIENT` is unset.
|