{
    "openapi": "3.0.3",
    "info": {
        "title": "ProfClinic API",
        "description": "Reception API for Orfeas (Professional Clinic).\r\n\r\n**Authentication:** send `X-Api-Key` on every `/v1` request.\r\n**Formats:** JSON UTF-8 · dates `YYYY-MM-DD` · times `HH:MM` (24h).\r\n**Errors:** `{ \"error\": { \"code\", \"message\", \"details?\" }, \"request_id?\" }`.\r\n**Pagination:** `{ \"data\": [...], \"meta\": { \"page\", \"page_size\", \"total\", \"total_pages\" } }`.\r\n**Finance:** `/v1/finance/*` requires the owner API key.",
        "version": "1.0.0",
        "contact": {
            "name": "ProfClinic API",
            "email": "api@profclinic.local"
        },
        "license": {
            "name": "Proprietary"
        }
    },
    "servers": [
        {
            "url": "/",
            "description": "This server"
        }
    ],
    "tags": [
        {
            "name": "Health"
        },
        {
            "name": "Reference"
        },
        {
            "name": "Calendar"
        },
        {
            "name": "Appointments"
        },
        {
            "name": "Patients"
        },
        {
            "name": "Devices"
        },
        {
            "name": "Sync"
        },
        {
            "name": "Finance"
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key",
                "description": "Staff API key for reception endpoints. Use the owner key only for /v1/finance/*."
            },
            "IdempotencyKey": {
                "type": "apiKey",
                "in": "header",
                "name": "Idempotency-Key",
                "description": "Optional on POST /v1/appointments. Same key + same body returns the same appointment."
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "UNAUTHORIZED"
                            },
                            "message": {
                                "type": "string",
                                "example": "Invalid API key"
                            },
                            "details": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "field": {
                                            "type": "string"
                                        },
                                        "messages": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "request_id": {
                        "type": "string",
                        "format": "uuid"
                    }
                }
            },
            "Clinic": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "location": {
                        "type": "string"
                    },
                    "active": {
                        "type": "boolean"
                    },
                    "opening_hours": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "weekday": {
                                    "type": "string"
                                },
                                "from": {
                                    "type": "string",
                                    "example": "09:00"
                                },
                                "to": {
                                    "type": "string",
                                    "example": "21:00"
                                }
                            }
                        }
                    }
                }
            },
            "AppointmentType": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "duration": {
                        "type": "integer",
                        "description": "Minutes"
                    },
                    "clinic_id": {
                        "type": "integer",
                        "nullable": true
                    }
                }
            },
            "Staff": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "speciality": {
                        "type": "string"
                    }
                }
            },
            "Appointment": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "date": {
                        "type": "string",
                        "example": "2026-09-23"
                    },
                    "time": {
                        "type": "string",
                        "example": "10:00"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "confirmed",
                            "arrived",
                            "completed",
                            "no_show",
                            "cancelled"
                        ]
                    },
                    "clinic": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "type": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "staff": {
                        "type": "object",
                        "nullable": true,
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "name": {
                                "type": "string"
                            }
                        }
                    },
                    "notes": {
                        "type": "string"
                    },
                    "device_model": {
                        "type": "string"
                    },
                    "patient_id": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "modified_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "duration": {
                        "type": "integer"
                    }
                }
            },
            "Patient": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "first_name": {
                        "type": "string"
                    },
                    "last_name": {
                        "type": "string"
                    },
                    "phone": {
                        "type": "string"
                    },
                    "email": {
                        "type": "string"
                    },
                    "address": {
                        "type": "string"
                    },
                    "city": {
                        "type": "string"
                    },
                    "amka": {
                        "type": "string"
                    },
                    "source": {
                        "type": "string"
                    },
                    "notes": {
                        "type": "string"
                    },
                    "created_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "modified_at": {
                        "type": "string",
                        "nullable": true
                    },
                    "devices": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Device"
                        }
                    }
                }
            },
            "Device": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "patient_id": {
                        "type": "integer"
                    },
                    "brand": {
                        "type": "string"
                    },
                    "model": {
                        "type": "string"
                    },
                    "model_id": {
                        "type": "integer",
                        "nullable": true
                    },
                    "side": {
                        "type": "string",
                        "enum": [
                            "",
                            "L",
                            "R"
                        ]
                    },
                    "serial": {
                        "type": "string"
                    },
                    "fitting_date": {
                        "type": "string",
                        "nullable": true
                    },
                    "warranty_date": {
                        "type": "string",
                        "nullable": true
                    }
                }
            },
            "Slot": {
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string"
                    },
                    "time": {
                        "type": "string"
                    },
                    "staff_id": {
                        "type": "integer"
                    },
                    "staff_name": {
                        "type": "string"
                    },
                    "clinic_id": {
                        "type": "integer"
                    },
                    "duration": {
                        "type": "integer"
                    }
                }
            },
            "PageMeta": {
                "type": "object",
                "properties": {
                    "page": {
                        "type": "integer",
                        "example": 1
                    },
                    "page_size": {
                        "type": "integer",
                        "example": 50
                    },
                    "total": {
                        "type": "integer",
                        "example": 23
                    },
                    "total_pages": {
                        "type": "integer",
                        "example": 1
                    }
                }
            },
            "PagedAppointments": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Appointment"
                        }
                    },
                    "meta": {
                        "$ref": "#/components/schemas/PageMeta"
                    }
                }
            }
        },
        "parameters": {
            "Page": {
                "name": "page",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "default": 1,
                    "minimum": 1
                }
            },
            "PageSize": {
                "name": "page_size",
                "in": "query",
                "schema": {
                    "type": "integer",
                    "default": 50,
                    "minimum": 1,
                    "maximum": 100
                }
            },
            "DateFrom": {
                "name": "date_from",
                "in": "query",
                "schema": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-09-23"
                }
            },
            "DateTo": {
                "name": "date_to",
                "in": "query",
                "schema": {
                    "type": "string",
                    "format": "date",
                    "example": "2026-09-23"
                }
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "Missing or invalid API key",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Validation": {
                "description": "Validation error",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        }
    },
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "paths": {
        "/health": {
            "get": {
                "tags": [
                    "Health"
                ],
                "summary": "Public ping (no API key)",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/health": {
            "get": {
                "tags": [
                    "Health"
                ],
                "summary": "Health + database check",
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    }
                }
            }
        },
        "/v1/clinics": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List clinics",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Clinic"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/appointment-types": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List appointment types",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/AppointmentType"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/staff": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "List staff / audiologists",
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Staff"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/staff/{staffId}/hours": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "Working hours for one staff member",
                "parameters": [
                    {
                        "name": "staffId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 10
                        }
                    },
                    {
                        "$ref": "#/components/parameters/DateFrom"
                    },
                    {
                        "$ref": "#/components/parameters/DateTo"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/days-off": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "Clinic days off",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/DateFrom"
                    },
                    {
                        "$ref": "#/components/parameters/DateTo"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/sources": {
            "get": {
                "tags": [
                    "Reference"
                ],
                "summary": "Source / origin values (Προέλευση)",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/device-models": {
            "get": {
                "tags": [
                    "Devices"
                ],
                "summary": "Hearing-aid / device catalog",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PageSize"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/availability": {
            "get": {
                "tags": [
                    "Calendar"
                ],
                "summary": "Free time slots",
                "parameters": [
                    {
                        "name": "clinic_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 1
                        }
                    },
                    {
                        "name": "type_id",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 6
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "2026-09-23"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "2026-09-23"
                        }
                    },
                    {
                        "name": "staff_id",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "example": 10
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Slot"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v1/appointments": {
            "get": {
                "tags": [
                    "Appointments"
                ],
                "summary": "List / search appointments",
                "parameters": [
                    {
                        "name": "date",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "2026-09-23"
                        }
                    },
                    {
                        "name": "week_of",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/DateFrom"
                    },
                    {
                        "$ref": "#/components/parameters/DateTo"
                    },
                    {
                        "name": "changed_since",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "2026-09-01T00:00:00"
                        }
                    },
                    {
                        "name": "clinic_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "type_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "patient_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "staff_id",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "confirmed",
                                "arrived",
                                "completed",
                                "no_show",
                                "cancelled"
                            ]
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PageSize"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PagedAppointments"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Book an appointment",
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "schema": {
                            "type": "string"
                        },
                        "description": "Optional. Same key + same body = same appointment."
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "date",
                                    "time",
                                    "clinic_id",
                                    "type_id",
                                    "patient_id"
                                ],
                                "properties": {
                                    "date": {
                                        "type": "string",
                                        "example": "2026-09-24"
                                    },
                                    "time": {
                                        "type": "string",
                                        "example": "10:00"
                                    },
                                    "clinic_id": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "type_id": {
                                        "type": "integer",
                                        "example": 6
                                    },
                                    "patient_id": {
                                        "type": "integer",
                                        "example": 19
                                    },
                                    "staff_id": {
                                        "type": "integer",
                                        "example": 10
                                    },
                                    "notes": {
                                        "type": "string"
                                    },
                                    "device_model": {
                                        "type": "string"
                                    },
                                    "status": {
                                        "type": "string"
                                    },
                                    "override_hours": {
                                        "type": "boolean",
                                        "default": false
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    },
                    "409": {
                        "description": "SLOT_TAKEN / OUTSIDE_HOURS / IDEMPOTENCY_CONFLICT"
                    }
                }
            }
        },
        "/v1/appointments/{appointmentId}": {
            "get": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Get one appointment",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "404": {
                        "description": "Not found"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Reschedule / change details",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "date": {
                                        "type": "string"
                                    },
                                    "time": {
                                        "type": "string"
                                    },
                                    "clinic_id": {
                                        "type": "integer"
                                    },
                                    "type_id": {
                                        "type": "integer"
                                    },
                                    "staff_id": {
                                        "type": "integer",
                                        "nullable": true
                                    },
                                    "patient_id": {
                                        "type": "integer"
                                    },
                                    "notes": {
                                        "type": "string"
                                    },
                                    "device_model": {
                                        "type": "string"
                                    },
                                    "override_hours": {
                                        "type": "boolean"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/appointments/{appointmentId}/cancel": {
            "post": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Cancel appointment",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/appointments/{appointmentId}/status": {
            "post": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Change status",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "status"
                                ],
                                "properties": {
                                    "status": {
                                        "type": "string",
                                        "enum": [
                                            "confirmed",
                                            "arrived",
                                            "completed",
                                            "no_show",
                                            "cancelled"
                                        ]
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/appointments/{appointmentId}/notes": {
            "post": {
                "tags": [
                    "Appointments"
                ],
                "summary": "Add a note",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string",
                                        "example": "Patient called"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/patients": {
            "get": {
                "tags": [
                    "Patients"
                ],
                "summary": "Search patients",
                "parameters": [
                    {
                        "name": "phone",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "99745579"
                        }
                    },
                    {
                        "name": "name",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "example": "LEONTIOU"
                        }
                    },
                    {
                        "name": "amka",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "changed_since",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PageSize"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "tags": [
                    "Patients"
                ],
                "summary": "Create patient",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "first_name",
                                    "last_name",
                                    "phone"
                                ],
                                "properties": {
                                    "first_name": {
                                        "type": "string",
                                        "example": "Test"
                                    },
                                    "last_name": {
                                        "type": "string",
                                        "example": "Orfeas"
                                    },
                                    "phone": {
                                        "type": "string",
                                        "example": "990001112"
                                    },
                                    "email": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string",
                                        "example": "Nicosia"
                                    },
                                    "amka": {
                                        "type": "string"
                                    },
                                    "source": {
                                        "type": "string"
                                    },
                                    "notes": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/v1/patients/{patientId}": {
            "get": {
                "tags": [
                    "Patients"
                ],
                "summary": "Get patient card (includes devices)",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "example": 19
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "patch": {
                "tags": [
                    "Patients"
                ],
                "summary": "Update patient",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "first_name": {
                                        "type": "string"
                                    },
                                    "last_name": {
                                        "type": "string"
                                    },
                                    "phone": {
                                        "type": "string"
                                    },
                                    "email": {
                                        "type": "string"
                                    },
                                    "address": {
                                        "type": "string"
                                    },
                                    "city": {
                                        "type": "string"
                                    },
                                    "amka": {
                                        "type": "string"
                                    },
                                    "source": {
                                        "type": "string"
                                    },
                                    "notes": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/patients/{patientId}/notes": {
            "post": {
                "tags": [
                    "Patients"
                ],
                "summary": "Add patient note",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "text"
                                ],
                                "properties": {
                                    "text": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/patients/{patientId}/appointments": {
            "get": {
                "tags": [
                    "Patients"
                ],
                "summary": "Patient appointment history",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PageSize"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/patients/{patientId}/devices": {
            "get": {
                "tags": [
                    "Devices"
                ],
                "summary": "List patient devices",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "tags": [
                    "Devices"
                ],
                "summary": "Record a device for a patient",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "model": {
                                        "type": "string"
                                    },
                                    "model_id": {
                                        "type": "integer"
                                    },
                                    "brand": {
                                        "type": "string"
                                    },
                                    "side": {
                                        "type": "string",
                                        "enum": [
                                            "L",
                                            "R"
                                        ]
                                    },
                                    "serial": {
                                        "type": "string"
                                    },
                                    "fitting_date": {
                                        "type": "string"
                                    },
                                    "warranty_date": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/v1/changes": {
            "get": {
                "tags": [
                    "Sync"
                ],
                "summary": "Poll changes since a timestamp",
                "parameters": [
                    {
                        "name": "since",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string",
                            "example": "2026-09-01T00:00:00"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "maximum": 500
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/audit": {
            "get": {
                "tags": [
                    "Sync"
                ],
                "summary": "API change log",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PageSize"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/webhooks": {
            "get": {
                "tags": [
                    "Sync"
                ],
                "summary": "List webhook subscriptions",
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            },
            "post": {
                "tags": [
                    "Sync"
                ],
                "summary": "Register webhook URL",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "url"
                                ],
                                "properties": {
                                    "url": {
                                        "type": "string",
                                        "example": "https://example.com/orfeas"
                                    },
                                    "secret": {
                                        "type": "string"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created"
                    }
                }
            }
        },
        "/v1/webhooks/{webhookId}": {
            "delete": {
                "tags": [
                    "Sync"
                ],
                "summary": "Disable webhook",
                "parameters": [
                    {
                        "name": "webhookId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/v1/finance/appointments/{appointmentId}": {
            "get": {
                "tags": [
                    "Finance"
                ],
                "summary": "Financial fields for an appointment (owner key)",
                "parameters": [
                    {
                        "name": "appointmentId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "403": {
                        "description": "Staff key not allowed"
                    }
                }
            }
        },
        "/v1/finance/patients/{patientId}": {
            "get": {
                "tags": [
                    "Finance"
                ],
                "summary": "Financial fields for a patient (owner key)",
                "parameters": [
                    {
                        "name": "patientId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    },
                    "403": {
                        "description": "Staff key not allowed"
                    }
                }
            }
        }
    }
}