Документация API эндпоинтов

Ниже представлен список API эндпоинтов сервера с кратким описанием.

Аутентификация и Регистрация

1. POST /login
   • Описание: Аутентификация пользователя.
   • Request Body (JSON): {"phone": "string", "password": "string"}
   • Response Body (Success - 200 OK, JSON):{"success": true, "action": "login", "result": "USER_TYPE:USER_ID"} (например, "patient:123", "doctor:45")
   • Response Body (Error - 401 Unauthorized, JSON):{"success": false, "action": "login", "error": "Invalid credentials"}
   • Response Body (Error - 400 Bad Request, JSON):{"error": "Missing phone or password"}
2. POST /registration
   • Описание: Регистрация нового пользователя (по умолчанию как пациента).
   • Request Body (JSON):{"last_name": "string", "first_name": "string", "patronymic": "string" (optional), "phone": "string", "password": "string"}
   • Response Body (Success - 200 OK, JSON):{"success": true, "action": "registration"}
   • Response Body (Error - 409 Conflict, JSON):{"success": false, "action": "registration", "error": "User already exists or registration failed"}
   • Response Body (Error - 400 Bad Request, JSON):{"success": false, "error": "Missing required fields"}

Управление Пользователями (Административные)

3. POST /add_junior_admin (Для Senior Admin)
   • Описание: Добавление нового младшего администратора.
   • Request Body (JSON):{"last_name": "string", "first_name": "string", "patronymic": "string" (optional), "phone": "string"} (пароль по умолчанию "0987654321")
   • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Junior administrator successfully added"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 409, 500)
4. DELETE /delete_user_by_phone?phone=<phone_number> (Для Senior Admin)
   • Описание: Удаление пользователя по номеру телефона.
   • Request Parameters: phone (string)
   • Response Body (Success - 200 OK, JSON): {"success": true}
   • Response Body (Error - 404 Not Found, JSON):{"success": false, "error": "User not found"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 500)
   • Примечание: Клиент должен использовать HTTP DELETE.
5. GET /get_users (Для Junior/Senior Admin)
   • Описание: Получение списка всех пользователей.
   • Response Body (Success - 200 OK, JSON):{"success": true, "users": [{"id": "int", "last_name": "string", ...}]}
   • Response Body (Error - 500 Internal Server Error, JSON):{"success": false, "error": "сообщение об ошибке"}

Управление Профилями Пользователей

6. PATCH /edit_patient_profile
   • Описание: Редактирование профиля пациента.
   • Request Body (JSON):{ "user_id": int, "current_password": "string", "last_name": "string" (opt), "first_name": "string" (opt), "patronymic": "string" (opt), "phone": "string" (opt), "new_password": "string" (opt), "new_password_repeat": "string" (opt, required if new_password) }
   • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Profile updated successfully"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 401, 403, 404, 409, 500)
7. PATCH /edit_doctor_profile
   • Описание: Редактирование профиля врача.
   • Request Body (JSON):{ "user_id": int, "current_password": "string", "last_name": "string" (opt), "first_name": "string" (opt), "patronymic": "string" (opt), "phone": "string" (opt), "new_password": "string" (opt), "new_password_repeat": "string" (opt, required if new_password) }
   • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Profile updated successfully"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 401, 403, 404, 409, 500)
8. PATCH /edit_junior_admin_profile
   • Описание: Редактирование профиля младшего администратора. Телефон менять нельзя.
   • Request Body (JSON):{ "user_id": int, "current_password": "string", "last_name": "string" (opt), "first_name": "string" (opt), "patronymic": "string" (opt), "new_password": "string" (opt), "new_password_repeat": "string" (opt, required if new_password) }
   • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Junior admin profile updated successfully"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 401, 403, 404, 409, 500)
9. PATCH /edit_senior_admin_profile
   • Описание: Редактирование профиля старшего администратора.
   • Request Body (JSON):{ "user_id": int, "current_password": "string", "last_name": "string" (opt), "first_name": "string" (opt), "patronymic": "string" (opt), "phone": "string" (opt), "new_password": "string" (opt), "new_password_repeat": "string" (opt, required if new_password) }
   • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Senior admin profile updated successfully"}
   • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 401, 403, 404, 409, 500)
10. DELETE /delete_self_account?user_id=<user_id> (Для Patient, Doctor)
    • Описание: Удаление собственного аккаунта.
    • Request Parameters: user_id (int)
    • Response Body (Success - 200 OK, JSON): {"success": true}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 403, 404, 500)

Управление Врачами (Административные)

11. POST /add_doctor (Для Junior Admin)
    • Описание: Добавление нового врача.
    • Request Body (JSON):{"last_name": "string", "first_name": "string", "patronymic": "string" (opt), "phone": "string", "education": "string", "specialty": "string", "experience": int, "price": int} (пароль по умолчанию "987654321")
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Doctor successfully added"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 409, 500)
12. GET /get_doctors (Для Junior/Senior Admin)
    • Описание: Получение списка всех врачей.
    • Response Body (Success - 200 OK, JSON):{"success": true, "doctors": [{"doctor_id": "int", ...}]}
    • Response Body (Error - 500 Internal Server Error, JSON):{"success": false, "error": "сообщение об ошибке"}
13. GET /doctors_exist/<doctor_id> (Для Junior Admin)
    • Описание: Проверка существования врача по ID.
    • Response Body (Success - 200 OK, JSON):{"success": true, "exists": true, "doctor_id": "string"}
    • Response Body (Success - 404 Not Found, JSON):{"success": true, "exists": false}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}

Управление Больницами (Административные)

14. POST /add_hospital (Для Senior Admin)
    • Описание: Добавление новой больницы. admin_id - это user_id младшего администратора.
    • Request Body (JSON):{"region": "string", "settlement_type": "string", "settlement_name": "string", "street": "string", "house": "string", "full_name": "string", "admin_id": "string" (user_id младшего админа)}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Hospital successfully added"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 409, 500)
15. GET /get_hospitals (Для Senior Admin)
    • Описание: Получение списка всех больниц.
    • Response Body (Success - 200 OK, JSON):{"success": true, "hospitals": [{"hospital_id": "string", ...}]}
    • Response Body (Error - 500 Internal Server Error, JSON):{"success": false, "error": "сообщение об ошибке"}
16. GET /hospitals_exist/<hospital_id> (Для Junior Admin)
    • Описание: Проверка существования больницы по ID.
    • Response Body (Success - 200 OK, JSON):{"success": true, "exists": true, "hospital_id": "string"}
    • Response Body (Success - 404 Not Found, JSON):{"success": true, "exists": false}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
17. POST /attach_doctor_to_hospital (Для Junior Admin)
    • Описание: Прикрепление врача к больнице.
    • Request Body (JSON):{"doctor_id": int, "hospital_id": int, "junior_admin_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Doctor successfully attached to hospital"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 409, 500, 503)
18. POST /detach_doctor_from_hospital (Для Junior Admin)
    • Описание: Открепление врача от больницы.
    • Request Body (JSON):{"doctor_id": int, "hospital_id": int, "junior_admin_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Hospital ID removed from doctor's list"}
    • Response Body (Error, JSON): {"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 500)

Управление Записями на Прием и Расписанием

19. POST /add_record_slot (Для Junior Admin)
    • Описание: Добавление нового слота для записи к врачу. junior_admin_id используется для проверки, что больница принадлежит этому админу.
    • Request Body (JSON):{"doctor_id": int, "date": "YYYY-MM-DD", "time": "HH:MM:SS", "hospital_id": int, "cabinet": int, "junior_admin_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Appointment slot added"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 500)
20. GET /get_doctor_schedule?doctor_id=<id> (Для Doctor, Junior Admin)
    • Описание: Получение расписания врача на ближайшие 7 дней. Для Junior Admin также выполняется проверка принадлежности врача к его больнице (через /check_doctor_admin_hospital).
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "schedule": [{"appointment_date": "YYYY-MM-DD", "appointment_time": "HH:MM:SS", "full_name": "string" (название больницы), ...}]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
21. GET /get_doctor_schedule_for_patient?doctor_id=<id> (Для Patient)
    • Описание: Получение расписания врача для пациента (включая статус слота и hospital_id).
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "schedule": [{"appointment_date": "YYYY-MM-DD", ..., "slot_status": "open/close", "hospital_id": "string"}]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
22. GET /junior_admin_schedule?junior_admin_id=<id>&doctor_id=<id> (Для Junior Admin)
    • Описание: Получение расписания врача в больнице младшего администратора.
    • Request Parameters: junior_admin_id (int), doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "schedule": [...]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
    • Примечание: Текущая реализация на сервере для GET-запроса неверно обрабатывает параметры. Требуется исправление (см. TODO B.3).
23. POST /book_appointment (Для Patient)
    • Описание: Запись пациента на прием.
    • Request Body (JSON):{"doctor_id": int, "hospital_id": int, "appointment_date": "YYYY-MM-DD", "appointment_time": "HH:MM:SS", "patient_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Booked successfully"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 404, 409, 500)
24. PATCH /cancel_appointment (Для Patient)
    • Описание: Отмена записи на прием.
    • Request Body (JSON): {"record_id": int, "patient_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Appointment cancelled / Cancelled and notified waitlister"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 404, 500)
25. GET /get_patient_appointments?patient_id=<id> (Для Patient)
    • Описание: Получение списка записей пациента.
    • Request Parameters: patient_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "appointments": [{"appointment_date": "YYYY-MM-DD", ...}]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
26. GET /get_cancelled_slots?doctor_id=<id> (Для Patient)
    • Описание: Получение списка отмененных слотов для указанного врача.
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "slots": [{"record_id": int, "date": "YYYY-MM-DD", "time": "HH:MM:SS"}]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}

Поиск Врачей и Фильтры (Для Patient)

27. POST /search_doctors
    • Описание: Поиск врачей по различным критериям.
    • Request Body (JSON):{"region": "string" (opt, "-" if any), "settlement_type": "string" (opt, "-" if any), "settlement_name": "string" (opt, "-" if any), "full_name": "string" (opt, "-" if any, название больницы), "specialty": "string" (opt, "-" if any), "sort_by_rating": boolean (opt, default false)}
    • Response Body (Success - 200 OK, JSON):{"success": true, "doctors": [{"fio": "string", "specialty": "string", ...}]}
    • Response Body (Error - 500 Internal Server Error, JSON):{"success": false, "error": "Database error"}
    • Примечание: Клиентская функция get_doctors_for_patient должна использовать этот эндпоинт для фильтрации.
28. GET /get_regions
    • Описание: Получение списка уникальных регионов больниц.
    • Response Body (Success - 200 OK, JSON):{"success": true, "regions": ["-", "Region1", ...]}
29. GET /get_settlement_types
    • Описание: Получение списка уникальных типов населенных пунктов.
    • Response Body (Success - 200 OK, JSON):{"success": true, "settlement_types": ["-", "Type1", ...]}
30. GET /get_settlement_names
    • Описание: Получение списка уникальных названий населенных пунктов.
    • Response Body (Success - 200 OK, JSON):{"success": true, "settlement_names": ["-", "Name1", ...]}
31. GET /get_hospital_full_names
    • Описание: Получение списка полных названий больниц.
    • Response Body (Success - 200 OK, JSON):{"success": true, "hospital_full_names": ["-", "FullName1", ...]}
32. GET /get_specialties
    • Описание: Получение списка уникальных специальностей врачей.
    • Response Body (Success - 200 OK, JSON):{"success": true, "specialties": ["-", "Specialty1", ...]}
33. GET /get_doctor_hospitals?doctor_id=<id>
    • Описание: Получение списка больниц, к которым прикреплен врач.
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "hospitals": [{"hospital_id": int, "full_name": "string", ...}]}

Отзывы о Врачах

34. POST /post_doctor_feedback (Для Patient)
    • Описание: Добавление отзыва о враче.
    • Request Body (JSON):{"doctor_ref_id": int, "user_id": int, "text": "string", "rate": int (1-5), "address": "string"} (name и date генерируются сервером)
    • Response Body (Success - 201 Created, JSON):{"success": true, "id": "new_rating_id"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 404, 500)
35. PATCH /edit_doctor_feedback (Для Patient - автора отзыва)
    • Описание: Редактирование собственного отзыва.
    • Request Body (JSON):{"rating_id": int, "user_id": int (автор), "rate": int, "text": "string" (opt), "name": "string", "date": "YYYY-MM-DD HH:MM:SS", "address": "string"}
    • Response Body (Success - 200 OK, JSON): {"success": true}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 500)
36. DELETE /delete_doctor_feedback (Для Patient - автора, или Junior Admin, если врач из его больницы)
    • Описание: Удаление отзыва.
    • Request Body (JSON):{"rating_id": int, "admin_id": int (user_id того, кто удаляет)}
    • Response Body (Success - 200 OK, JSON): {"success": true}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 500)
37. GET /get_doctor_feedback_items?doctor_id=<id> (Для Patient)
    • Описание: Получение всех отзывов о враче.
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "ratings": [{"id": int, "text": "string", ...}]}
38. GET /get_doctor_feedback_calculated?doctor_id=<id> (Для Patient)
    • Описание: Получение среднего рейтинга врача.
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "average": "float"}
39. GET /get_doctor_average_ratings (Для Patient)
    • Описание: Получение средних рейтингов для всех врачей (взвешенный).
    • Response Body (Success - 200 OK, JSON):{"success": true, "doctor_average_ratings": ["-", "float", ...]} (массив, где индекс может соответствовать doctor_id, если так задумано)

Лист Ожидания (Waitlist)

40. POST /add_patient_to_waitlist (Для Patient)
    • Описание: Добавление пациента в лист ожидания к врачу.
    • Request Body (JSON): {"doctor_id": int, "patient_id": int} (ФИО и телефон берутся из users)
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Patient added to waitlist successfully"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 404, 500)
41. POST /cancel_appointment_from_waitlist (Для Patient)
    • Описание: Отмена своей записи из листа ожидания.
    • Request Body (JSON): {"waitlist_id": int, "patient_id": int}
    • Response Body (Success - 200 OK, JSON):{"success": true, "message": "Removed from waitlist"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 500)
    • Примечание: Клиент вызывает этот эндпоинт через функцию cancel_waitlist.
42. GET /get_waitlist?doctor_id=<id>&junior_admin_id=<id> (Для Junior Admin)
    • Описание: Получение листа ожидания для врача (если врач прикреплен к больнице администратора).
    • Request Parameters: doctor_id (int), junior_admin_id (int)
    • Response Body (Success - 200 OK, JSON):{"success": true, "waitlist": [{"id": int, "patient_id": int, ...}]}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"}
43. GET /get_waitlist_count?doctor_id=<id> (Для Patient, Junior Admin)
    • Описание: Получение количества пациентов в листе ожидания у врача.
    • Request Parameters: doctor_id (int)
    • Response Body (Success - 200 OK, JSON): {"success": true, "count": int}

Вспомогательные и Прочее

44. GET /get_user_id?phone=<phone_number>
    • Описание: Получение ID пользователя по номеру телефона.
    • Request Parameters: phone (string)
    • Response Body (Success - 200 OK, JSON): {"id": int}
    • Response Body (Error - 404 Not Found, JSON): {"error": "User not found"}
45. GET /get_user_type?phone=<phone_number>
    • Описание: Получение типа пользователя по номеру телефона.
    • Request Parameters: phone (string)
    • Response Body (Success - 200 OK, JSON): {"user_type": "string"}
    • Response Body (Error - 404 Not Found, JSON): {"error": "User not found"}
46. GET /check_doctor_admin_hospital?doctor_id=<id>&admin_id=<id> (Для Junior Admin)
    • Описание: Проверка, привязан ли врач к той же больнице, что и младший администратор.
    • Request Parameters: doctor_id (int), admin_id (int, user_id младшего админа)
    • Response Body (Success - 200 OK, JSON):{"is_valid": boolean, "admin_hospital_id": int, "doctor_id": int}
47. POST /get_doctor_statistics (Для Junior Admin)
    • Описание: Получение статистики по врачу (количество пациентов за месяц, средний рейтинг, цена приема). Врач должен быть прикреплен к больнице администратора.
    • Request Body (JSON): {"junior_admin_id": int, "doctor_phone": "string"}
    • Response Body (Success - 200 OK, JSON):{"success": true, "patients_count": int, "average_rating": "float", "price": "float"}
    • Response Body (Error, JSON):{"success": false, "error": "сообщение об ошибке"} (статусы 400, 403, 404, 500)

Последнее обновление: 2025-06-06 00:58:12