care-api/docs/openapi.yaml

openapi: 3.0.3
info:
  title: KiviCare REST API
  description: |
    REST API completa para integração com KiviCare healthcare management system.
    
    ## Autenticação
    Esta API usa JWT (JSON Web Tokens) para autenticação. Para acessar endpoints protegidos:
    1. Fazer login via `/auth/login` 
    2. Incluir token no header: `Authorization: Bearer <token>`
    3. Tokens expiram em 24h, usar `/auth/refresh` para renovar
    
    ## Estrutura de Resposta
    Todas as respostas seguem o formato padrão:
    ```json
    {
      "success": true,
      "data": {...},
      "message": "Operação realizada com sucesso",
      "timestamp": "2025-09-13T01:15:00Z"
    }
    ```
    
    ## Rate Limiting
    - 1000 requests por hora por IP
    - 100 requests por minuto por token JWT
    
    ## Links Úteis
    - [WordPress Site](https://example.com)
    - [KiviCare Plugin](https://wordpress.org/plugins/kivicare-clinic-management-system/)
    
  version: 1.0.0
  contact:
    name: Descomplicar® Dev Team
    email: dev@descomplicar.pt
    url: https://descomplicar.pt
  license:
    name: GPL v3
    url: https://www.gnu.org/licenses/gpl-3.0.en.html

servers:
  - url: https://example.com/wp-json/care/v1
    description: Production server
  - url: https://staging.example.com/wp-json/care/v1
    description: Staging server
  - url: http://localhost/wp-json/care/v1
    description: Development server

tags:
  - name: Authentication
    description: Login, logout and token management
  - name: Clinics
    description: Clinic management operations
  - name: Doctors
    description: Doctor/staff management  
  - name: Patients
    description: Patient management
  - name: Appointments
    description: Appointment scheduling and management
  - name: Encounters
    description: Medical encounters and consultations
  - name: Prescriptions
    description: Prescription management
  - name: Bills
    description: Billing and invoice management

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      
  schemas:
    Error:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Error description"
        error_code:
          type: string
          example: "INVALID_TOKEN"
        timestamp:
          type: string
          format: date-time
          
    AuthResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            token:
              type: string
              description: JWT access token
            refresh_token:
              type: string
              description: JWT refresh token
            expires_in:
              type: integer
              description: Token expiration in seconds
              example: 86400
            user:
              $ref: '#/components/schemas/User'
              
    User:
      type: object
      properties:
        id:
          type: integer
          example: 123
        username:
          type: string
          example: "doctor_smith"
        email:
          type: string
          format: email
          example: "doctor@clinic.com"
        role:
          type: string
          enum: [admin, doctor, receptionist, patient]
          example: "doctor"
        display_name:
          type: string
          example: "Dr. John Smith"
          
    Clinic:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "Central Medical Clinic"
        address:
          type: string
          example: "123 Main St, City, Country"
        phone:
          type: string
          example: "+1234567890"
        email:
          type: string
          format: email
          example: "info@clinic.com"
        status:
          type: string
          enum: [active, inactive]
          example: "active"
        created_at:
          type: string
          format: date-time
          
    Doctor:
      type: object
      properties:
        id:
          type: integer
          example: 456
        user_id:
          type: integer
          example: 123
        clinic_id:
          type: integer
          example: 1
        specialization:
          type: string
          example: "Cardiology"
        qualification:
          type: string
          example: "MD, FACC"
        experience_years:
          type: integer
          example: 15
        consultation_fee:
          type: number
          format: float
          example: 150.00
        status:
          type: string
          enum: [active, inactive]
          example: "active"
          
    Patient:
      type: object
      properties:
        id:
          type: integer
          example: 789
        first_name:
          type: string
          example: "John"
        last_name:
          type: string
          example: "Doe"
        email:
          type: string
          format: email
          example: "john.doe@email.com"
        phone:
          type: string
          example: "+1234567890"
        date_of_birth:
          type: string
          format: date
          example: "1985-06-15"
        gender:
          type: string
          enum: [male, female, other]
          example: "male"
        address:
          type: string
          example: "456 Oak St, City, Country"
        emergency_contact:
          type: string
          example: "Jane Doe - +0987654321"
        medical_history:
          type: string
          example: "Hypertension, Diabetes"
        allergies:
          type: string
          example: "Penicillin"
        created_at:
          type: string
          format: date-time
          
    Appointment:
      type: object
      properties:
        id:
          type: integer
          example: 1001
        clinic_id:
          type: integer
          example: 1
        doctor_id:
          type: integer
          example: 456
        patient_id:
          type: integer
          example: 789
        appointment_date:
          type: string
          format: date
          example: "2025-09-15"
        appointment_time:
          type: string
          format: time
          example: "10:30:00"
        duration:
          type: integer
          description: Duration in minutes
          example: 30
        status:
          type: string
          enum: [scheduled, confirmed, cancelled, completed, no_show]
          example: "scheduled"
        reason:
          type: string
          example: "Regular checkup"
        notes:
          type: string
          example: "Patient reports chest pain"
        created_at:
          type: string
          format: date-time

paths:
  # Authentication Endpoints
  /auth/login:
    post:
      tags:
        - Authentication
      summary: User login
      description: Authenticate user and receive JWT tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  example: "doctor_smith"
                password:
                  type: string
                  format: password
                  example: "secure_password"
                remember_me:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many login attempts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/refresh:
    post:
      tags:
        - Authentication
      summary: Refresh JWT token
      description: Get new access token using refresh token
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - refresh_token
              properties:
                refresh_token:
                  type: string
                  description: Valid refresh token
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/logout:
    post:
      tags:
        - Authentication
      summary: User logout
      description: Invalidate current JWT token
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Logout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Logout successful"
        '401':
          description: Token invalid or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # Clinic Endpoints
  /clinics:
    get:
      tags:
        - Clinics
      summary: List all clinics
      description: Retrieve a list of all clinics
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          description: Filter by clinic status
          schema:
            type: string
            enum: [active, inactive]
      responses:
        '200':
          description: List of clinics retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Clinic'
                  pagination:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 5
                      total_pages:
                        type: integer
                        example: 1
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    post:
      tags:
        - Clinics
      summary: Create new clinic
      description: Create a new clinic record
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - address
              properties:
                name:
                  type: string
                  example: "New Medical Center"
                address:
                  type: string
                  example: "789 Health Ave, Medical City"
                phone:
                  type: string
                  example: "+1234567890"
                email:
                  type: string
                  format: email
                  example: "info@newmedical.com"
      responses:
        '201':
          description: Clinic created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Clinic'
                  message:
                    type: string
                    example: "Clinic created successfully"
        '400':
          description: Bad request - validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /clinics/{id}:
    get:
      tags:
        - Clinics
      summary: Get clinic by ID
      description: Retrieve a specific clinic by ID
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Clinic ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: Clinic retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Clinic'
        '404':
          description: Clinic not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    put:
      tags:
        - Clinics
      summary: Update clinic
      description: Update an existing clinic
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Clinic ID
          schema:
            type: integer
            example: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: "Updated Medical Center"
                address:
                  type: string
                  example: "Updated address"
                phone:
                  type: string
                  example: "+1234567890"
                email:
                  type: string
                  format: email
                  example: "updated@email.com"
                status:
                  type: string
                  enum: [active, inactive]
                  example: "active"
      responses:
        '200':
          description: Clinic updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/Clinic'
                  message:
                    type: string
                    example: "Clinic updated successfully"
        '400':
          description: Bad request - validation errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Clinic not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

    delete:
      tags:
        - Clinics
      summary: Delete clinic
      description: Delete a clinic (soft delete)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Clinic ID
          schema:
            type: integer
            example: 1
      responses:
        '200':
          description: Clinic deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Clinic deleted successfully"
        '404':
          description: Clinic not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # Patient Endpoints (sample - expandir para outros endpoints)
  /patients:
    get:
      tags:
        - Patients
      summary: List all patients
      description: Retrieve a list of all patients with pagination and filtering
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
        - name: search
          in: query
          description: Search by name, email or phone
          schema:
            type: string
        - name: gender
          in: query
          schema:
            type: string
            enum: [male, female, other]
      responses:
        '200':
          description: Patients retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Patient'
                  pagination:
                    type: object

    post:
      tags:
        - Patients
      summary: Create new patient
      description: Register a new patient in the system
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - first_name
                - last_name
                - email
                - phone
              properties:
                first_name:
                  type: string
                  example: "John"
                last_name:
                  type: string
                  example: "Doe"
                email:
                  type: string
                  format: email
                  example: "john.doe@email.com"
                phone:
                  type: string
                  example: "+1234567890"
                date_of_birth:
                  type: string
                  format: date
                  example: "1985-06-15"
                gender:
                  type: string
                  enum: [male, female, other]
                address:
                  type: string
                emergency_contact:
                  type: string
                medical_history:
                  type: string
                allergies:
                  type: string
      responses:
        '201':
          description: Patient created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Patient'
                  message:
                    type: string

  # Appointments Endpoints (sample)
  /appointments:
    get:
      tags:
        - Appointments
      summary: List appointments
      description: Retrieve appointments with filtering options
      security:
        - BearerAuth: []
      parameters:
        - name: date_from
          in: query
          schema:
            type: string
            format: date
        - name: date_to
          in: query
          schema:
            type: string
            format: date
        - name: doctor_id
          in: query
          schema:
            type: integer
        - name: patient_id
          in: query
          schema:
            type: integer
        - name: status
          in: query
          schema:
            type: string
            enum: [scheduled, confirmed, cancelled, completed, no_show]
      responses:
        '200':
          description: Appointments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'

    post:
      tags:
        - Appointments
      summary: Schedule appointment
      description: Create a new appointment
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - doctor_id
                - patient_id
                - appointment_date
                - appointment_time
              properties:
                doctor_id:
                  type: integer
                  example: 456
                patient_id:
                  type: integer
                  example: 789
                appointment_date:
                  type: string
                  format: date
                  example: "2025-09-15"
                appointment_time:
                  type: string
                  format: time
                  example: "10:30:00"
                duration:
                  type: integer
                  default: 30
                reason:
                  type: string
                notes:
                  type: string
      responses:
        '201':
          description: Appointment scheduled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/Appointment'
                  message:
                    type: string

security:
  - BearerAuth: []