{ "version": "1.0", "modules": [ { "name": "Departments", "prefix": "/departments", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Department", "description": "Creates a new department record. Returns 409 if the department name already exists.", "request_body": { "schema_name": "DepartmentCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Departments", "description": "Returns a paginated list of departments. Supports optional search filter on department name.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedDepartmentResponse", "fields": [ { "name": "items", "type": "List[DepartmentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{department_id}", "summary": "Get Department", "description": "Retrieves a single department by ID. Returns 404 if the department does not exist.", "path_params": [ { "name": "department_id", "type": "str" } ], "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{department_id}", "summary": "Update Department", "description": "Updates an existing department. Only provided fields are updated. Returns 404 if the department does not exist, 409 if the new name conflicts with an existing department.", "path_params": [ { "name": "department_id", "type": "str" } ], "request_body": { "schema_name": "DepartmentUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "DepartmentResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{department_id}", "summary": "Delete Department", "description": "Deletes a department by ID. Returns 404 if the department does not exist, 409 if the department is referenced by other records (users, appointments, services).", "path_params": [ { "name": "department_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Insurance Providers", "prefix": "/insurance-providers", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Insurance Provider", "description": "Creates a new insurance provider record. Returns 409 if an insurance provider with the same name already exists.", "request_body": { "schema_name": "InsuranceproviderCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "coverage_policy", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "InsuranceproviderResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "coverage_policy", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Insurance Providers", "description": "Returns a paginated list of insurance providers. Supports optional search filter on name, contact person, and email fields.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "InsuranceproviderListResponse", "fields": [ { "name": "items", "type": "list[InsuranceproviderResponse]", "required": true }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{entity_id}", "summary": "Get Insurance Provider by ID", "description": "Returns details of a single insurance provider by ID. Returns 404 if the insurance provider does not exist.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "InsuranceproviderResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "coverage_policy", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{entity_id}", "summary": "Update Insurance Provider", "description": "Updates an existing insurance provider record. Returns 404 if the insurance provider does not exist. Returns 409 if the updated name conflicts with another provider.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "InsuranceproviderUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "coverage_policy", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "InsuranceproviderResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "contact_person", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "coverage_policy", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{entity_id}", "summary": "Delete Insurance Provider", "description": "Deletes an insurance provider record. Returns 404 if the insurance provider does not exist. Returns 409 if the provider is referenced by existing patients.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Users", "prefix": "/users", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create User", "description": "Creates a new user account with hashed password. Validates department existence if provided. Returns 409 if email already exists.", "request_body": { "schema_name": "UserCreate", "fields": [ { "name": "email", "type": "EmailStr", "required": true }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "password", "type": "str", "required": false } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Users", "description": "Returns a paginated list of users. Supports optional filters for role, active status, department, and search term (searches first name, last name, and email).", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "role", "type": "UserRole", "required": false }, { "name": "is_active", "type": "bool", "required": false }, { "name": "department_id", "type": "str", "required": false }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedResponse[UserResponse]", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}", "summary": "Get User", "description": "Returns a single user by ID. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{user_id}/details", "summary": "Get User Details", "description": "Returns user information with department name pre-loaded. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "response": { "schema_name": "UserDetailsResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "department_name", "type": "str", "required": false, "nullable": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{user_id}", "summary": "Update User", "description": "Updates user fields. Only provided fields are updated. Validates email uniqueness and department existence. Returns 404 if user not found.", "path_params": [ { "name": "user_id", "type": "str" } ], "request_body": { "schema_name": "UserUpdate", "fields": [ { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "role", "type": "UserRole", "required": false, "nullable": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "UserResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "email", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "role", "type": "UserRole", "required": true, "enum_values": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ] }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{user_id}", "summary": "Delete User", "description": "Deletes a user account. Returns 404 if user not found. Returns 409 if user is referenced by other records (appointments, consultations, etc).", "path_params": [ { "name": "user_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Patients", "prefix": "/patients", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Patient", "description": "Creates a new patient record and automatically creates an associated medical record. Returns 409 if patient_number already exists. Returns 400 if insurance provider does not exist.", "request_body": { "schema_name": "PatientCreate", "fields": [ { "name": "patient_number", "type": "str", "required": false }, { "name": "first_name", "type": "str", "required": false }, { "name": "last_name", "type": "str", "required": false }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": false }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "str", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PatientResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_number", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "StrId", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Patients", "description": "Returns a paginated list of patients. Supports optional search filter on first_name, last_name, patient_number, and email fields.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "search", "type": "str", "required": false } ], "response": { "schema_name": "PaginatedPatientResponse", "fields": [ { "name": "items", "type": "List[PatientResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_number", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "StrId", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{patient_id}", "summary": "Get Patient", "description": "Returns a single patient record by ID. Returns 404 if patient not found.", "path_params": [ { "name": "patient_id", "type": "str" } ], "response": { "schema_name": "PatientResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_number", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "StrId", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{patient_id}/details", "summary": "Get Patient Details", "description": "Returns detailed patient record with insurance provider, medical record, and appointments including doctor and department information. Returns 404 if patient not found.", "path_params": [ { "name": "patient_id", "type": "str" } ], "response": { "schema_name": "PatientDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_number", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "StrId", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "insurance_provider", "type": "InsuranceProviderSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] }, { "name": "medical_record", "type": "MedicalrecordResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "appointments", "type": "List[AppointmentSummary]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_date", "type": "date", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{patient_id}", "summary": "Update Patient", "description": "Updates patient record fields. Only provided fields are updated. Returns 404 if patient not found. Returns 409 if patient_number already exists. Returns 400 if insurance provider does not exist.", "path_params": [ { "name": "patient_id", "type": "str" } ], "request_body": { "schema_name": "PatientUpdate", "fields": [ { "name": "patient_number", "type": "str", "required": false, "nullable": true }, { "name": "first_name", "type": "str", "required": false, "nullable": true }, { "name": "last_name", "type": "str", "required": false, "nullable": true }, { "name": "date_of_birth", "type": "date", "required": false, "nullable": true }, { "name": "gender", "type": "str", "required": false, "nullable": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "EmailStr", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "str", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PatientResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_number", "type": "str", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true }, { "name": "gender", "type": "str", "required": true }, { "name": "phone", "type": "str", "required": false, "nullable": true }, { "name": "email", "type": "str", "required": false, "nullable": true }, { "name": "address", "type": "str", "required": false, "nullable": true }, { "name": "city", "type": "str", "required": false, "nullable": true }, { "name": "state", "type": "str", "required": false, "nullable": true }, { "name": "postal_code", "type": "str", "required": false, "nullable": true }, { "name": "country", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_name", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_phone", "type": "str", "required": false, "nullable": true }, { "name": "emergency_contact_relationship", "type": "str", "required": false, "nullable": true }, { "name": "insurance_provider_id", "type": "StrId", "required": false, "nullable": true }, { "name": "insurance_policy_number", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{patient_id}", "summary": "Delete Patient", "description": "Deletes a patient record and cascades to all associated records (medical record, appointments, consultations, etc.). Returns 404 if patient not found. Returns 409 if patient has records that prevent deletion.", "path_params": [ { "name": "patient_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/medical-records", "summary": "Create Medical Record", "description": "Creates a medical record for a patient. Returns 409 if medical record already exists for this patient. Returns 400 if patient does not exist.", "request_body": { "schema_name": "MedicalrecordCreate", "fields": [ { "name": "patient_id", "type": "str", "required": false }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "MedicalrecordResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/medical-records", "summary": "List Medical Records", "description": "Returns a paginated list of medical records. Supports optional filter by patient_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false } ], "response": { "schema_name": "list", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/medical-records/{record_id}", "summary": "Get Medical Record", "description": "Returns a single medical record by ID. Returns 404 if medical record not found.", "path_params": [ { "name": "record_id", "type": "str" } ], "response": { "schema_name": "MedicalrecordResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/medical-records/{record_id}", "summary": "Update Medical Record", "description": "Updates medical record fields. Only provided fields are updated. Returns 404 if medical record not found. Returns 400 if patient does not exist.", "path_params": [ { "name": "record_id", "type": "str" } ], "request_body": { "schema_name": "MedicalrecordUpdate", "fields": [ { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "MedicalrecordResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "blood_type", "type": "str", "required": false, "nullable": true }, { "name": "allergies", "type": "str", "required": false, "nullable": true }, { "name": "chronic_conditions", "type": "str", "required": false, "nullable": true }, { "name": "family_medical_history", "type": "str", "required": false, "nullable": true }, { "name": "surgical_history", "type": "str", "required": false, "nullable": true }, { "name": "immunization_history", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/medical-records/{record_id}", "summary": "Delete Medical Record", "description": "Deletes a medical record. Returns 404 if medical record not found. Returns 409 if medical record has references that prevent deletion.", "path_params": [ { "name": "record_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Appointments", "prefix": "/appointments", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Appointment", "description": "Creates a new appointment for a patient with a doctor. Validates patient, doctor, and department references. Returns 404 if any reference is invalid.", "request_body": { "schema_name": "AppointmentCreate", "fields": [ { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": false }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Appointments", "description": "Returns a paginated list of appointments. Supports filtering by patient_id, doctor_id, department_id, status, appointment_type, and appointment_date.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "department_id", "type": "str", "required": false }, { "name": "status", "type": "AppointmentStatus", "required": false }, { "name": "appointment_type", "type": "AppointmentType", "required": false }, { "name": "appointment_date", "type": "date", "required": false } ], "response": { "schema_name": "PaginatedAppointmentResponse", "fields": [ { "name": "items", "type": "List[AppointmentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{appointment_id}", "summary": "Get Appointment", "description": "Retrieves a single appointment by ID. Returns 404 if the appointment does not exist.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/{appointment_id}", "summary": "Update Appointment", "description": "Updates an existing appointment. Only provided fields are updated. Validates patient, doctor, and department references. Returns 404 if the appointment or any reference does not exist.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "request_body": { "schema_name": "AppointmentUpdate", "fields": [ { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "doctor_id", "type": "str", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": false, "nullable": true }, { "name": "appointment_time", "type": "time", "required": false, "nullable": true }, { "name": "duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "appointment_type", "type": "AppointmentType", "required": false, "nullable": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": false, "nullable": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{appointment_id}", "summary": "Delete Appointment", "description": "Deletes an appointment. Returns 404 if the appointment does not exist. Returns 409 if the appointment is referenced by other records.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "status_code": 200 }, { "method": "GET", "path": "/{appointment_id}/details", "summary": "Get Appointment Details", "description": "Retrieves detailed appointment information with eager-loaded patient, doctor, and department. Returns 404 if the appointment does not exist.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "response": { "schema_name": "AppointmentDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "patient", "type": "PatientSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true } ] }, { "name": "doctor", "type": "DoctorSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "department", "type": "DepartmentSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{appointment_id}/check-in", "summary": "Check In Appointment", "description": "Updates the appointment status to checked_in. Only scheduled or confirmed appointments can be checked in. Returns 400 if the status transition is invalid.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{appointment_id}/cancel", "summary": "Cancel Appointment", "description": "Updates the appointment status to cancelled. Cannot cancel an appointment that is already completed, cancelled, or marked no show. Returns 400 if the status transition is invalid.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/{appointment_id}/complete", "summary": "Complete Appointment", "description": "Updates the appointment status to completed. Only checked-in or in-progress appointments can be completed. Returns 400 if the status transition is invalid.", "path_params": [ { "name": "appointment_id", "type": "str" } ], "response": { "schema_name": "AppointmentResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "department_id", "type": "StrId", "required": false, "nullable": true }, { "name": "appointment_date", "type": "date", "required": true }, { "name": "appointment_time", "type": "time", "required": true }, { "name": "duration_minutes", "type": "int", "required": true }, { "name": "appointment_type", "type": "AppointmentType", "required": true, "enum_values": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ] }, { "name": "status", "type": "AppointmentStatus", "required": true, "enum_values": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ] }, { "name": "reason", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] }, { "name": "Reports", "prefix": "/reports", "endpoints": [ { "method": "POST", "path": "/", "summary": "Create Report", "description": "Creates a new report record. Validates that the user who generated the report exists. Returns 400 if the user does not exist.", "request_body": { "schema_name": "ReportCreate", "fields": [ { "name": "report_name", "type": "str", "required": false }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "str", "required": false }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "report_name", "type": "str", "required": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/", "summary": "List Reports", "description": "Returns a paginated list of reports. Supports optional filters on status, report_type, generated_by_user_id, start_date, and end_date.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "status_filter", "type": "ReportStatus", "required": false }, { "name": "report_type_filter", "type": "ReportType", "required": false }, { "name": "generated_by_user_id", "type": "str", "required": false }, { "name": "start_date", "type": "date", "required": false }, { "name": "end_date", "type": "date", "required": false } ], "response": { "schema_name": "PaginatedReportResponse", "fields": [ { "name": "items", "type": "list[ReportResponse]", "required": true }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{report_id}", "summary": "Get Report By ID", "description": "Retrieves a single report by its unique identifier. Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "report_name", "type": "str", "required": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{report_id}/details", "summary": "Get Report Details", "description": "Retrieves a report with related user information (generated_by). Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "response": { "schema_name": "ReportDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "report_name", "type": "str", "required": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "generated_by", "type": "UserSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "email", "type": "str", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PATCH", "path": "/{report_id}", "summary": "Update Report", "description": "Updates an existing report record. Only provided fields are updated. Validates that the user exists if generated_by_user_id is updated. Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "request_body": { "schema_name": "ReportUpdate", "fields": [ { "name": "report_name", "type": "str", "required": false, "nullable": true }, { "name": "report_type", "type": "ReportType", "required": false, "nullable": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": false, "nullable": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true } ] }, "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "report_name", "type": "str", "required": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/{report_id}", "summary": "Delete Report", "description": "Deletes a report record. Returns 404 if the report does not exist. Returns 409 if the report is referenced by other records.", "path_params": [ { "name": "report_id", "type": "str" } ], "status_code": 204 }, { "method": "POST", "path": "/{report_id}/generate", "summary": "Generate Report", "description": "Triggers report generation for a report. Updates the report status to generating and then completed. Returns 400 if the report has already been generated. Returns 404 if the report does not exist.", "path_params": [ { "name": "report_id", "type": "str" } ], "response": { "schema_name": "ReportResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "report_name", "type": "str", "required": true }, { "name": "report_type", "type": "ReportType", "required": true, "enum_values": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ] }, { "name": "generated_by_user_id", "type": "StrId", "required": true }, { "name": "start_date", "type": "date", "required": false, "nullable": true }, { "name": "end_date", "type": "date", "required": false, "nullable": true }, { "name": "parameters", "type": "Dict[str, Any]", "required": false, "nullable": true }, { "name": "file_path", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "ReportStatus", "required": true, "enum_values": [ "GENERATING", "COMPLETED", "FAILED" ] }, { "name": "generated_at", "type": "datetime", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/{report_id}/download", "summary": "Download Report", "description": "Downloads the generated report file. Returns 404 if the report does not exist or the file is not available.", "path_params": [ { "name": "report_id", "type": "str" } ], "status_code": 200 } ] }, { "name": "Billing", "prefix": "/billing", "endpoints": [ { "method": "POST", "path": "/services", "summary": "Create Service", "description": "Creates a new service in the catalog. Validates that the referenced department exists if department_id is provided. Returns 409 if service already exists.", "request_body": { "schema_name": "ServiceCreate", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true } ] }, "response": { "schema_name": "ServiceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/services/{entity_id}", "summary": "Get Service", "description": "Retrieves a single service by ID. Returns 404 if service not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "ServiceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/services", "summary": "List Services", "description": "Returns a paginated list of services. Supports optional filtering by is_active, service_type, and department_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "is_active", "type": "bool", "required": false }, { "name": "service_type", "type": "ServiceType", "required": false }, { "name": "department_id", "type": "str", "required": false } ], "response": { "schema_name": "ServiceListResponse", "fields": [ { "name": "items", "type": "List[ServiceResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/services/{entity_id}", "summary": "Update Service", "description": "Updates an existing service. Only provided fields are updated. Returns 404 if service not found, 409 if unique constraint violated.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "ServiceUpdate", "fields": [ { "name": "name", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": false, "nullable": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true } ] }, "response": { "schema_name": "ServiceResponse", "fields": [ { "name": "name", "type": "str", "required": false }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "service_type", "type": "ServiceType", "required": true, "enum_values": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ] }, { "name": "default_price", "type": "Decimal", "required": false }, { "name": "default_duration_minutes", "type": "int", "required": false, "nullable": true }, { "name": "department_id", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/services/{entity_id}", "summary": "Delete Service", "description": "Deletes a service. Returns 404 if service not found, 409 if service is referenced by invoice line items.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/invoices", "summary": "Create Invoice", "description": "Creates a new invoice record. Validates that referenced patient and appointment exist. Returns 409 if invoice_number already exists.", "request_body": { "schema_name": "InvoiceCreate", "fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "InvoiceResponse", "fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/invoices/{entity_id}", "summary": "Get Invoice", "description": "Retrieves a single invoice by ID. Returns 404 if invoice not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "InvoiceResponse", "fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/invoices/{entity_id}/details", "summary": "Get Invoice Details", "description": "Retrieves full invoice details including patient information, appointment details, line items with services, and all payments.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "InvoiceDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "invoice_number", "type": "str", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": true }, { "name": "tax_amount", "type": "Decimal", "required": true }, { "name": "discount_amount", "type": "Decimal", "required": true }, { "name": "total_amount", "type": "Decimal", "required": true }, { "name": "amount_paid", "type": "Decimal", "required": true }, { "name": "balance_due", "type": "Decimal", "required": true }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "StrId", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "patient", "type": "PatientSummaryResponse", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "patient_number", "type": "str", "required": true } ] }, { "name": "appointment", "type": "AppointmentSummaryResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_date", "type": "date", "required": true } ] }, { "name": "line_items", "type": "List[InvoiceLineItemDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "service_id", "type": "StrId", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": true }, { "name": "unit_price", "type": "Decimal", "required": true }, { "name": "line_total", "type": "Decimal", "required": true }, { "name": "service", "type": "ServiceDetailResponse", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "name", "type": "str", "required": true } ] } ] }, { "name": "payments", "type": "List[PaymentDetailResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "amount", "type": "Decimal", "required": true }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "payment_date", "type": "datetime", "required": true } ] } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/invoices", "summary": "List Invoices", "description": "Returns a paginated list of invoices. Supports optional filtering by status, patient_id, and appointment_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "status_filter", "type": "InvoiceStatus", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false } ], "response": { "schema_name": "InvoiceListResponse", "fields": [ { "name": "items", "type": "List[InvoiceResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/invoices/{entity_id}", "summary": "Update Invoice", "description": "Updates an existing invoice. Only provided fields are updated. Returns 404 if invoice not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "InvoiceUpdate", "fields": [ { "name": "invoice_number", "type": "str", "required": false, "nullable": true }, { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": false, "nullable": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false, "nullable": true }, { "name": "tax_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "discount_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "total_amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "amount_paid", "type": "Decimal", "required": false, "nullable": true }, { "name": "balance_due", "type": "Decimal", "required": false, "nullable": true }, { "name": "status", "type": "InvoiceStatus", "required": false, "nullable": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "InvoiceResponse", "fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/invoices/{entity_id}", "summary": "Delete Invoice", "description": "Deletes an invoice. Returns 404 if invoice not found, 409 if invoice is referenced by payments.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/invoices/{entity_id}/issue", "summary": "Issue Invoice", "description": "Changes invoice status from draft to issued. Only draft invoices can be issued. Returns 400 if invoice is not in draft status.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "IssueInvoiceRequest", "fields": [] }, "response": { "schema_name": "InvoiceResponse", "fields": [ { "name": "invoice_number", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "invoice_date", "type": "date", "required": true }, { "name": "due_date", "type": "date", "required": false, "nullable": true }, { "name": "subtotal", "type": "Decimal", "required": false }, { "name": "tax_amount", "type": "Decimal", "required": false }, { "name": "discount_amount", "type": "Decimal", "required": false }, { "name": "total_amount", "type": "Decimal", "required": false }, { "name": "amount_paid", "type": "Decimal", "required": false }, { "name": "balance_due", "type": "Decimal", "required": false }, { "name": "status", "type": "InvoiceStatus", "required": true, "enum_values": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/invoice-line-items", "summary": "Create Invoice Line Item", "description": "Creates a new line item for an invoice. Validates that referenced invoice and service exist.", "request_body": { "schema_name": "InvoicelineitemCreate", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "unit_price", "type": "Decimal", "required": false }, { "name": "line_total", "type": "Decimal", "required": false } ] }, "response": { "schema_name": "InvoicelineitemResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "unit_price", "type": "Decimal", "required": false }, { "name": "line_total", "type": "Decimal", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/invoice-line-items/{entity_id}", "summary": "Get Invoice Line Item", "description": "Retrieves a single invoice line item by ID. Returns 404 if line item not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "InvoicelineitemResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "unit_price", "type": "Decimal", "required": false }, { "name": "line_total", "type": "Decimal", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/invoice-line-items", "summary": "List Invoice Line Items", "description": "Returns a paginated list of invoice line items. Supports optional filtering by invoice_id and service_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false } ], "response": { "schema_name": "InvoicelineitemListResponse", "fields": [ { "name": "items", "type": "List[InvoicelineitemResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "unit_price", "type": "Decimal", "required": false }, { "name": "line_total", "type": "Decimal", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/invoice-line-items/{entity_id}", "summary": "Update Invoice Line Item", "description": "Updates an existing invoice line item. Only provided fields are updated. Returns 404 if line item not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "InvoicelineitemUpdate", "fields": [ { "name": "invoice_id", "type": "str", "required": false, "nullable": true }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false, "nullable": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "unit_price", "type": "Decimal", "required": false, "nullable": true }, { "name": "line_total", "type": "Decimal", "required": false, "nullable": true } ] }, "response": { "schema_name": "InvoicelineitemResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "service_id", "type": "str", "required": false, "nullable": true }, { "name": "description", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false }, { "name": "unit_price", "type": "Decimal", "required": false }, { "name": "line_total", "type": "Decimal", "required": false }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/invoice-line-items/{entity_id}", "summary": "Delete Invoice Line Item", "description": "Deletes an invoice line item. Returns 404 if line item not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/payments", "summary": "Create Payment", "description": "Creates a new payment record. Validates that referenced invoice and patient exist and that payment amount does not exceed balance due.", "request_body": { "schema_name": "PaymentCreate", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/payments/{entity_id}", "summary": "Get Payment", "description": "Retrieves a single payment by ID. Returns 404 if payment not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/payments", "summary": "List Payments", "description": "Returns a paginated list of payments. Supports optional filtering by invoice_id, patient_id, and payment_method.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": false } ], "response": { "schema_name": "PaymentListResponse", "fields": [ { "name": "items", "type": "List[PaymentResponse]", "required": true, "is_list": true, "item_fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ] }, { "name": "total", "type": "int", "required": true }, { "name": "limit", "type": "int", "required": true }, { "name": "offset", "type": "int", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/payments/{entity_id}", "summary": "Update Payment", "description": "Updates an existing payment. Only provided fields are updated. Returns 404 if payment not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "PaymentUpdate", "fields": [ { "name": "invoice_id", "type": "str", "required": false, "nullable": true }, { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "payment_date", "type": "datetime", "required": false, "nullable": true }, { "name": "amount", "type": "Decimal", "required": false, "nullable": true }, { "name": "payment_method", "type": "PaymentMethod", "required": false, "nullable": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/payments/{entity_id}", "summary": "Delete Payment", "description": "Deletes a payment. Returns 404 if payment not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/payments/process", "summary": "Process Payment", "description": "Processes a payment and automatically updates the invoice status and balance. Validates payment amount does not exceed balance due. Updates invoice status to partially_paid or paid based on remaining balance.", "request_body": { "schema_name": "ProcessPaymentRequest", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "PaymentResponse", "fields": [ { "name": "invoice_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "payment_date", "type": "datetime", "required": true }, { "name": "amount", "type": "Decimal", "required": false }, { "name": "payment_method", "type": "PaymentMethod", "required": true, "enum_values": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ] }, { "name": "transaction_reference", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "processed_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "id", "type": "StrId", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 } ] }, { "name": "Clinical", "prefix": "/clinical", "endpoints": [ { "method": "POST", "path": "/vital-signs", "summary": "Create Vital Sign", "description": "Records a new set of vital signs for a patient. Validates blood pressure consistency and temperature range. Returns 404 if patient or recording user does not exist.", "request_body": { "schema_name": "VitalsignCreate", "fields": [ { "name": "patient_id", "type": "str", "required": false }, { "name": "recorded_by_user_id", "type": "str", "required": false }, { "name": "recorded_at", "type": "datetime", "required": true }, { "name": "systolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "diastolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "pulse_rate", "type": "int", "required": false, "nullable": true }, { "name": "temperature_celsius", "type": "Decimal", "required": false, "nullable": true }, { "name": "respiratory_rate", "type": "int", "required": false, "nullable": true }, { "name": "weight_kg", "type": "Decimal", "required": false, "nullable": true }, { "name": "height_cm", "type": "Decimal", "required": false, "nullable": true }, { "name": "oxygen_saturation", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "VitalsignResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "recorded_by_user_id", "type": "StrId", "required": true }, { "name": "recorded_at", "type": "datetime", "required": true }, { "name": "systolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "diastolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "pulse_rate", "type": "int", "required": false, "nullable": true }, { "name": "temperature_celsius", "type": "Decimal", "required": false, "nullable": true }, { "name": "respiratory_rate", "type": "int", "required": false, "nullable": true }, { "name": "weight_kg", "type": "Decimal", "required": false, "nullable": true }, { "name": "height_cm", "type": "Decimal", "required": false, "nullable": true }, { "name": "oxygen_saturation", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/vital-signs", "summary": "List Vital Signs", "description": "Returns a paginated list of vital sign records. Supports optional filtering by patient_id and recorded_by_user_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false }, { "name": "recorded_by_user_id", "type": "str", "required": false } ], "response": { "schema_name": "VitalsignListResponse", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/vital-signs/{entity_id}", "summary": "Get Vital Sign", "description": "Retrieves a single vital sign record by ID. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "VitalsignResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "recorded_by_user_id", "type": "StrId", "required": true }, { "name": "recorded_at", "type": "datetime", "required": true }, { "name": "systolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "diastolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "pulse_rate", "type": "int", "required": false, "nullable": true }, { "name": "temperature_celsius", "type": "Decimal", "required": false, "nullable": true }, { "name": "respiratory_rate", "type": "int", "required": false, "nullable": true }, { "name": "weight_kg", "type": "Decimal", "required": false, "nullable": true }, { "name": "height_cm", "type": "Decimal", "required": false, "nullable": true }, { "name": "oxygen_saturation", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/vital-signs/{entity_id}", "summary": "Update Vital Sign", "description": "Updates an existing vital sign record. Validates references and constraints. Returns 404 if vital sign not found or 400 for validation errors.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "VitalsignUpdate", "fields": [ { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "recorded_by_user_id", "type": "str", "required": false, "nullable": true }, { "name": "recorded_at", "type": "datetime", "required": false, "nullable": true }, { "name": "systolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "diastolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "pulse_rate", "type": "int", "required": false, "nullable": true }, { "name": "temperature_celsius", "type": "Decimal", "required": false, "nullable": true }, { "name": "respiratory_rate", "type": "int", "required": false, "nullable": true }, { "name": "weight_kg", "type": "Decimal", "required": false, "nullable": true }, { "name": "height_cm", "type": "Decimal", "required": false, "nullable": true }, { "name": "oxygen_saturation", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "VitalsignResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "recorded_by_user_id", "type": "StrId", "required": true }, { "name": "recorded_at", "type": "datetime", "required": true }, { "name": "systolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "diastolic_bp", "type": "int", "required": false, "nullable": true }, { "name": "pulse_rate", "type": "int", "required": false, "nullable": true }, { "name": "temperature_celsius", "type": "Decimal", "required": false, "nullable": true }, { "name": "respiratory_rate", "type": "int", "required": false, "nullable": true }, { "name": "weight_kg", "type": "Decimal", "required": false, "nullable": true }, { "name": "height_cm", "type": "Decimal", "required": false, "nullable": true }, { "name": "oxygen_saturation", "type": "int", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/vital-signs/{entity_id}", "summary": "Delete Vital Sign", "description": "Deletes a vital sign record. Returns 404 if not found or 409 if referenced by other records.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/consultations", "summary": "Create Consultation", "description": "Creates a new consultation record. Validates patient, doctor, and optional appointment references. Returns 409 if appointment already has a consultation.", "request_body": { "schema_name": "ConsultationCreate", "fields": [ { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": false, "default": false }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "ConsultationResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/consultations", "summary": "List Consultations", "description": "Returns a paginated list of consultations. Supports optional filtering by patient_id, doctor_id, and appointment_id.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "appointment_id", "type": "str", "required": false } ], "response": { "schema_name": "ConsultationListResponse", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/consultations/{entity_id}", "summary": "Get Consultation", "description": "Retrieves a single consultation record by ID. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "ConsultationResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "GET", "path": "/consultations/{entity_id}/details", "summary": "Get Consultation Details", "description": "Retrieves a consultation with full details including patient, doctor, appointment, prescriptions, and lab tests. Uses eager loading to avoid N+1 queries. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "ConsultationDetailResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true }, { "name": "patient", "type": "PatientSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true }, { "name": "date_of_birth", "type": "date", "required": true } ] }, { "name": "doctor", "type": "DoctorSummary", "required": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "first_name", "type": "str", "required": true }, { "name": "last_name", "type": "str", "required": true } ] }, { "name": "appointment", "type": "AppointmentSummary", "required": false, "nullable": true, "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_date", "type": "date", "required": true } ] }, { "name": "prescriptions", "type": "List[PrescriptionSummary]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "medication_name", "type": "str", "required": true } ] }, { "name": "lab_tests", "type": "List[LabtestSummary]", "required": true, "is_list": true, "item_fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] } ] } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/consultations/{entity_id}", "summary": "Update Consultation", "description": "Updates an existing consultation record. Validates references. Returns 404 if consultation not found or 409 if appointment already has another consultation.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "ConsultationUpdate", "fields": [ { "name": "appointment_id", "type": "str", "required": false, "nullable": true }, { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "doctor_id", "type": "str", "required": false, "nullable": true }, { "name": "consultation_date", "type": "datetime", "required": false, "nullable": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": false, "nullable": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "ConsultationResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/consultations/{entity_id}", "summary": "Delete Consultation", "description": "Deletes a consultation record and cascades to related prescriptions and lab tests. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/consultations/{entity_id}/complete", "summary": "Complete Consultation", "description": "Marks a consultation as complete. Requires diagnosis to be entered. Updates related appointment status to completed. Returns 400 if diagnosis is missing or 404 if consultation not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "ConsultationResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "appointment_id", "type": "StrId", "required": false, "nullable": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "consultation_date", "type": "datetime", "required": true }, { "name": "chief_complaint", "type": "str", "required": false, "nullable": true }, { "name": "present_illness", "type": "str", "required": false, "nullable": true }, { "name": "examination_findings", "type": "str", "required": false, "nullable": true }, { "name": "diagnosis", "type": "str", "required": false, "nullable": true }, { "name": "treatment_plan", "type": "str", "required": false, "nullable": true }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "follow_up_required", "type": "bool", "required": true }, { "name": "follow_up_date", "type": "date", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/prescriptions", "summary": "Create Prescription", "description": "Creates a new prescription record. Validates consultation, patient, and doctor references. Returns 404 if any referenced entity does not exist.", "request_body": { "schema_name": "PrescriptionCreate", "fields": [ { "name": "consultation_id", "type": "str", "required": false }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "medication_name", "type": "str", "required": false }, { "name": "dosage", "type": "str", "required": false }, { "name": "frequency", "type": "str", "required": false }, { "name": "duration", "type": "str", "required": false }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "route", "type": "str", "required": false, "nullable": true }, { "name": "special_instructions", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "default": true }, { "name": "prescribed_date", "type": "date", "required": true } ] }, "response": { "schema_name": "PrescriptionResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "medication_name", "type": "str", "required": true }, { "name": "dosage", "type": "str", "required": true }, { "name": "frequency", "type": "str", "required": true }, { "name": "duration", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "route", "type": "str", "required": false, "nullable": true }, { "name": "special_instructions", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "prescribed_date", "type": "date", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/prescriptions", "summary": "List Prescriptions", "description": "Returns a paginated list of prescriptions. Supports optional filtering by patient_id, doctor_id, consultation_id, and is_active status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "consultation_id", "type": "str", "required": false }, { "name": "is_active", "type": "bool", "required": false } ], "response": { "schema_name": "PrescriptionListResponse", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/prescriptions/{entity_id}", "summary": "Get Prescription", "description": "Retrieves a single prescription record by ID. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "PrescriptionResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "medication_name", "type": "str", "required": true }, { "name": "dosage", "type": "str", "required": true }, { "name": "frequency", "type": "str", "required": true }, { "name": "duration", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "route", "type": "str", "required": false, "nullable": true }, { "name": "special_instructions", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "prescribed_date", "type": "date", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/prescriptions/{entity_id}", "summary": "Update Prescription", "description": "Updates an existing prescription record. Validates references. Returns 404 if prescription not found or 400 for validation errors.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "PrescriptionUpdate", "fields": [ { "name": "consultation_id", "type": "str", "required": false, "nullable": true }, { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "doctor_id", "type": "str", "required": false, "nullable": true }, { "name": "medication_name", "type": "str", "required": false, "nullable": true }, { "name": "dosage", "type": "str", "required": false, "nullable": true }, { "name": "frequency", "type": "str", "required": false, "nullable": true }, { "name": "duration", "type": "str", "required": false, "nullable": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "route", "type": "str", "required": false, "nullable": true }, { "name": "special_instructions", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": false, "nullable": true }, { "name": "prescribed_date", "type": "date", "required": false, "nullable": true } ] }, "response": { "schema_name": "PrescriptionResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "doctor_id", "type": "StrId", "required": true }, { "name": "medication_name", "type": "str", "required": true }, { "name": "dosage", "type": "str", "required": true }, { "name": "frequency", "type": "str", "required": true }, { "name": "duration", "type": "str", "required": true }, { "name": "quantity", "type": "int", "required": false, "nullable": true }, { "name": "route", "type": "str", "required": false, "nullable": true }, { "name": "special_instructions", "type": "str", "required": false, "nullable": true }, { "name": "is_active", "type": "bool", "required": true }, { "name": "prescribed_date", "type": "date", "required": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/prescriptions/{entity_id}", "summary": "Delete Prescription", "description": "Deletes a prescription record. Returns 404 if not found or 409 if referenced by other records.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/lab-tests", "summary": "Create Lab Test", "description": "Creates a new lab test order. Validates patient, doctor, and optional consultation references. Returns 404 if any referenced entity does not exist.", "request_body": { "schema_name": "LabtestCreate", "fields": [ { "name": "patient_id", "type": "str", "required": false }, { "name": "consultation_id", "type": "str", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "str", "required": false }, { "name": "test_name", "type": "str", "required": false }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LabtestResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 201 }, { "method": "GET", "path": "/lab-tests", "summary": "List Lab Tests", "description": "Returns a paginated list of lab tests. Supports optional filtering by patient_id, doctor_id (ordered_by), consultation_id, and status.", "query_params": [ { "name": "limit", "type": "int", "required": false, "default": 20 }, { "name": "offset", "type": "int", "required": false, "default": 0 }, { "name": "patient_id", "type": "str", "required": false }, { "name": "doctor_id", "type": "str", "required": false }, { "name": "consultation_id", "type": "str", "required": false }, { "name": "status", "type": "LabTestStatus", "required": false } ], "response": { "schema_name": "LabtestListResponse", "is_list": false, "fields": [] }, "status_code": 200 }, { "method": "GET", "path": "/lab-tests/{entity_id}", "summary": "Get Lab Test", "description": "Retrieves a single lab test record by ID. Returns 404 if not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "LabtestResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "PUT", "path": "/lab-tests/{entity_id}", "summary": "Update Lab Test", "description": "Updates an existing lab test record. Validates references and status transitions. Returns 404 if lab test not found or 400 for validation errors.", "path_params": [ { "name": "entity_id", "type": "str" } ], "request_body": { "schema_name": "LabtestUpdate", "fields": [ { "name": "patient_id", "type": "str", "required": false, "nullable": true }, { "name": "consultation_id", "type": "str", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "str", "required": false, "nullable": true }, { "name": "test_name", "type": "str", "required": false, "nullable": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": false, "nullable": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": false, "nullable": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true } ] }, "response": { "schema_name": "LabtestResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "DELETE", "path": "/lab-tests/{entity_id}", "summary": "Delete Lab Test", "description": "Deletes a lab test record. Returns 404 if not found or 409 if referenced by other records.", "path_params": [ { "name": "entity_id", "type": "str" } ], "status_code": 200 }, { "method": "POST", "path": "/lab-tests/{entity_id}/collect-sample", "summary": "Collect Lab Test Sample", "description": "Records sample collection for a lab test. Updates status to 'sample_collected' and sets collection timestamp. Can only be performed on tests in 'ordered' status. Returns 400 if invalid status or 404 if test not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "response": { "schema_name": "LabtestResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 }, { "method": "POST", "path": "/lab-tests/{entity_id}/enter-results", "summary": "Enter Lab Test Results", "description": "Enters results for a lab test. Updates status to 'completed' and sets result values. Requires sample to be collected first. Returns 400 if sample not collected or test is cancelled, 404 if test not found.", "path_params": [ { "name": "entity_id", "type": "str" } ], "query_params": [ { "name": "result_value", "type": "str", "required": false, "default": null }, { "name": "result_unit", "type": "str", "required": false }, { "name": "reference_range", "type": "str", "required": false } ], "response": { "schema_name": "LabtestResponse", "fields": [ { "name": "id", "type": "StrId", "required": true }, { "name": "patient_id", "type": "StrId", "required": true }, { "name": "consultation_id", "type": "StrId", "required": false, "nullable": true }, { "name": "ordered_by_doctor_id", "type": "StrId", "required": true }, { "name": "test_name", "type": "str", "required": true }, { "name": "test_type", "type": "str", "required": false, "nullable": true }, { "name": "ordered_date", "type": "datetime", "required": true }, { "name": "sample_collected_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_date", "type": "datetime", "required": false, "nullable": true }, { "name": "result_value", "type": "str", "required": false, "nullable": true }, { "name": "result_unit", "type": "str", "required": false, "nullable": true }, { "name": "reference_range", "type": "str", "required": false, "nullable": true }, { "name": "status", "type": "LabTestStatus", "required": true, "enum_values": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ] }, { "name": "notes", "type": "str", "required": false, "nullable": true }, { "name": "created_at", "type": "datetime", "required": true }, { "name": "updated_at", "type": "datetime", "required": true } ], "is_list": false }, "status_code": 200 } ] } ], "enums": { "UserRole": [ "ADMINISTRATOR", "DOCTOR", "NURSE", "RECEPTIONIST", "BILLING_OFFICER" ], "Gender": [ "MALE", "FEMALE", "OTHER" ], "AppointmentType": [ "CONSULTATION", "FOLLOW_UP", "EMERGENCY", "ROUTINE_CHECKUP", "PROCEDURE" ], "AppointmentStatus": [ "SCHEDULED", "CONFIRMED", "CHECKED_IN", "IN_PROGRESS", "COMPLETED", "CANCELLED", "NO_SHOW" ], "ServiceType": [ "CONSULTATION", "PROCEDURE", "LAB_TEST", "IMAGING", "THERAPY", "SURGERY", "VACCINATION", "OTHER" ], "LabTestStatus": [ "ORDERED", "SAMPLE_COLLECTED", "IN_PROGRESS", "COMPLETED", "CANCELLED" ], "InvoiceStatus": [ "DRAFT", "ISSUED", "PARTIALLY_PAID", "PAID", "OVERDUE", "CANCELLED" ], "PaymentMethod": [ "CASH", "CREDIT_CARD", "DEBIT_CARD", "INSURANCE", "BANK_TRANSFER", "CHEQUE", "OTHER" ], "ReportType": [ "PATIENT_STATISTICS", "REVENUE", "APPOINTMENT_SUMMARY", "SERVICE_UTILIZATION", "DOCTOR_PERFORMANCE", "BILLING_SUMMARY", "OPERATIONAL_METRICS" ], "ReportStatus": [ "GENERATING", "COMPLETED", "FAILED" ] } }