openapi: 3.0.3
info:
  title: Medical Tourism API
  description: |
    RESTful API for managing medical tourism cases, patient coordination, and healthcare provider interactions.
    
    ## Features
    - 🔐 JWT-based authentication
    - 📋 Comprehensive case management
    - 🔄 State machine workflow
    - 📎 Document upload support
    - 🔍 Public tracking system
    - ⚡ Rate limiting protection
    
    ## Authentication
    Most endpoints require JWT authentication. Include the token in the Authorization header:
    ```
    Authorization: Bearer <your_jwt_token>
    ```
    
    ## Rate Limits
    - **Login**: 5 attempts per 5 minutes
    - **Authenticated**: 100 requests per hour
    - **Public**: 30 requests per minute
    
  version: 1.0.0
  contact:
    name: Medical Tourism Support
    email: support@iranelaj.com
  license:
    name: Proprietary
    
servers:
  - url: http://localhost/iranelaj/public/api
    description: Development server
  - url: https://iranelaj.com/api
    description: Production server

tags:
  - name: Authentication
    description: User authentication and token management
  - name: Cases
    description: Medical case management
  - name: Public
    description: Public endpoints (no authentication required)
  - name: Documents
    description: File upload and document management
  - name: Statistics
    description: Analytics and reporting

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from /auth/login endpoint
      
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Error message"
        errors:
          type: object
          additionalProperties:
            type: string
        timestamp:
          type: string
          format: date-time
          
    LoginRequest:
      type: object
      required:
        - email
        - password
      properties:
        email:
          type: string
          format: email
          example: "admin@iranelaj.com"
        password:
          type: string
          format: password
          example: "admin123"
          
    LoginResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Login successful"
        data:
          type: object
          properties:
            token:
              type: string
              example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
            user:
              $ref: '#/components/schemas/User'
        timestamp:
          type: string
          format: date-time
          
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        email:
          type: string
          example: "admin@iranelaj.com"
        name:
          type: string
          example: "System Administrator"
        role:
          type: string
          example: "admin"
          
    Case:
      type: object
      properties:
        id:
          type: integer
          example: 123
        tracking_code:
          type: string
          example: "MTABC123XYZ9"
        patient_full_name:
          type: string
          example: "John Doe"
        patient_age:
          type: integer
          example: 45
        patient_gender:
          type: string
          enum: [Male, Female, Other]
        patient_country:
          type: string
          example: "United States"
        patient_whatsapp:
          type: string
          example: "+1234567890"
        patient_email:
          type: string
          format: email
          nullable: true
        medical_condition:
          type: string
          example: "Cardiac surgery consultation"
        preferred_treatment:
          type: string
          nullable: true
        current_state:
          type: string
          enum: 
            - submitted
            - under_review
            - documents_incomplete
            - medical_question
            - payment_request
            - quotation_provided
            - accepted
            - rejected
            - completed
            - cancelled
          example: "under_review"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          
    CreateCaseRequest:
      type: object
      required:
        - patient_full_name
        - patient_age
        - patient_gender
        - patient_country
        - patient_whatsapp
        - medical_condition
        - legal_acknowledgement_accepted
      properties:
        patient_full_name:
          type: string
          example: "John Doe"
        patient_age:
          type: integer
          minimum: 1
          maximum: 150
          example: 45
        patient_gender:
          type: string
          enum: [Male, Female, Other]
        patient_country:
          type: string
          example: "United States"
        patient_whatsapp:
          type: string
          example: "+1234567890"
        patient_email:
          type: string
          format: email
        medical_condition:
          type: string
          example: "Cardiac surgery consultation"
        preferred_treatment:
          type: string
        legal_acknowledgement_accepted:
          type: boolean
          example: true
          
    CreateCaseResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Case created successfully"
        data:
          type: object
          properties:
            case_id:
              type: integer
              example: 123
            tracking_code:
              type: string
              example: "MTABC123XYZ9"
        timestamp:
          type: string
          format: date-time
          
    CaseList:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
        data:
          type: object
          properties:
            cases:
              type: array
              items:
                $ref: '#/components/schemas/Case'
            pagination:
              $ref: '#/components/schemas/Pagination'
        timestamp:
          type: string
          format: date-time
          
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total:
          type: integer
          example: 150
        total_pages:
          type: integer
          example: 8
        has_more:
          type: boolean
          example: true
          
    Statistics:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            total_cases:
              type: integer
              example: 150
            by_state:
              type: object
              additionalProperties:
                type: integer
            by_country:
              type: array
              items:
                type: object
                properties:
                  country:
                    type: string
                  count:
                    type: integer
            this_month:
              type: integer
              
    DocumentUploadResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: "Document uploaded successfully"
        data:
          type: object
          properties:
            document_id:
              type: integer
              example: 45
            filename:
              type: string
              example: "abc123def456_1234567890.pdf"
        timestamp:
          type: string
          format: date-time

paths:
  /:
    get:
      tags:
        - Public
      summary: API Information
      description: Get API version and available endpoints
      responses:
        '200':
          description: API information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      name:
                        type: string
                      version:
                        type: string
                      endpoints:
                        type: object
                        
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User Login
      description: Authenticate user and receive JWT token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /auth/me:
    get:
      tags:
        - Authentication
      summary: Get Current User
      description: Get authenticated user information
      security:
        - BearerAuth: []
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /auth/refresh:
    post:
      tags:
        - Authentication
      summary: Refresh JWT Token
      description: Get a new JWT token using existing valid token
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Token refreshed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      token:
                        type: string
        '401':
          description: Invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
  /cases:
    get:
      tags:
        - Cases
      summary: List Cases
      description: Get paginated list of all cases with optional filters
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: state
          in: query
          schema:
            type: string
        - name: country
          in: query
          schema:
            type: string
        - name: search
          in: query
          schema:
            type: string
        - name: date_from
          in: query
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: List of cases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaseList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
    post:
      tags:
        - Cases
        - Public
      summary: Create Case
      description: Create a new medical tourism case (public endpoint)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCaseRequest'
      responses:
        '201':
          description: Case created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCaseResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /cases/{id}:
    get:
      tags:
        - Cases
      summary: Get Case
      description: Get detailed information about a specific case
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Case details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      case:
                        $ref: '#/components/schemas/Case'
                      documents:
                        type: array
                        items:
                          type: object
                      notes:
                        type: array
                        items:
                          type: object
                      state_history:
                        type: array
                        items:
                          type: object
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
    put:
      tags:
        - Cases
      summary: Update Case
      description: Update case information
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                patient_age:
                  type: integer
                patient_email:
                  type: string
                medical_condition:
                  type: string
      responses:
        '200':
          description: Case updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
    delete:
      tags:
        - Cases
      summary: Delete Case
      description: Delete a case (admin only)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Case deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '403':
          description: Forbidden - admin only
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
  /cases/tracking/{code}:
    get:
      tags:
        - Cases
        - Public
      summary: Track Case
      description: Get case information using tracking code (public endpoint)
      parameters:
        - name: code
          in: path
          required: true
          schema:
            type: string
          example: "MTABC123XYZ9"
      responses:
        '200':
          description: Case information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      case:
                        type: object
                      documents_count:
                        type: integer
                      state_history:
                        type: array
                        items:
                          type: object
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
  /cases/statistics:
    get:
      tags:
        - Statistics
      summary: Get Statistics
      description: Get case statistics and analytics
      security:
        - BearerAuth: []
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            default: 7
            maximum: 90
      responses:
        '200':
          description: Statistics data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Statistics'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /cases/{id}/state:
    put:
      tags:
        - Cases
      summary: Update Case State
      description: Transition case to a new state
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - new_state
              properties:
                new_state:
                  type: string
                  enum:
                    - under_review
                    - documents_incomplete
                    - medical_question
                    - payment_request
                    - quotation_provided
                    - accepted
                    - rejected
                    - completed
                    - cancelled
                notes:
                  type: string
      responses:
        '200':
          description: State updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          description: Invalid state transition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
  /cases/{id}/notes:
    post:
      tags:
        - Cases
      summary: Add Note
      description: Add a note to a case
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - note
              properties:
                note:
                  type: string
                  example: "Patient requested additional information"
      responses:
        '201':
          description: Note added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          
  /cases/{id}/documents:
    post:
      tags:
        - Documents
      summary: Upload Document
      description: Upload a document for a case
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - document
              properties:
                document:
                  type: string
                  format: binary
                  description: "Supported: PDF, JPEG, PNG, DOC, DOCX (max 10MB)"
                document_type:
                  type: string
                  enum:
                    - medical_report
                    - passport
                    - insurance
                    - other
                  default: other
      responses:
        '201':
          description: Document uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentUploadResponse'
        '400':
          description: Invalid request or file too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Case not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

security:
  - BearerAuth: []
