clinicpro/docs/api/doctor.md

Doctor API

Prefix: /api/v1/doctor, /api/v1/doctors, /api/v1/clinic-pro/doctor-address*

---

POST /api/v1/doctor

Create a doctor profile for the authenticated user.

Permission: AUTH — any authenticated user

Request Body (application/json)

{
  "title": "دکتر علی احمدی",
  "gender": "male",
  "medical_system_code": "12345",
  "degree": "متخصص",
  "info": "توضیحات درباره پزشک",
  "specialties": [1, 2],
  "doctor_services": [3, 4]
}

Field	Type	Required	Description
title	string	✅	Full name with title
gender	string	❌	"male" or "female"
medical_system_code	string	❌	Nظام پزشکی code
degree	string	❌	Academic degree
info	string	❌	Bio/description
specialties	integer[]	❌	Array of specialty IDs
doctor_services	integer[]	❌	Array of doctor service IDs

Response 201

{
  "success": true,
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "دکتر علی احمدی",
    "gender": "male",
    "medical_system_code": "12345",
    "degree": "متخصص",
    "info": "...",
    "doctor_rate": null,
    "active_doctor_appointment": false,
    "specialties": [],
    "doctor_services": [],
    "created_at": 1717000000
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing or invalid token
ERR_CONFLICT_001	409	Doctor profile already exists for this user
ERR_VALIDATION_002	422	Missing required field

---

GET /api/v1/doctor/{uuid}

Get doctor detail with clinics.

Permission: PUBLIC

Path Parameters

Param	Type	Description
uuid	string (UUID)	Doctor UUID

Response 200

{
  "success": true,
  "data": {
    "data": {
      "uuid": "550e8400-...",
      "title": "دکتر علی احمدی",
      "gender": "male",
      "medical_system_code": "12345",
      "degree": "متخصص",
      "info": "...",
      "image": "https://...",
      "doctor_rate": 4.5,
      "active_doctor_appointment": true,
      "specialties": [{ "id": 1, "name": "قلب و عروق" }],
      "doctor_services": [{ "id": 3, "name": "نوار قلب" }],
      "clinics": [{ "uuid": "...", "name": "کلینیک الوند" }],
      "created_at": 1717000000
    }
  }
}

⚠️ Double-nested: Frontend extracts with data?.data?.data

Errors

Code	HTTP	Description
ERR_NOT_FOUND_001	404	Doctor not found

---

GET /api/v1/doctors

List doctors with pagination and filters.

Permission: PUBLIC

Query Parameters

Param	Type	Required	Description
page	integer	❌	Default: 1
limit	integer	❌	Default: 20
search	string	❌	Search in title
specialty_id	integer	❌	Filter by specialty
city_id	integer	❌	Filter by city
state_id	integer	❌	Filter by province

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "title": "دکتر علی احمدی",
      "degree": "متخصص",
      "doctor_rate": 4.5,
      "image": "https://..."
    }
  ],
  "meta": {
    "totalRecords": 50,
    "totalPages": 3,
    "currentPage": 1
  }
}

---

PATCH /api/v1/doctor/{uuid}

Update doctor profile.

Permission: AUTH — must be the owner (or ROLE_ADMIN)

Path Parameters

Param	Type	Description
uuid	string (UUID)	Doctor UUID

Request Body (application/json)

Same fields as POST — all optional.

Response 200

Updated doctor object (same structure as GET single).

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not the owner
ERR_NOT_FOUND_001	404	Doctor not found

---

DELETE /api/v1/doctor/{uuid}

Delete a doctor profile.

Permission: ROLE_ADMIN

Path Parameters

Param	Type	Description
uuid	string (UUID)	Doctor UUID

Response 200

{
  "success": true,
  "data": { "message": "پزشک با موفقیت حذف شد" }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin
ERR_NOT_FOUND_001	404	Doctor not found

---

POST /file/upload/clinic_pro/doctor/field_image

Upload doctor profile image.

Permission: AUTH

Request

Content-Type: multipart/form-data

Field	Type	Required	Description
file	binary	✅	Image file (max 5MB)

Response 200

{
  "success": true,
  "data": {
    "url": "https://clinic-pro.ddev.site/uploads/doctor/abc123.jpg",
    "uuid": "...",
    "filename": "abc123.jpg",
    "filemime": "image/jpeg",
    "filesize": 204800
  }
}

Errors

Code	HTTP	Description
ERR_FILE_001	422	Invalid file type
ERR_AUTH_001	401	Missing token

---

GET /api/v1/clinic-pro/doctor-addresses/{doctorId}

Get all practice addresses for a doctor.

Permission: PUBLIC

Path Parameters

Param	Type	Description
doctorId	integer	Doctor's numeric ID

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "مطب تهران",
      "address": "تهران، خیابان...",
      "telephone": "02112345678",
      "latitude": 35.6892,
      "longitude": 51.3890
    }
  ]
}

---

POST /api/v1/clinic-pro/doctor-address

Add a new practice address.

Permission: AUTH — must own the doctor profile

Request Body

{
  "name": "مطب تهران",
  "address": "تهران، خیابان ولیعصر",
  "telephone": "02112345678",
  "latitude": 35.6892,
  "longitude": 51.3890
}

Field	Type	Required
name	string	❌
address	string	❌
telephone	string	❌
latitude	float	❌
longitude	float	❌

Response 201

{
  "success": true,
  "data": {
    "id": 1,
    "name": "مطب تهران",
    "address": "تهران، خیابان ولیعصر",
    "telephone": "02112345678",
    "latitude": 35.6892,
    "longitude": 51.3890
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not the doctor owner
ERR_NOT_FOUND_001	404	Doctor not found

---

PATCH /api/v1/clinic-pro/doctor-address/{id}

Update a practice address.

Permission: AUTH — must own the doctor profile

Path Parameters

Param	Type	Description
id	integer	Address ID

Request Body

Same fields as POST — all optional.

Response 200

Updated address object.

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not the owner
ERR_NOT_FOUND_001	404	Address not found

---

DELETE /api/v1/clinic-pro/doctor-address/{id}

Delete a practice address.

Permission: AUTH — must own the doctor profile

Response 200

{ "success": true, "data": { "message": "آدرس حذف شد" } }

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not the owner
ERR_NOT_FOUND_001	404	Address not found

---

POST /api/v1/clinic-pro/doctor-address/from-clinic/{clinicUuid}

Create a doctor address automatically from a clinic's location.

Permission: AUTH — must own the doctor profile and be associated with the clinic

Path Parameters

Param	Type	Description
clinicUuid	string (UUID)	Clinic UUID

Response 201

Address object created from clinic data.

Errors

Code	HTTP	Description
ERR_FORBIDDEN_001	403	Not associated with this clinic
ERR_NOT_FOUND_001	404	Clinic not found