GWM : API Swagger for TAP

app/Config/Acl.php

@@ -42,6 +42,7 @@ class Acl
         '#^/sales#' => ['roles' => [ADMIN_ROLE_ID, HEAD_ROLE_ID, STAFF_ROLE_ID]],
         '#^/expense#' => ['roles' => [ADMIN_ROLE_ID, HEAD_ROLE_ID, STAFF_ROLE_ID]],
         '#^/sendDataToTPA#' => ['roles' => [ADMIN_ROLE_ID, HEAD_ROLE_ID, ACCOUNT_MANAGER_ROLE_ID, MANAGER_ROLE_ID]],
+        '#^/swagger#' => ['roles' => [ADMIN_ROLE_ID, HEAD_ROLE_ID, ACCOUNT_MANAGER_ROLE_ID, MANAGER_ROLE_ID]],
 
 
 

app/Config/Routes.php

@@ -29,6 +29,8 @@ $routes->get('/chatbottest', 'ChatbotControllerNew::chatbotest');
 $routes->get('/chatbot', 'ChatbotControllerNew::chatbot');
 
 $routes->get('/swagger', 'SwaggerController::index', ['filter' => 'authMVC']);
+$routes->get('/swagger/tpa', 'SwaggerController::tpa', ['filter' => 'authMVC']);
+$routes->get('/swagger/tpa-spec', 'SwaggerController::tpaSpec', ['filter' => 'authMVC']);
 $routes->get('/fedeploy', 'DeployController::fedeploy_view', ['filter' => 'authMVC']);
 $routes->post('/fedeploy', 'DeployController::fedeploy', ['filter' => 'authMVC']);
 $routes->get('/visitOffBoardCheck', 'EmployeeController::visitOffBoardCheck');

app/Controllers/SwaggerController.php

@@ -1,10 +1,84 @@
 <?php namespace App\Controllers;
 
 use App\Controllers\BaseController;
+use CodeIgniter\Exceptions\PageNotFoundException;
 
 class SwaggerController extends BaseController
 {
-    public function index(){        
+    public function index()
-        return view('swagger/index');
+    {
-    }    
+        return view('swagger/index', [
+            'specUrl' => base_url('assets/api.yaml'),
+            'pageTitle' => 'Swagger UI',
+            'swaggerPreauthorize' => [],
+        ]);
+    }
+
+    /**
+     * Swagger UI for TPA external integrations OpenAPI spec (openapi/tpa-external-integrations.yaml).
+     * Pre-fills Authorize from the same `.env` keys the API controllers use (`getenv`).
+     */
+    public function tpa()
+    {
+        return view('swagger/index', [
+            'specUrl' => base_url('swagger/tpa-spec'),
+            'pageTitle' => 'TPA external APIs — Swagger UI',
+            'swaggerPreauthorize' => $this->buildTpaSwaggerPreauthorize(),
+        ]);
+    }
+
+    /**
+     * Values for Swagger UI Authorize (apiKey / basic). Uses runtime env — keep `/swagger/tpa` access-controlled.
+     *
+     * @return list<array<string, string>>
+     */
+    protected function buildTpaSwaggerPreauthorize(): array
+    {
+        return [
+            ['kind' => 'apiKey', 'scheme' => 'MediAssistUsername', 'value' => $this->readEnvString('MEDI_ASSIST_API_USERNAME')],
+            ['kind' => 'apiKey', 'scheme' => 'MediAssistPassword', 'value' => $this->readEnvString('MEDI_ASSIST_API_PASSWORD')],
+            ['kind' => 'apiKey', 'scheme' => 'VidalSubscriptionKey', 'value' => $this->readEnvString('VIDAL_API_SUBSCRIPTION_KEY')],
+            ['kind' => 'apiKey', 'scheme' => 'VidalIrSubscriptionKey', 'value' => $this->readEnvString('VIDAL_SUBSCRIPTION_KEY')],
+            ['kind' => 'apiKey', 'scheme' => 'VidalWellnessSubscriptionKey', 'value' => $this->readEnvString('VIDAL_WELLNESS_SUBSCRIPTION_KEY')],
+            [
+                'kind' => 'basic',
+                'scheme' => 'HealthIndiaTokenBasic',
+                'username' => $this->readEnvString('HEALTH_INDIA_USERNAME'),
+                'password' => $this->readEnvString('HEALTH_INDIA_PASSWORD'),
+            ],
+        ];
+    }
+
+    /**
+     * Read `.env` the same way as the rest of CodeIgniter (`env()` then `getenv()`).
+     */
+    protected function readEnvString(string $key): string
+    {
+        if (function_exists('env')) {
+            $v = \env($key);
+            if ($v !== null) {
+                return \is_bool($v) ? '' : (string) $v;
+            }
+        }
+
+        $g = \getenv($key);
+
+        return $g === false ? '' : (string) $g;
+    }
+
+    /**
+     * Serves the OpenAPI YAML from project root /openapi (not under public/).
+     */
+    public function tpaSpec()
+    {
+        $path = ROOTPATH . 'openapi/tpa-external-integrations.yaml';
+        if (! is_readable($path)) {
+            throw PageNotFoundException::forPageNotFound('OpenAPI spec not found.');
+        }
+
+        return $this->response
+            ->setHeader('Content-Type', 'application/yaml; charset=UTF-8')
+            ->setHeader('Cache-Control', 'public, max-age=300')
+            ->setBody(file_get_contents($path));
+    }
 }

app/Views/swagger/index.php

@@ -4,7 +4,7 @@
 
 <head>
   <meta charset="UTF-8">
-  <title>Swagger UI</title>
+  <title><?= esc($pageTitle ?? 'Swagger UI') ?></title>
   <link rel="stylesheet" type="text/css" href="<?= base_url('assets/swagger/swagger-ui.css') ?>">
   <link rel="icon" type="image/png" href="<?= base_url('assets/swagger/favicon-32x32.png') ?> sizes=" 32x32" />
   <link rel="icon" type="image/png" href="<?= base_url('assets/swagger/favicon-16x16.png') ?> sizes=" 16x16" />
@@ -31,15 +31,15 @@
 <body>
   <div id="swagger-ui"></div>
 
-  <script src="<?= base_url('assets/swagger/swagger-ui-bundle.js') ?>">console.log(base_url); </script>
+  <script src="<?= base_url('assets/swagger/swagger-ui-bundle.js') ?>"></script>
-  <script src="<?= base_url('assets/swagger/swagger-ui-standalone-preset.js') ?>"> </script>
+  <script src="<?= base_url('assets/swagger/swagger-ui-standalone-preset.js') ?>"></script>
   <script>
     window.onload = function() {
-      // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "<?= base_url('assets/api.yaml') ?>",
+        url: "<?= esc($specUrl ?? base_url('assets/api.yaml'), 'js') ?>",
         dom_id: '#swagger-ui',
         deepLinking: true,
+        persistAuthorization: true,
         presets: [
           SwaggerUIBundle.presets.apis,
           SwaggerUIStandalonePreset
@@ -48,12 +48,28 @@
           SwaggerUIBundle.plugins.DownloadUrl
         ],
         layout: "StandaloneLayout"
-      })
+      });
-      // End Swagger UI call region
 
-      window.ui = ui
+      window.ui = ui;
-    }
 
+      <?php if (! empty($swaggerPreauthorize)): ?>
+      try {
+        <?php foreach ($swaggerPreauthorize as $row): ?>
+          <?php if (($row['kind'] ?? '') === 'apiKey'): ?>
+        if (typeof ui.preauthorizeApiKey === 'function') {
+          ui.preauthorizeApiKey(<?= json_encode($row['scheme'] ?? '') ?>, <?= json_encode($row['value'] ?? '') ?>);
+        }
+          <?php elseif (($row['kind'] ?? '') === 'basic'): ?>
+        if (typeof ui.preauthorizeBasic === 'function') {
+          ui.preauthorizeBasic(<?= json_encode($row['scheme'] ?? '') ?>, <?= json_encode($row['username'] ?? '') ?>, <?= json_encode($row['password'] ?? '') ?>);
+        }
+          <?php endif; ?>
+        <?php endforeach; ?>
+      } catch (e) {
+        console.warn('Swagger preauthorize', e);
+      }
+      <?php endif; ?>
+    };
   </script>
 </body>
 

openapi/tpa-external-integrations.yaml

@@ -0,0 +1,922 @@
+openapi: 3.0.3
+info:
+  title: Nhance — TPA external API integrations
+  description: |
+    OpenAPI description of **outbound** HTTP calls made by Nhance to third-party TPA systems.
+    Base URLs and credentials come from environment variables (see **Authorize** / security schemes below).
+    This is **not** the public REST API of the Nhance application itself.
+
+    Controllers: `MediAssistApiController`, `VidalApiController`, `VoloApiController`,
+    `FhplApiController`, `HealthIndiaApiController`.
+
+    **Credentials (.env)** — use the same variable names as `getenv()` / `env()` in PHP:
+    MediAssist: `MEDI_ASSIST_API_USERNAME`, `MEDI_ASSIST_API_PASSWORD`; URLs: `MEDI_ASSIST_API_BASE_URL_*`.
+    Vidal: `VIDAL_API_SUBSCRIPTION_KEY`, `VIDAL_SUBSCRIPTION_KEY` (IR only), `VIDAL_WELLNESS_SUBSCRIPTION_KEY`; base `VIDAL_API_BASE_URL`.
+    Volo login: `VOLO_API_EMAIL`, `VOLO_API_PASSWORD`, `VOLO_LOGGED_IN_PORTAL`; bases `VOLO_API_ADMIN_BASE_URL`, `VOLO_API_CONSUMER_BASE_URL`.
+    FHPL: `FHPL_TOKEN_URL`, `FHPL_USER_NAME`, `FHPL_PASSWORD`, `FHPL_GRANT_TYPE`; API `FHPL_BASE_URL`.
+    Health India: `HEALTH_INDIA_TOKEN_URL`, `HEALTH_INDIA_USERNAME`, `HEALTH_INDIA_PASSWORD`; API `HEALTH_INDIA_BASE_URL`.
+  version: 1.0.0
+
+tags:
+  - name: MediAssist
+  - name: Vidal
+  - name: Volo
+  - name: FHPL
+  - name: HealthIndia
+
+servers:
+  - url: https://example.invalid
+    description: >
+      Default placeholder only. Each TPA uses its own base URL from environment variables;
+      many MediAssist endpoints use a full URL per env var (see operation descriptions).
+
+# ----------------------------------------------------------------------------
+# MediAssist — servers vary per env var (often full URL including path).
+# Default hosts shown are illustrative; override via env.
+# ----------------------------------------------------------------------------
+paths:
+
+  /mediassist/claim-submit:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: Submit claim (claim push)
+      description: |
+        URL from `MEDI_ASSIST_API_BASE_URL_CLAIMSUBMIT` (full URL).
+        Headers `Username` / `Password` from `MEDI_ASSIST_API_USERNAME` / `MEDI_ASSIST_API_PASSWORD`.
+      operationId: mediassistSubmitClaim
+      servers:
+        - url: https://apiintegration.mediassist.in
+          description: Example host — replace with env URL
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MediAssistSubmitClaimBody'
+      responses:
+        '200':
+          description: Wrapped by app helper; success includes `claimReferenceNo` in nested payload
+
+  /mediassist/ecard:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: E-card URL request
+      description: URL from `MEDI_ASSIST_API_BASE_URL_ECARDREQUEST`.
+      operationId: mediassistEcardRequest
+      servers:
+        - url: https://apiintegration.mediassist.in
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [employeeId, policyNo]
+              properties:
+                employeeId: { type: string }
+                policyNo: { type: string }
+      responses:
+        '200':
+          description: Response includes `ecardUrl` when successful
+
+  /mediassist/benef-details:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: Get beneficiary / enrollment (TPA ID pull)
+      description: URL from `MEDI_ASSIST_API_BASE_URL_FETCHTPA`. Paginated with `startIndex` / `range`.
+      operationId: mediassistGetBenefDetails
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [policyNo]
+              properties:
+                policyNo: { type: string }
+                startDate: { type: string, default: "" }
+                endDate: { type: string, default: "" }
+                isDeActivedata: { type: boolean, default: false }
+                startIndex: { type: integer }
+                range: { type: integer, example: 100 }
+                employeeId: { type: string, default: "" }
+      responses:
+        '200':
+          description: Expects `benefDetails` and `count` in data
+
+  /mediassist/claim-status:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: Claim status / claims data
+      description: URL from `MEDI_ASSIST_API_BASE_URL_CLAIMSTATUS`.
+      operationId: mediassistClaimStatus
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MediAssistClaimStatusBody'
+      responses:
+        '200':
+          description: Expects `claimsData` array in response data
+
+  /mediassist/ir-submission:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: IR (information) submission with attachment URLs
+      description: URL from `MEDI_ASSIST_API_BASE_URL_IRSUBMISSION`.
+      operationId: mediassistIRSubmission
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [ClaimID, Attachments]
+              properties:
+                ClaimID: { type: string }
+                Attachments:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      AttachmentName: { type: string }
+                      AttachmentPath: { type: string, description: Public download URL }
+      responses:
+        '200':
+          description: App treats `status` from helper as success/failure
+
+  /mediassist/network-hospital:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: Network hospital list
+      description: |
+        Built as `{MEDI_ASSIST_API_BASE_URL}/NetworkHospital` (env base + path).
+      operationId: mediassistNetworkHospital
+      requestBody:
+        content:
+          application/json:
+            example:
+              startIndex: 0
+              endIndex: 10
+              policyNumber: "97000063250400000031"
+      responses:
+        '200':
+          description: Third-party response passed through
+
+  /mediassist/intimate-claim:
+    post:
+      tags: [MediAssist]
+      security:
+        - MediAssistUsername: []
+          MediAssistPassword: []
+      summary: Intimate claim (UAT sample in code)
+      description: |
+        **Note:** `IntimateClaim()` in code uses a hardcoded URL and test credentials;
+        production should use env-driven URL and secrets.
+      operationId: mediassistIntimateClaimDev
+      deprecated: true
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                Username: { type: string }
+                Password: { type: string }
+                policyNo: { type: string }
+                memberId: { type: number }
+                DateOfAdmisssion: { type: string, format: date }
+                HospitalName: { type: string }
+                AilmentDescription: { type: string }
+                ContactNo: { type: string }
+
+  # --------------------------------------------------------------------------
+  # Vidal Health TPA (Azure APIM)
+  # --------------------------------------------------------------------------
+  /partner-integration/api/files/upload-url:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalSubscriptionKey: []
+      summary: Get signed URL for document upload
+      description: |
+        `VIDAL_API_BASE_URL` + `/files/upload-url`.
+        Header `Ocp-Apim-Subscription-Key` = `VIDAL_API_SUBSCRIPTION_KEY`.
+        Second step uploads file via PUT to returned `signedUrl` (Azure Blob).
+      operationId: vidalFileUploadUrl
+      servers:
+        - url: https://devapigw.vidalhealthtpa.com
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                scope: { type: string, example: document type }
+                fileName: { type: string }
+      responses:
+        '200':
+          description: Expects `data.signedUrl`, `data.fileId`
+
+  /partner-integration/api/claims/submit:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalSubscriptionKey: []
+      summary: Submit claim
+      operationId: vidalClaimsSubmit
+      servers:
+        - url: https://devapigw.vidalhealthtpa.com
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VidalClaimSubmitBody'
+      responses:
+        '200':
+          description: Success path checks `data.status == SUCCESS` and nested claim numbers
+
+  /partner-integration/api/claims/claim-dependent-info:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalSubscriptionKey: []
+      summary: Claim dependent info / status poll
+      operationId: vidalClaimDependentInfo
+      servers:
+        - url: https://devapigw.vidalhealthtpa.com
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                empNO: { type: string, default: "" }
+                tpaCardID: { type: string, default: "" }
+                claimID: { type: string, description: Set when known }
+                emailID: { type: string, default: "" }
+                mobileNO: { type: string, default: "" }
+      responses:
+        '200':
+          description: Expects `data.data.claims[]`
+
+  /partner-integration/enrollment/info:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalSubscriptionKey: []
+      summary: Enrollment / beneficiary pull (Vidal V2)
+      description: |
+        URL from `vidalEnrollmentInfoApiUrl()`: strips trailing `/api` from `VIDAL_API_BASE_URL`
+        and appends `/enrollment/info`, or falls back to dev URL.
+        Paginates with `startIndex` / `endIndex`.
+      operationId: vidalEnrollmentInfo
+      servers:
+        - url: https://devapigw.vidalhealthtpa.com
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                policyNo: { type: string }
+                startIndex: { type: integer, example: 1 }
+                endIndex: { type: integer, example: 100 }
+
+  /vidal/wellness-sso:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalWellnessSubscriptionKey: []
+      summary: Wellness SSO (encrypted payload)
+      description: |
+        `VIDAL_WELLNESS_BASE_URL`. Headers include `Ocp-Apim-Subscription-Key`,
+        `apiver`, `mode: encrypt`. Body uses AES-encrypted payload + `source` / `subPartnerId`.
+      operationId: vidalWellnessSSO
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                payload: { type: string, description: iv:ciphertext base64 format }
+                source: { type: string }
+                subPartnerId: { type: string }
+
+  /vidal/ir-submission:
+    post:
+      tags: [Vidal]
+      security:
+        - VidalIrSubscriptionKey: []
+      summary: IR submission (shortfall documents)
+      description: |
+        Full URL from `VIDAL_API_BASE_URL_IRSUBMISSION`.
+        Uses `VIDAL_SUBSCRIPTION_KEY` (note distinct from `VIDAL_API_SUBSCRIPTION_KEY` in code).
+        Body sent as JSON string in some call paths.
+      operationId: vidalIRSubmission
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                shortFallNo: { type: string }
+                fileId: { type: string, description: Single file }
+                fileIdList:
+                  type: array
+                  items: { type: string }
+                  description: Multiple files
+
+  # --------------------------------------------------------------------------
+  # Volo / TrueCover (admin + consumer bases)
+  # --------------------------------------------------------------------------
+  /external/login:
+    post:
+      tags: [Volo]
+      security: []
+      summary: Login — obtain access token
+      description: |
+        `VOLO_API_ADMIN_BASE_URL` + `/external/login`.
+        Body uses `VOLO_API_EMAIL`, `VOLO_API_PASSWORD`, `VOLO_LOGGED_IN_PORTAL`.
+      operationId: voloLogin
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                emailId: { type: string }
+                password: { type: string }
+                loggedInPortal:
+                  type: string
+                  example: POLICY_CONFIGURATION_PORTAL
+      responses:
+        '200':
+          description: Expects `accessToken` for Authorization header on subsequent calls
+
+  /trueclaim/tpa/get-Enrollment-dump:
+    get:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Enrollment dump by endorsement
+      operationId: voloGetEnrollmentDumpByEndorsement
+      parameters:
+        - in: query
+          name: insurerPolicyNumber
+          required: true
+          schema: { type: string }
+        - in: query
+          name: endorsmentNo
+          required: true
+          schema: { type: string }
+
+  /trueclaim/tpa/getHospitalByInsurerName:
+    get:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Hospitals by insurer name
+      operationId: voloGetHospitalByInsurerName
+      parameters:
+        - in: query
+          name: insurerName
+          required: true
+          schema: { type: string }
+
+  /trueclaim/tpa/doc:
+    post:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Upload document (body defined by TPA)
+      operationId: voloUploadDocument
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+
+  /trueclaim/tpa/get-Enroll-dump:
+    get:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Enrollment dump by insurer policy number
+      operationId: voloGetEnrollmentDump
+      parameters:
+        - in: query
+          name: insurerPolicyNumber
+          required: true
+          schema: { type: string }
+
+  /truecover/external-service/claim-status:
+    post:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: External claim status (consumer base)
+      description: |
+        `VOLO_API_CONSUMER_BASE_URL` + `/truecover/external-service/claim-status`.
+      operationId: voloFetchExternalClaimStatus
+      servers:
+        - url: https://consumer.example.ewatpa.com
+          description: Replace with VOLO_API_CONSUMER_BASE_URL
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [tpaClaimNo]
+              properties:
+                tpaClaimNo: { type: string }
+
+  /trueclaim/tpa/getTpaData:
+    post:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: TPA data by date range and entity
+      operationId: voloGetTpaData
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [startDate, endDate, entityId]
+              properties:
+                startDate: { type: string }
+                endDate: { type: string }
+                entityId: { type: string }
+
+  /trueclaim/create-new-all-member-id-card-pdf:
+    get:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: E-card PDF (base64 in response body)
+      operationId: voloGetEcardPdf
+      parameters:
+        - in: query
+          name: employeeId
+          required: true
+          schema: { type: string }
+        - in: query
+          name: entityId
+          required: true
+          schema: { type: string }
+
+  /trueclaim/get-entity-from-policy:
+    get:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Resolve entity id from policy number
+      operationId: voloGetEntityFromPolicy
+      parameters:
+        - in: query
+          name: policyNumber
+          required: true
+          schema: { type: string }
+
+  /trueclaim/policy-bazaar/intimate-claim:
+    post:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Intimate claim (claim push)
+      description: |
+        Built payload includes `hospitalId` (`VOLO_DEFAULT_HOSPITAL_ID`), `memberId`,
+        dates, `potentialClaimAmount`, `claimDocuments` (pdf URL), `entityId`, `insurerPolicyNumber`.
+      operationId: voloIntimateClaim
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/VoloIntimateClaimBody'
+
+  /trueclaim/tpa/getClaimData:
+    post:
+      tags: [Volo]
+      security:
+        - VoloBearerToken: []
+      summary: Get claim data
+      operationId: voloGetClaimData
+      parameters:
+        - in: query
+          name: claimId
+          required: true
+          schema: { type: string }
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              description: Empty JSON object sent as body
+
+  # --------------------------------------------------------------------------
+  # FHPL
+  # --------------------------------------------------------------------------
+  /oauth/token:
+    get:
+      tags: [FHPL]
+      security: []
+      summary: Generate OAuth token
+      description: |
+        URL from `FHPL_TOKEN_URL`. **Note:** implementation uses GET with `application/x-www-form-urlencoded`
+        body (`UserName`, `Password`, `grant_type`) — align with FHPL spec / Postman.
+      operationId: fhplGenerateToken
+      requestBody:
+        content:
+          application/x-www-form-urlencoded:
+            schema:
+              type: object
+              properties:
+                UserName: { type: string }
+                Password: { type: string }
+                grant_type: { type: string }
+
+  /api/ClaimSubmission:
+    post:
+      tags: [FHPL]
+      summary: Claim submission
+      description: |
+        `{FHPL_BASE_URL}/api/ClaimSubmission` with Bearer token from token endpoint.
+      operationId: fhplClaimSubmission
+      security:
+        - FhplBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FhplClaimSubmissionBody'
+
+  /api/GetTPA_ClaimsDetails:
+    post:
+      tags: [FHPL]
+      summary: TPA claim details / MIS (status sync)
+      operationId: fhplGetTpaClaimsDetails
+      security:
+        - FhplBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                UserName: { type: string }
+                Password: { type: string }
+                PolicyNumber: { type: string }
+                Fromdate: { type: string, format: date }
+                Todate: { type: string, format: date }
+
+  /api/GetEcard:
+    post:
+      tags: [FHPL]
+      summary: Get e-card URL
+      operationId: fhplGetEcard
+      security:
+        - FhplBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                UserName: { type: string }
+                Password: { type: string }
+                PolicyNumber: { type: string }
+                EmployeeID: { type: string }
+
+  /api/GetEnrollmentDetailsPolicy:
+    post:
+      tags: [FHPL]
+      summary: Enrollment details for policy (paginated)
+      operationId: fhplGetEnrollmentDetailsPolicy
+      security:
+        - FhplBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                UserName: { type: string }
+                Password: { type: string }
+                PolicyNumber: { type: string }
+                StartIndex: { type: integer }
+                Range: { type: integer, example: 100 }
+
+  # --------------------------------------------------------------------------
+  # Health India TPA
+  # --------------------------------------------------------------------------
+  /JWT/GenerateJWTAuth:
+    post:
+      tags: [HealthIndia]
+      summary: Generate JWT (Basic auth)
+      description: |
+        `HEALTH_INDIA_TOKEN_URL`. HTTP Basic with `HEALTH_INDIA_USERNAME` / `HEALTH_INDIA_PASSWORD`.
+        Body is `{}`.
+      operationId: healthIndiaGenerateJWT
+      security:
+        - HealthIndiaTokenBasic: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+
+  /Intimation/GetClaimIntimation:
+    post:
+      tags: [HealthIndia]
+      summary: Claim intimation / reimbursement submission
+      description: >
+        HEALTH_INDIA_BASE_URL + /Intimation/GetClaimIntimation
+      operationId: healthIndiaClaimIntimation
+      security:
+        - HealthIndiaBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HealthIndiaClaimIntimationBody'
+
+  /Claims/GetClaims:
+    post:
+      tags: [HealthIndia]
+      summary: Get claim(s) by CCN
+      operationId: healthIndiaGetClaims
+      security:
+        - HealthIndiaBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                policY_NUMBER: { type: string }
+                CCN: { type: string }
+                CCN_EXT: { type: string }
+
+  /Member/GetMemberEcard:
+    post:
+      tags: [HealthIndia]
+      summary: Member e-card
+      operationId: healthIndiaGetMemberEcard
+      security:
+        - HealthIndiaBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                policY_NUMBER: { type: string }
+                employeE_CODE: { type: string }
+                membeR_ID: { type: string }
+
+  /Enrollment/GetEnrollmentData:
+    post:
+      tags: [HealthIndia]
+      summary: Bulk enrollment data (TPA ID pull)
+      operationId: healthIndiaGetEnrollmentData
+      security:
+        - HealthIndiaBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                policY_NUMBER: { type: string }
+
+  /ClaimsMIS/GetClaimsMIS:
+    post:
+      tags: [HealthIndia]
+      summary: Claims MIS / sync
+      operationId: healthIndiaGetClaimsMIS
+      security:
+        - HealthIndiaBearerAuth: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                policY_NUMBER: { type: string }
+
+components:
+  securitySchemes:
+    MediAssistUsername:
+      type: apiKey
+      in: header
+      name: Username
+      description: |
+        `.env`: `MEDI_ASSIST_API_USERNAME` — same value as `getenv('MEDI_ASSIST_API_USERNAME')` in PHP.
+
+    MediAssistPassword:
+      type: apiKey
+      in: header
+      name: Password
+      description: |
+        `.env`: `MEDI_ASSIST_API_PASSWORD` — same value as `getenv('MEDI_ASSIST_API_PASSWORD')`.
+
+    VidalSubscriptionKey:
+      type: apiKey
+      in: header
+      name: Ocp-Apim-Subscription-Key
+      description: |
+        `.env`: `VIDAL_API_SUBSCRIPTION_KEY` — used for partner-integration APIs (`VIDAL_API_BASE_URL`).
+
+    VidalIrSubscriptionKey:
+      type: apiKey
+      in: header
+      name: Ocp-Apim-Subscription-Key
+      description: |
+        `.env`: `VIDAL_SUBSCRIPTION_KEY` — used **only** for IR submission (`VIDAL_API_BASE_URL_IRSUBMISSION`).
+        Same header name as main Vidal key but different secret.
+
+    VidalWellnessSubscriptionKey:
+      type: apiKey
+      in: header
+      name: Ocp-Apim-Subscription-Key
+      description: |
+        `.env`: `VIDAL_WELLNESS_SUBSCRIPTION_KEY`. Wellness also uses `VIDAL_WELLNESS_BASE_URL`,
+        `VIDAL_WELLNESS_BASE64_KEY`, `VIDAL_WELLNESS_URL_IDENTIFIER`, `VIDAL_WELLNESS_SUB_PARTNER_ID`.
+
+    VoloBearerToken:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        Obtain token from `POST .../external/login` using body fields from `.env`:
+        `VOLO_API_EMAIL`, `VOLO_API_PASSWORD`, `VOLO_LOGGED_IN_PORTAL`.
+        Send the returned `accessToken` as the Bearer value (as required by the API, sometimes including a `Token ` prefix).
+
+    FhplBearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        Bearer `access_token` returned from `FHPL_TOKEN_URL` using form fields
+        `UserName`=`FHPL_USER_NAME`, `Password`=`FHPL_PASSWORD`, `grant_type`=`FHPL_GRANT_TYPE`.
+
+    HealthIndiaTokenBasic:
+      type: http
+      scheme: basic
+      description: |
+        For JWT generation call only. `.env`: `HEALTH_INDIA_USERNAME`, `HEALTH_INDIA_PASSWORD`
+        (HTTP Basic to `HEALTH_INDIA_TOKEN_URL`).
+
+    HealthIndiaBearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        Bearer JWT from the GenerateJWTAuth response (not a fixed `.env` value).
+        Use `result[0].access_token` after calling token URL with Basic credentials above.
+
+  schemas:
+    MediAssistSubmitClaimBody:
+      type: object
+      properties:
+        policyNo: { type: string }
+        memberId: { type: string }
+        mobileNo: { type: string }
+        emailId: { type: string }
+        claimDateOfAdmission: { type: string }
+        claimDateOfDischarge: { type: string }
+        hospName: { type: string }
+        hospAddress: { type: string }
+        reasonForHospitalization: { type: string }
+        disease: { type: string }
+        claimAmount: { type: number }
+        claimType:
+          type: string
+          example: HOSPITALIZATION
+        claimSubmissionAttachments:
+          type: object
+          properties:
+            fileName: { type: string }
+            filePath: { type: string, description: Public URL to PDF }
+
+    MediAssistClaimStatusBody:
+      type: object
+      properties:
+        policyNo: { type: string }
+        startDate: { type: string }
+        endDate: { type: string }
+        employeeCode: { type: string }
+        memberID: { type: string }
+        claimNo: { type: string }
+        claimRefNo: { type: string }
+
+    VidalClaimSubmitBody:
+      type: object
+      properties:
+        policyNo: { type: string }
+        dependentUniqueId: { type: string }
+        typeOfClaim: { type: string, example: Main hospitalization claim }
+        claimSubType: { type: string }
+        requestedAmount: { type: string }
+        ailmentType: { type: string, example: Non covid }
+        admissionDate: { type: string, description: dd-mm-yyyy }
+        dischargeDate: { type: string }
+        hospitalName: { type: string }
+        empanelmentNo: { type: number }
+        ailmentName: { type: string }
+        hospitalAddress: { type: string, nullable: true }
+        hospitalState: { type: string, nullable: true }
+        hospitalCity: { type: string, nullable: true }
+        hospitalPinCode: { type: string, nullable: true }
+        hospitalPhoneNo: { type: string, nullable: true }
+        fileId: { type: string }
+        bankDetails:
+          type: object
+          properties:
+            accountHolderName: { type: string, nullable: true }
+            accountType: { type: string, nullable: true }
+            accountNo: { type: string, nullable: true }
+            ifscCode: { type: string, nullable: true }
+
+    VoloIntimateClaimBody:
+      type: object
+      properties:
+        hospitalId: { type: string }
+        memberId: { type: string }
+        dateOfAdmission: { type: string, format: date }
+        dateOfDischarge: { type: string, format: date }
+        potentialClaimAmount: { type: number }
+        claimDocuments:
+          type: array
+          items:
+            type: object
+            properties:
+              documentName: { type: string }
+              documentType: { type: string, example: medical_report }
+              extension: { type: string, example: pdf }
+              url: { type: string, format: uri }
+        entityId: { type: string }
+        insurerPolicyNumber: { type: string }
+
+    FhplClaimSubmissionBody:
+      type: object
+      properties:
+        IssueID: { type: string }
+        Userid:
+          type: string
+          description: Same as `.env` `FHPL_USER_NAME` where the app sends Userid.
+        PolicyNo: { type: string }
+        UhidNo: { type: string }
+        ClaimID: { type: string }
+        DOA: { type: string, format: date }
+        DateofDischarge: { type: string, format: date, nullable: true }
+        ClaimedAmount: { type: number }
+        DocumentType: { type: integer, example: 20, description: Fresh claim }
+        PayeeName: { type: string }
+        HospitalName: { type: string }
+        MobileNo: { type: string }
+        Documents:
+          type: array
+          items:
+            type: object
+            properties:
+              documentName: { type: string }
+              documentCategory: { type: string, example: IRR }
+              filecontent: { type: string, description: Base64 PDF }
+
+    HealthIndiaClaimIntimationBody:
+      type: object
+      description: Field casing matches Health India API (mixedCase keys).
+      properties:
+        policY_NUMBER: { type: string }
+        employeE_CODE: { type: string }
+        membeR_ID: { type: string }
+        claiM_TYPE: { type: string, example: Reimbursement }
+        benefiT_TYPE: { type: string, enum: [IPD, OPD] }
+        claimeD_AMOUNT: { type: string }
+        datE_OF_ADMISSION: { type: string, format: date }
+        ailmenT_DESCRIPTION: { type: string }
+        hospitaL_CODE: { type: string }
+        hospitaL_NAME: { type: string }
+        hospitaL_ADDRESS: { type: string }
+        hospitaL_NUMBER: { type: string }
+        pdF_BYTES:
+          type: array
+          items: { type: string, description: Base64-encoded PDF }