Files

s.hajizadeh 0f9f702a00 Add Fanavaran-only flow-test script and document how to run it.

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>

2026-08-17 17:05:33 +03:30

4.4 KiB

Raw Blame History

last_updated, tags, source

last_updated

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

Document every Fanavaran API used in claim registration
Clarify per-insurer dependencies
Identify reusable pieces
Map YARA ↔ Fanavaran integration points
Enable onboarding a new insurer from this docs set alone

Document index

#	Document	Covers
1	01-write-apis.md	Auth + GEN.03 / GEN.12 / GEN.07 / GEN.08 write APIs
2	02-read-apis-lookups.md	Policy inquiry, driver inquiry, lookups
3	03-constants.md	Shared vs tenant constants
4	04-tenant-matrix.md	Shared ✅ / tenant-specific ✅ matrix
5	05-claim-flow.md	Full claim flow + sequence diagrams
6	06-yara-integration.md	Module / service / controller / function map
7	07-data-mapping.md	YARA field → Fanavaran field
8	08-dependencies.md	Mongo, files, env, SMS, audit
9	09-error-handling.md	Errors, retry, backoff, logging
10	10-testing.md	Test scenarios, manual flow-test script, proven case
11	11-onboard-new-client.md	Checklist to add a new insurer

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)
`scripts/data/fanavaran-flow.env.example`	Env template for the flow-test script

Architecture (one glance)

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:

Mongo collection fanavaranClientConfigs (runtime source of truth after boot seed)
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

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.

4.4 KiB Raw Blame History