{
  "openapi": "3.0.3",
  "info": {
    "title": "HIS Server — Claims API Gateway",
    "description": "Hospital Information System (HIS) API Gateway and Claims Processing Server.\n\nConnects Hospital clients to the **Vigorus HCX Platform** with high-throughput **Redis Streams** and asynchronous **Rust Worker** processing.\n\n### Authentication:\n- **External Clients** (`/api/v1/*`): Provide `X-CLIENT-ID` and `X-CLIENT-SECRET` headers in the **Authorize** dialog.\n- **Internal Worker** (`/api/internal/*`): Provide `X-WORKER-SECRET` header.",
    "version": "1.0.0",
    "contact": {
      "name": "HIS Server Support",
      "email": "support@hospital.local"
    }
  },
  "servers": [
    {
      "url": "http://localhost:8000",
      "description": "Local Development Server"
    },
    {
      "url": "http://127.0.0.1:8000",
      "description": "Local IP"
    }
  ],
  "tags": [
    {
      "name": "Claims (Client API)",
      "description": "Endpoints accessible by external Hospital HIS clients (requires client credentials)"
    },
    {
      "name": "Internal Worker API",
      "description": "Endpoints dedicated to internal Rust background worker processing"
    },
    {
      "name": "System Health",
      "description": "Health checks & service monitoring"
    }
  ],
  "paths": {
    "/api/v1/claims": {
      "get": {
        "tags": ["Claims (Client API)"],
        "summary": "Fetch claims list",
        "description": "Retrieves claims from the Vigorus HCX platform. Results are cached in Redis for 30 seconds to optimize performance.",
        "operationId": "getClaims",
        "security": [
          {
            "ClientIdAuth": [],
            "ClientSecretAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Filter by claim status (e.g. pending, approved, rejected)",
            "required": false,
            "schema": {
              "type": "string",
              "example": "pending"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number for pagination",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 1,
              "example": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of records per page",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "example": 20
            }
          },
          {
            "name": "hospital_id",
            "in": "query",
            "description": "Filter by specific hospital identifier",
            "required": false,
            "schema": {
              "type": "string",
              "example": "HOSP_DEMO_01"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Claims retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetClaimsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid client credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "message": "Client credentials are required."
                }
              }
            }
          },
          "500": {
            "description": "Internal server or Vigorus provider error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/claims/{claimId}": {
      "put": {
        "tags": ["Claims (Client API)"],
        "summary": "Update claim data (Async Queue)",
        "description": "Submits medical clinical data and bundles for a claim. This endpoint does **not** block waiting on Vigorus. It validates the schema, queues the job into the Redis Stream `claims:update`, and immediately responds with `202 Accepted`.",
        "operationId": "updateClaim",
        "security": [
          {
            "ClientIdAuth": [],
            "ClientSecretAuth": []
          }
        ],
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the claim to update",
            "schema": {
              "type": "string",
              "example": "CLM-2026-001"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Clinical data and document/diagnostic bundle arrays",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateClaimRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Claim update queued successfully in Redis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueSuccessResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error (e.g. medicalData missing or invalid bundles)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid client credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/internal/claims/process": {
      "post": {
        "tags": ["Internal Worker API"],
        "summary": "Worker Callback: Process claim to Vigorus",
        "description": "Internal endpoint invoked by the **Rust background worker** when consuming jobs from Redis. Authenticates with `X-WORKER-SECRET` and forwards the claim payload to Vigorus with an active OAuth Bearer token.",
        "operationId": "processFromWorker",
        "security": [
          {
            "WorkerSecretAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkerProcessRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Claim updated successfully in Vigorus",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkerProcessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request (e.g. medicalData missing or invalid bundles)"
          },
          "401": {
            "description": "Unauthorized - Missing or invalid worker secret"
          },
          "500": {
            "description": "Vigorus API error or network failure"
          }
        }
      }
    },
    "/up": {
      "get": {
        "tags": ["System Health"],
        "summary": "Service health check",
        "description": "Probing endpoint for Docker / Kubernetes / uptime monitoring to confirm the Laravel application is running.",
        "operationId": "healthCheck",
        "responses": {
          "200": {
            "description": "Application is healthy"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ClientIdAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CLIENT-ID",
        "description": "Client Key identifier registered in the database (e.g. `3ad8a4ec-321b-404c-9774-7dbce6fc870a`)"
      },
      "ClientSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CLIENT-SECRET",
        "description": "Client Secret key registered in the database (e.g. `74985c7e4442161a5b590cc2ea948e3a86734cfd248784164786691555b02ae4`)"
      },
      "WorkerSecretAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-WORKER-SECRET",
        "description": "Worker Secret key configured in `.env` (`CLAIMS_WORKER_SECRET`)"
      }
    },
    "schemas": {
      "Diagnosis": {
        "type": "object",
        "required": ["code"],
        "properties": {
          "code": {
            "type": "string",
            "description": "ICD-10 or clinical diagnosis code",
            "example": "A09"
          },
          "name": {
            "type": "string",
            "description": "Diagnosis name or clinical description",
            "example": "Infectious gastroenteritis and colitis, unspecified"
          }
        }
      },
      "MedicalData": {
        "type": "object",
        "properties": {
          "registrationDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "example": "2026-10-15"
          },
          "admissionDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "example": "2026-10-16"
          },
          "dischargeDate": {
            "type": "string",
            "format": "date",
            "nullable": true,
            "example": "2026-10-18"
          },
          "dischargeType": {
            "type": "string",
            "nullable": true,
            "example": "normal"
          },
          "diagnosis": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Diagnosis"
            }
          }
        }
      },
      "BundleItem": {
        "type": "object",
        "required": ["bundle"],
        "properties": {
          "id": {
            "type": "string",
            "example": "BNDL-001"
          },
          "bundle": {
            "type": "object",
            "description": "FHIR / HCX compliant bundle resource object",
            "example": {
              "resourceType": "Bundle",
              "type": "collection"
            }
          }
        }
      },
      "UpdateClaimRequest": {
        "type": "object",
        "required": ["medicalData"],
        "properties": {
          "medicalData": {
            "$ref": "#/components/schemas/MedicalData"
          },
          "wellnessBundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BundleItem"
            },
            "example": []
          },
          "dischargeBundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BundleItem"
            },
            "example": []
          },
          "diagnosticBundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BundleItem"
            },
            "example": []
          },
          "documentBundles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BundleItem"
            },
            "example": []
          }
        }
      },
      "QueueSuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "integer",
            "example": 202
          },
          "message": {
            "type": "string",
            "example": "Claim update queued successfully."
          },
          "job_id": {
            "type": "string",
            "format": "uuid",
            "example": "e4b0c79e-4c07-4e6f-b258-202d0cf3f1e9"
          },
          "claim_id": {
            "type": "string",
            "example": "CLM-2026-001"
          }
        }
      },
      "GetClaimsResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "status": {
            "type": "integer",
            "example": 200
          },
          "data": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "example": [
              {
                "claimId": "CLM-2026-001",
                "patientId": "PAT-8812",
                "status": "pending",
                "amount": 25000.0,
                "created_at": "2026-10-18T10:00:00Z"
              }
            ]
          },
          "pagination": {
            "type": "object",
            "properties": {
              "current_page": { "type": "integer", "example": 1 },
              "total": { "type": "integer", "example": 10 },
              "per_page": { "type": "integer", "example": 20 }
            }
          },
          "message": {
            "type": "string",
            "example": "Claims retrieved successfully"
          }
        }
      },
      "WorkerProcessRequest": {
        "type": "object",
        "required": ["claim_id", "payload"],
        "properties": {
          "claim_id": {
            "type": "string",
            "example": "CLM-2026-001"
          },
          "payload": {
            "$ref": "#/components/schemas/UpdateClaimRequest"
          }
        }
      },
      "WorkerProcessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "status": { "type": "integer", "example": 200 },
          "message": { "type": "string", "example": "Claim updated successfully in Vigorus." },
          "claim_id": { "type": "string", "example": "CLM-2026-001" },
          "data": { "type": "object" }
        }
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "message": { "type": "string", "example": "medicalData is required." },
          "errors": {
            "type": "object",
            "example": {
              "medicalData": ["medicalData is required."]
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "status": { "type": "integer", "example": 401 },
          "message": { "type": "string", "example": "Client credentials are required." }
        }
      }
    }
  }
}