docs

2026-09-21 10:05:49 +03:30
parent 9dd0ec0c00
commit 985c28ed6b
10 changed files with 1068 additions and 8 deletions
--- a/docs/fanavaran/car-body-curl-flow.md
+++ b/docs/fanavaran/car-body-curl-flow.md
@@ -0,0 +1,442 @@
+---
+last_updated: 2026-09-16
+tags: [fanavaran, car-body, hull, curl, vhud, parsian]
+source: fanavaran-apis skill + VHUD GEN docs
+---
+
+# Car-body (بدنه) Fanavaran — manual curl flow
+
+Direct Fanavaran BimeApi calls for **vehicle-hull-claims** (VHUD GEN.03 / GEN.05 / GEN.06).  
+Use this when debugging production without YARA, or to compare with YARA preview payloads.
+
+Credentials below match **`PARSIAN_FANAVARAN_CONFIG`** in `claim-request-management.service.ts` and `scripts/fanavaran-auth.sh parsian`. Tokens (`APP_TOKEN`, `AUTH_TOKEN`) change daily — run auth curls first or `./scripts/fanavaran-auth.sh parsian` then `source files/fanavaran-auth/parsian/tokens.env`.
+
+## Base URLs
+
+| Purpose | URL |
+|---------|-----|
+| Auth | `https://apimanager.iraneit.com/BimeApiManager/api/EITAuthentication/...` |
+| Business (BimeApi v2 car) | `https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/...` |
+
+## Variables (set after each step)
+
+```bash
+# Parsian (ready values)
+export FANAVARAN_APPNAME='ParsianService'
+export FANAVARAN_SECRET='P@r30@n$erv!ce'
+export FANAVARAN_USERNAME='ParsianServiceUser'
+export FANAVARAN_PASSWORD='P@r30@n123'
+export FANAVARAN_CORP_ID='543'
+export FANAVARAN_CONTRACT_ID='28'          # confirm hull ContractId with Fanavaran if files fail
+export FANAVARAN_LOCATION='210050'
+
+export APP_TOKEN=''                        # from GetAppToken response header apptoken
+export AUTH_TOKEN=''                       # from Login response header/body
+
+export HULL_CLAIM_ID='5023617'             # GEN.03 response Id — کد رایانه (NOT ClaimNo); replace after POST
+export HULL_CLAIM_NO='2268'                # display only
+export EXPERTISE_ID=''                     # GEN.06 response Id
+```
+
+### One-shot auth (Parsian) — copy/paste
+
+```bash
+curl -sS -D /tmp/fanavaran-apptoken.headers -o /tmp/fanavaran-apptoken.body \
+  -X POST 'https://apimanager.iraneit.com/BimeApiManager/api/EITAuthentication/GetAppToken' \
+  -H 'appname: ParsianService' \
+  -H 'secret: P@r30@n$erv!ce' \
+  -H 'Content-Length: 0'
+
+export APP_TOKEN="$(awk -F': ' 'tolower($1)=="apptoken"{gsub(/\r/,"",$2);print $2;exit}' /tmp/fanavaran-apptoken.headers)"
+
+curl -sS -D /tmp/fanavaran-login.headers -o /tmp/fanavaran-login.body \
+  -X POST 'https://apimanager.iraneit.com/BimeApiManager/api/EITAuthentication/Login' \
+  -H "appToken: ${APP_TOKEN}" \
+  -H 'userName: ParsianServiceUser' \
+  -H 'password: P@r30@n123' \
+  -H 'Content-Length: 0'
+
+export AUTH_TOKEN="$(awk -F': ' 'tolower($1)=="authenticationtoken"{gsub(/\r/,"",$2);print $2;exit}' /tmp/fanavaran-login.headers)"
+echo "APP_TOKEN=${APP_TOKEN}"
+echo "AUTH_TOKEN=${AUTH_TOKEN}"
+```
+
+Or from repo root: `./scripts/fanavaran-auth.sh parsian && source files/fanavaran-auth/parsian/tokens.env` (uses `AUTHENTICATION_TOKEN` — alias `export AUTH_TOKEN="$AUTHENTICATION_TOKEN"`).
+
+### Id vs ClaimNo (critical)
+
+| Field | Persian | Use in URL? |
+|-------|---------|-------------|
+| **`Id`** | کد رایانه پرونده | **Yes** — `/vehicle-hull-claims/{Id}/files` and `/expertise` |
+| **`ClaimNo`** | شماره پرونده | **No** — do not put `2268` in the path |
+
+Example: `Id=5023617`, `ClaimNo=2268` → use **`5023617`** everywhere below.
+
+---
+
+## Auth — GetAppToken
+
+**Doc:** API.GENR (EIT Authentication)
+
+```bash
+curl -sS -D /tmp/fanavaran-apptoken.headers -o /tmp/fanavaran-apptoken.body \
+  -X POST 'https://apimanager.iraneit.com/BimeApiManager/api/EITAuthentication/GetAppToken' \
+  -H 'appname: ParsianService' \
+  -H 'secret: P@r30@n$erv!ce' \
+  -H 'Content-Length: 0'
+```
+
+Read **`apptoken`** (or `appToken`) from response **headers**:
+
+```bash
+grep -i apptoken /tmp/fanavaran-apptoken.headers
+export APP_TOKEN='<paste apptoken header value>'
+```
+
+Body is usually empty. No JSON body on this call.
+
+---
+
+## Auth — Login
+
+```bash
+curl -sS -D /tmp/fanavaran-login.headers -o /tmp/fanavaran-login.body \
+  -X POST 'https://apimanager.iraneit.com/BimeApiManager/api/EITAuthentication/Login' \
+  -H "appToken: ${APP_TOKEN}" \
+  -H 'userName: ParsianServiceUser' \
+  -H 'password: P@r30@n123' \
+  -H 'Content-Length: 0'
+```
+
+Read **`authenticationToken`** from response header or JSON body:
+
+```bash
+grep -i authenticationtoken /tmp/fanavaran-login.headers
+# or
+cat /tmp/fanavaran-login.body
+export AUTH_TOKEN='<paste token>'
+```
+
+Token is typically valid until **Asia/Tehran midnight** (same as YARA `FanavaranAuthService`).
+
+---
+
+## Business headers (all stages below)
+
+Every BimeApi call needs:
+
+```text
+authenticationToken: <AUTH_TOKEN>
+CorpId: <FANAVARAN_CORP_ID>
+ContractId: <FANAVARAN_CONTRACT_ID>
+Location: <FANAVARAN_LOCATION>
+Content-Type: application/json   # except multipart files
+```
+
+---
+
+## YARA preview (copy JSON bodies from production)
+
+Before curling Fanavaran directly, get the exact payload from Parsian production YARA (same tenant auth as above):
+
+| Stage | YARA preview (Parsian) |
+|-------|-------------------------|
+| 1 Base claim | `GET /v2/fanavaran/parsian/claim-cases/{claimCaseId}/base-claim/preview` |
+| 2 Damage case | **N/A for CAR_BODY** — skipped |
+| 3 Attachments | `GET /v2/fanavaran/parsian/claim-cases/{claimCaseId}/attachments/preview` |
+| 4 Expertise | `GET /v2/fanavaran/parsian/claim-cases/{claimCaseId}/expertise/preview` |
+
+Expert UI BFF (if used): `POST /car-damage/expert/api/fanavaran` with `{"claimCaseId":"..."}` runs remaining stages via the app.
+
+Save preview `payload` into a file, e.g. `stage1-body.json`, then use `@stage1-body.json` in curl.  
+Example hull-only GEN.03 body (proven Parsian case): [`stage1-hull-body.json`](./stage1-hull-body.json).
+
+**Enrichment before POST (YARA does this automatically):**
+
+| Field | Source |
+|-------|--------|
+| `ActualPremium` | `GET /lookups/body-policy/{PolicyId}` → `TotalPremium` |
+| `AccidentCulpritId` | `GET /lookups/inquiry-by-unique-identifier?nationalCode=…&birthday=…` → `driverId` (fallback: policy `CustomerId`) |
+| `CustomerFaultPercent` | **100** (required; درصد تقصير بيمه گذار) |
+| `AuthorityCulpritId` | `GET /lookups/detection-accident-culprits` → بیمه‌گذار (required; مرجع تعيين مقصر) |
+
+Success example: `Id=5026065`, `ClaimNo=1747` — use **`5026065`** for files/expertise.
+
+---
+
+## Stage 1 — GEN.03 Create hull base claim
+
+**Doc:** CAR.VHUD.APIH.GEN.03  
+**Method:** `POST`  
+**URL:** `https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims`
+
+```bash
+curl -sS -X POST \
+  'https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims' \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}" \
+  -H 'Content-Type: application/json' \
+  -d @stage1-body.json
+```
+
+**Body:** paste from YARA **base-claim preview** `payload`. Must be **hull GEN.03 shape** (include `AccidentTypeId`, `IsLicenseReplaced`, `CostSeparationToDmgSections`, `IsOwnerChanged`; do **not** send ثالث-only fields like `DamagedCount`, `HasOtherCulprit`, `CompensationReferenceId`, plaque block on base).
+
+**GEN.03 required lookups (Parsian live):**
+
+| Field | Lookup | Typical collision value |
+|-------|--------|-------------------------|
+| `AccidentTypeId` | `GET /lookups/vehicle-hull-accident-types` | **2** = تصادف(حادثه) |
+| `CostSeparationToDmgSections` | `GET /lookups/ans` | **0** = خیر |
+| `IsOwnerChanged` | `GET /lookups/ans` | **0** = خیر |
+| `IsLicenseReplaced` | — | **`null`** (must be empty; do not send `0` or ثالث `IsLicenseReplacement`) |
+| `CulpritTypeId` | `GET /lookups/vehicle-hull-accident-culprit-type` | **301** = حادثه مقصر شناخته شده دارد (not ثالث `337`) |
+| `CustomerFaultPercent` | — | **100** |
+| `AuthorityCulpritId` | `GET /lookups/detection-accident-culprits` | بیمه‌گذار (`Id` from lookup, fallback **1**) |
+
+Fanavaran direct: `car/base-info/vehicle-hull-accident-types`, `common/code-list/ans`, `car/code-list/vehicle-hull-accident-culprit-type`.
+
+**Success:** JSON includes at least:
+
+```json
+{ "Id": 5023617, "ClaimNo": 2268, ... }
+```
+
+```bash
+export HULL_CLAIM_ID='5023617'   # use Id
+export HULL_CLAIM_NO='2268'      # do not use in nested URLs
+```
+
+### Optional — GET base claim (verify Id exists)
+
+```bash
+curl -sS -X GET \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}"
+```
+
+### Optional — PUT hull shape (if files/expertise say پرونده خسارت بدنه یافت نشد)
+
+If stage 1 was created with a wrong (ثالث-shaped) body, **PUT** the same hull GEN.03 field set onto the existing `Id` (body = preview payload after hull mapping):
+
+```bash
+curl -sS -X PUT \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}" \
+  -H 'Content-Type: application/json' \
+  -d @stage1-body-hull.json
+```
+
+YARA does this automatically before attachments/expertise when product is CAR_BODY.
+
+---
+
+## Stage 2 — Damage case (ثالث GEN.12) — **does not exist for hull**
+
+**Do not call:**
+
+```text
+POST .../vehicle-hull-claims/{id}/dmg-cases   ❌ Feature:url(...) not found
+```
+
+Third-party only:
+
+```text
+POST .../third-party-car-financial-claims/{id}/dmg-cases
+```
+
+For car-body YARA: damage-case preview/submit **returns skipped**. Flow is **1 → 3 → 4**.
+
+---
+
+## Stage 3 — GEN.05 Attachments (one file per request)
+
+**Doc:** CAR.VHUD.APIH.GEN.05  
+**Method:** `POST`  
+**URL:** `https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/{HULL_CLAIM_ID}/files`
+
+**Parsian `FileTypeId`:** `63` (سایر مدارک خسارت) — proven on ثالث; verify in `file-types` lookup for hull if rejected.
+
+### JSON metadata (multipart part)
+
+YARA sends this as multipart field **`Param`** (`application/json`):
+
+```json
+{
+  "FileName": "photo_example.jpg",
+  "FileTypeId": 63,
+  "ClaimId": 5023617
+}
+```
+
+`FileName` must **exactly** match the uploaded file name. `ClaimId` = same as URL `{HULL_CLAIM_ID}` (`Id`, not `ClaimNo`).
+
+### curl (matches YARA `postFanavaranMultipart`: Param + Param1)
+
+```bash
+export FILE_PATH='/path/to/photo_example.jpg'
+export FILE_NAME='photo_example.jpg'
+
+curl -sS -X POST \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/files" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}" \
+  -F "Param={\"FileName\":\"${FILE_NAME}\",\"FileTypeId\":63,\"ClaimId\":${HULL_CLAIM_ID}};type=application/json" \
+  -F "Param1=@${FILE_PATH};filename=${FILE_NAME}"
+```
+
+Repeat once per image (YARA does not batch hull uploads).
+
+**Success example:** `{ "Id": 2008737, "Status": 2003, ... }`
+
+### Optional — list files (GET)
+
+```bash
+curl -sS -X GET \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/files" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}"
+```
+
+---
+
+## Stage 4 — GEN.06 Expertise
+
+**Doc:** CAR.VHUD.APIH.GEN.06  
+**Method:** `POST`  
+**URL:** `https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/{HULL_CLAIM_ID}/expertise`
+
+**Body:** paste from YARA **expertise preview** `payload` (GEN.06 — **not** ثالث GEN.08).
+
+| Field | Source (YARA) |
+|-------|----------------|
+| `VehicleCurrentValue` | `evaluation.priceDrop.carPrice` if set; else **`GET /lookups/body-policy/{PolicyId}` → `VehicleValue`** |
+| `DmgSections[].DmgKindId` | **`5485`** (تخریب) from **`GET /lookups/vehicle-hull-dmg-kind`** |
+| `DmgSectionCosts[].DmgCostKindId` | **`1`** (Id for «مجموع لوازم») from **`GET /lookups/vehicle-hull-dmg-cost-kinds`** — not `DmgCostCategoryId` |
+
+Hull expects fields such as:
+
+- `ClaimExpertId` (Parsian assessor: **29** = `ExpertiseClaimExpertId`)
+- `Wage`, `ComponentReplacementCost`, `WasteValue`, `DropAmount`, `VehicleCurrentValue`
+- `MotorNo`, `ChassisNo`, `VIN`, `PlaqueNo`, `PlaqueSerial`, `BuiltYear`
+- `DmgSections[]` with `Count`, `Desc`, `AccessoryKindId`, `DmgSectionCosts[]`
+- **No** `DmgCaseId`, `InspectionPlaceId`, `DropAmountStatus`, `RepairWage`
+
+```bash
+curl -sS -X POST \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/expertise" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H "CorpId: ${FANAVARAN_CORP_ID}" \
+  -H "ContractId: ${FANAVARAN_CONTRACT_ID}" \
+  -H "Location: ${FANAVARAN_LOCATION}" \
+  -H 'Content-Type: application/json' \
+  -d @stage4-expertise-body.json
+```
+
+**Success:** `{ "Id": 71927, "ClaimId": 78776, ... }` → store as `expertiseId`.
+
+---
+
+## Stage map (YARA vs Fanavaran)
+
+| YARA / user stage | Fanavaran doc | HTTP | Exists for بدنه? |
+|-------------------|---------------|------|------------------|
+| Auth | GetAppToken + Login | POST | Yes |
+| 1 Base claim | GEN.03 | POST `/vehicle-hull-claims` | Yes |
+| 1b Sync hull body | GEN.03 | PUT `/vehicle-hull-claims/{Id}` | Yes (fix row) |
+| 2 Damage case | GEN.12 (ثالث) | POST `.../dmg-cases` | **No — skip** |
+| 3 Attachments | GEN.05 | POST `.../{Id}/files` | Yes |
+| 4 Expertise | GEN.06 | POST `.../{Id}/expertise` | Yes |
+
+## Not used for normal collision car-body
+
+| Doc | URL |
+|-----|-----|
+| GEN.01 bulk import | POST `/vehicle-hull-import-claims` |
+| GEN.02 import files | POST `/vehicle-hull-import-claims/{PrvId}/files` |
+| GEN.04 culprits | POST `.../{Id}/culprits` |
+
+## Related docs
+
+- Skill summary: `.agents/skills/fanavaran-apis/references/car-body-cases.md`
+- VHUD extracts: `.agents/skills/fanavaran-apis/references/vehicle-hull/`
+- Local auth script: `scripts/fanavaran-auth.sh parsian`
+
+---
+
+## Parsian — full flow script (after auth)
+
+Run the **One-shot auth** block above first. Save YARA preview JSON to `stage1-body.json` and `stage4-expertise-body.json`. Set `FILE_PATH` / `FILE_NAME` for stage 3.
+
+```bash
+# Stage 1 — POST hull base claim
+curl -sS -X POST \
+  'https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims' \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050' \
+  -H 'Content-Type: application/json' \
+  -d @stage1-body.json
+
+# Stage 1 optional — GET
+curl -sS -X GET \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050'
+
+# Stage 1 optional — PUT hull sync
+curl -sS -X PUT \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050' \
+  -H 'Content-Type: application/json' \
+  -d @stage1-body-hull.json
+
+# Stage 2 — (skip — no dmg-cases for hull)
+
+# Stage 3 — POST one file
+FILE_PATH='/path/to/photo.jpg'
+FILE_NAME='photo.jpg'
+curl -sS -X POST \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/files" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050' \
+  -F "Param={\"FileName\":\"${FILE_NAME}\",\"FileTypeId\":63,\"ClaimId\":${HULL_CLAIM_ID}};type=application/json" \
+  -F "Param1=@${FILE_PATH};filename=${FILE_NAME}"
+
+# Stage 3 optional — GET files list
+curl -sS -X GET \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/files" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050'
+
+# Stage 4 — POST expertise
+curl -sS -X POST \
+  "https://apimanager.iraneit.com/BimeApiManager/api/BimeApi/v2.0/car/vehicle-hull-claims/${HULL_CLAIM_ID}/expertise" \
+  -H "authenticationToken: ${AUTH_TOKEN}" \
+  -H 'CorpId: 543' \
+  -H 'ContractId: 28' \
+  -H 'Location: 210050' \
+  -H 'Content-Type: application/json' \
+  -d @stage4-expertise-body.json
+```