---
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.