clinicpro/docs/api/rating.md

Rating & Comments API

Prefix: /api/v1/rate, /api/v1/comment, /api/v1/like

---

POST /api/v1/rate

Submit a rating for a doctor.

Permission: AUTH — any authenticated user (typically after a completed appointment)

Request Body (application/json)

{
  "doctor_uuid": "550e8400-...",
  "score": 5
}

Field	Type	Required	Validation
doctor_uuid	string (UUID)	✅	Must exist
score	integer	✅	1–5

Response 201

{
  "success": true,
  "data": {
    "uuid": "rate-uuid-...",
    "doctor_uuid": "...",
    "score": 5,
    "created_at": 1717000000
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_NOT_FOUND_001	404	Doctor not found
ERR_VALIDATION_001	422	Score out of range

---

GET /api/v1/rate/{doctorUuid}

Get average rating for a doctor.

Permission: PUBLIC

Path Parameters

Param	Type	Description
doctorUuid	string (UUID)	Doctor UUID

Response 200

{
  "success": true,
  "data": {
    "average": 4.3,
    "total": 47
  }
}

Errors

Code	HTTP	Description
ERR_NOT_FOUND_001	404	Doctor not found

---

POST /api/v1/comment

Submit a comment/review for a doctor.

Permission: AUTH

Comments require admin approval before appearing publicly.

Request Body (application/json)

{
  "doctor_uuid": "550e8400-...",
  "body": "پزشک بسیار مؤدب و متخصص بودند"
}

Field	Type	Required	Validation
doctor_uuid	string (UUID)	✅	Must exist
body	string	✅	Min 10 chars

Response 201

{
  "success": true,
  "data": {
    "uuid": "comment-uuid-...",
    "body": "پزشک بسیار مؤدب و متخصص بودند",
    "status": "pending",
    "created_at": 1717000000
  }
}

Comment Status Values:

Value	Description
pending	Awaiting admin review
approved	Visible to public
rejected	Not visible

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_NOT_FOUND_001	404	Doctor not found
ERR_VALIDATION_001	422	Body too short

---

GET /api/v1/comments/{doctorUuid}

Get approved comments for a doctor.

Permission: PUBLIC

Path Parameters

Param	Type	Description
doctorUuid	string (UUID)	Doctor UUID

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "body": "پزشک بسیار مؤدب...",
      "user": { "uuid": "...", "real_name": "علی" },
      "likes": 3,
      "status": "approved",
      "created_at": 1717000000
    }
  ]
}

Errors

Code	HTTP	Description
ERR_NOT_FOUND_001	404	Doctor not found

---

DELETE /api/v1/comment/{uuid}

Delete a comment.

Permission: AUTH — must be the comment author or ROLE_ADMIN

Response 200

{ "success": true, "data": { "message": "نظر حذف شد" } }

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_FORBIDDEN_001	403	Not the author
ERR_NOT_FOUND_001	404	Comment not found

---

GET /api/v1/admin/comments/pending

Get all pending comments waiting for review.

Permission: ROLE_ADMIN

Response 200

{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "body": "...",
      "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
      "user": { "uuid": "...", "real_name": "..." },
      "status": "pending",
      "created_at": 1717000000
    }
  ]
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_AUTH_006	403	Not admin

---

POST /api/v1/admin/comment/{uuid}/approve

Approve a pending comment (makes it public).

Permission: ROLE_ADMIN

Response 200

Updated comment object with status: "approved".

Errors

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

---

POST /api/v1/admin/comment/{uuid}/reject

Reject a pending comment.

Permission: ROLE_ADMIN

Response 200

Updated comment object with status: "rejected".

Errors

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

---

POST /api/v1/like/{commentUuid}

Toggle like on a comment (like if not liked, unlike if already liked).

Permission: AUTH

Path Parameters

Param	Type	Description
commentUuid	string (UUID)	Comment UUID

Response 200 (unlike) or 201 (new like)

{
  "success": true,
  "data": {
    "liked": true,
    "likes": 4
  }
}

Errors

Code	HTTP	Description
ERR_AUTH_001	401	Missing token
ERR_NOT_FOUND_001	404	Comment not found