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,220 @@
+# Secretary API
+
+> **Prefix:** `/api/v1/secretary`, `/api/v1/secretaries`
+
+Secretaries are linked to a doctor and have granular permissions controlling what they can do on behalf of the doctor.
+
+---
+
+## POST `/api/v1/secretary`
+
+Create a secretary for a doctor.
+
+**Permission:** `ROLE_DOCTOR` — must own the doctor profile
+
+### Request Body (`application/json`)
+```json
+{
+  "doctor_uuid": "550e8400-...",
+  "mobile_number": "09123456789",
+  "password": "secretaryPass123",
+  "permissions": {
+    "version": 1,
+    "resources": {
+      "appointments": { "view": true, "create": true, "cancel": false, "update_status": true },
+      "addresses":    { "view": true, "create": false, "update": false, "delete": false },
+      "clinic_info":  { "view": true, "update": false },
+      "insurances":   { "view": true, "create": false, "update": false, "delete": false }
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `doctor_uuid` | string (UUID) | ✅ | Doctor to assign secretary to |
+| `mobile_number` | string | ✅ | Secretary's login mobile |
+| `password` | string | ❌ | Initial password (auto-generated if omitted) |
+| `permissions` | object | ❌ | Permission set (see structure below) |
+
+**Permissions Structure:**
+```json
+{
+  "version": 1,
+  "resources": {
+    "appointments": {
+      "view":          true,   // Can view appointments list
+      "create":        true,   // Can book appointments
+      "cancel":        false,  // Can cancel appointments
+      "update_status": true    // Can mark as completed/no_show
+    },
+    "addresses": {
+      "view":   true,
+      "create": false,
+      "update": false,
+      "delete": false
+    },
+    "clinic_info": {
+      "view":   true,
+      "update": false
+    },
+    "insurances": {
+      "view":   true,
+      "create": false,
+      "update": false,
+      "delete": false
+    }
+  }
+}
+```
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "sec-uuid-...",
+    "mobile_number": "09123456789",
+    "active": true,
+    "permissions": { ... },
+    "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not a doctor or not the doctor's owner |
+| `ERR_NOT_FOUND_001` | 404 | Doctor not found |
+| `ERR_CONFLICT_001` | 409 | Mobile number already in use |
+| `ERR_SECRETARY_001` | 422 | Plan limit for secretaries reached |
+
+---
+
+## GET `/api/v1/secretary/{uuid}`
+
+Get secretary detail.
+
+**Permission:** `AUTH` — must be the linked doctor or `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Secretary UUID |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "...",
+    "mobile_number": "09123456789",
+    "active": true,
+    "permissions": { ... },
+    "doctor": { "uuid": "...", "title": "دکتر علی احمدی" },
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not authorized |
+| `ERR_NOT_FOUND_001` | 404 | Secretary not found |
+
+---
+
+## PATCH `/api/v1/secretary/{uuid}`
+
+Update secretary active status or permissions.
+
+**Permission:** `ROLE_DOCTOR` — must be the linked doctor
+
+### Request Body (`application/json`)
+```json
+{
+  "active": false,
+  "permissions": {
+    "version": 1,
+    "resources": {
+      "appointments": { "view": true, "create": false, "cancel": false, "update_status": false }
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `active` | boolean | ❌ | Enable/disable secretary |
+| `permissions` | object | ❌ | New permissions object |
+
+### Response `200`
+Updated secretary object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the linked doctor |
+| `ERR_NOT_FOUND_001` | 404 | Secretary not found |
+
+---
+
+## DELETE `/api/v1/secretary/{uuid}`
+
+Delete a secretary.
+
+**Permission:** `ROLE_DOCTOR` — must be the linked doctor
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "منشی حذف شد" } }
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the linked doctor |
+| `ERR_NOT_FOUND_001` | 404 | Secretary not found |
+
+---
+
+## GET `/api/v1/secretaries/{doctorUuid}`
+
+Get all secretaries for a specific doctor.
+
+**Permission:** `AUTH` — must be the doctor or `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `doctorUuid` | string (UUID) | Doctor UUID |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "mobile_number": "09...",
+      "active": true,
+      "permissions": { ... },
+      "created_at": 1717000000
+    }
+  ]
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the doctor |
+| `ERR_NOT_FOUND_001` | 404 | Doctor not found |