Add API documentation for Representation, Secretary, Settlement, SMS, Specialty, Tag, and User Profile endpoints

2026-06-11 10:27:27 +03:30
parent e88ae9bf9c
commit cced85456a
22 changed files with 5691 additions and 0 deletions
@@ -0,0 +1,154 @@
+# User Profile API
+
+> **Prefix:** `/api/v1/user-profile`
+
+User medical profiles store health information that can be shared with doctors.
+
+---
+
+## POST `/api/v1/user-profile`
+
+Create a medical profile for the authenticated user.
+
+**Permission:** `AUTH`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "علی",
+  "family": "احمدی",
+  "fathers_name": "محمد",
+  "national_code": "0012345678",
+  "gender": "male",
+  "blood_type": "A+",
+  "marital_status": "married",
+  "education": "لیسانس",
+  "job": "مهندس",
+  "address": "تهران، خیابان ولیعصر",
+  "home_phone": "02112345678",
+  "work_phone": "02198765432",
+  "insurance_id": 1,
+  "description": "توضیحات بیشتر",
+  "sharing_with_user": true,
+  "birthday": "1370-06-15",
+  "date_of_birth": 648172800,
+  "basic_insurance": "بیمه تأمین اجتماعی",
+  "supplementary_insurance": "بیمه ایران",
+  "other": {}
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ❌ | First name |
+| `family` | string | ❌ | Last name |
+| `fathers_name` | string | ❌ | Father's name |
+| `national_code` | string | ❌ | National ID (10 digits) |
+| `gender` | string | ❌ | `"male"` or `"female"` |
+| `blood_type` | string | ❌ | `"A+"`, `"A-"`, `"B+"`, `"B-"`, `"AB+"`, `"AB-"`, `"O+"`, `"O-"` |
+| `marital_status` | string | ❌ | `"single"` or `"married"` |
+| `education` | string | ❌ | Education level |
+| `job` | string | ❌ | Occupation |
+| `address` | string | ❌ | Home address |
+| `home_phone` | string | ❌ | Home phone number |
+| `work_phone` | string | ❌ | Work phone number |
+| `insurance_id` | integer | ❌ | Insurance ID |
+| `description` | string | ❌ | Additional notes |
+| `sharing_with_user` | boolean | ❌ | Allow doctors to view this profile |
+| `birthday` | string | ❌ | Birthday in Jalali format `YYYY-MM-DD` |
+| `date_of_birth` | integer | ❌ | Birthday as Unix timestamp |
+| `basic_insurance` | string | ❌ | Basic insurance name |
+| `supplementary_insurance` | string | ❌ | Supplementary insurance name |
+| `other` | object | ❌ | Extra metadata |
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "profile-uuid-...",
+    "name": "علی",
+    "family": "احمدی",
+    "gender": "male",
+    "blood_type": "A+",
+    "national_code": "0012345678",
+    "sharing_with_user": true,
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_CONFLICT_001` | 409 | Profile already exists for this user |
+
+---
+
+## GET `/api/v1/user-profile/{uuid}`
+
+Get a user profile.
+
+**Permission:** `AUTH` — must be the profile owner, or a doctor if `sharing_with_user: true`, or `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Profile UUID |
+
+### Response `200`
+Full profile object including all fields.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not authorized to view this profile |
+| `ERR_NOT_FOUND_001` | 404 | Profile not found |
+
+---
+
+## PATCH `/api/v1/user-profile/{uuid}`
+
+Update a user profile.
+
+**Permission:** `AUTH` — must be the profile owner
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Profile UUID |
+
+### Request Body
+Same fields as POST — all optional.
+
+### Response `200`
+Updated profile object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the profile owner |
+| `ERR_NOT_FOUND_001` | 404 | Profile not found |
+
+---
+
+## DELETE `/api/v1/user-profile/{uuid}`
+
+Delete a user profile.
+
+**Permission:** `ROLE_ADMIN`
+
+### Response `200`
+```json
+{ "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 | Profile not found |