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,267 @@
+# Insurance API
+
+> **Prefix:** `/api/v1/insurances`, `/api/v1/insurance`, `/api/v1/admin/insurance`
+
+Two resource types:
+1. **Insurance** — master list of insurance companies managed by admin
+2. **DoctorInsurance** — a doctor's acceptance of a specific insurance (with optional price)
+
+---
+
+## GET `/api/v1/insurances`
+
+List all active insurances.
+
+**Permission:** `PUBLIC`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | string | ❌ | `"basic"` or `"supplementary"` |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": 1,
+      "name": "بیمه تأمین اجتماعی",
+      "type": "basic",
+      "logo_url": "https://...",
+      "status": "active"
+    },
+    {
+      "id": 2,
+      "name": "بیمه ایران",
+      "type": "supplementary",
+      "logo_url": "https://...",
+      "status": "active"
+    }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/admin/insurances`
+
+List all insurances with pagination (admin view — includes inactive).
+
+**Permission:** `ROLE_ADMIN`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | integer | ❌ | Default: 1 |
+| `limit` | integer | ❌ | Default: 20 |
+| `search` | string | ❌ | Search in name |
+| `type` | string | ❌ | `"basic"` or `"supplementary"` |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "meta": { "totalRecords": 15, "totalPages": 1, "currentPage": 1 }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+
+---
+
+## POST `/api/v1/admin/insurance`
+
+Create a new insurance.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "بیمه تأمین اجتماعی",
+  "type": "basic",
+  "logo_url": "https://...",
+  "status": "active"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | Insurance name |
+| `type` | string | ✅ | `"basic"` or `"supplementary"` |
+| `logo_url` | string | ❌ | Logo image URL |
+| `status` | string | ❌ | `"active"` (default) or `"inactive"` |
+
+### Response `201`
+Insurance object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_VALIDATION_002` | 422 | Missing required field |
+
+---
+
+## PATCH `/api/v1/admin/insurance/{id}`
+
+Update an insurance.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Insurance ID |
+
+All body fields optional.
+
+### Response `200`
+Updated insurance object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Insurance not found |
+
+---
+
+## DELETE `/api/v1/admin/insurance/{id}`
+
+Delete an insurance.
+
+**Permission:** `ROLE_ADMIN`
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "بیمه حذف شد" } }
+```
+
+---
+
+## POST `/api/v1/admin/insurance/{id}/upload-logo`
+
+Upload insurance logo.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request
+`Content-Type: multipart/form-data`
+
+| Field | Type | Required |
+|-------|------|----------|
+| `file` | binary | ✅ |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "url": "https://...",
+    "uuid": "...",
+    "filename": "insurance_logo.png",
+    "filemime": "image/png",
+    "filesize": 51200
+  }
+}
+```
+
+---
+
+## POST `/api/v1/insurance/`
+
+Add an insurance to a doctor's accepted list.
+
+**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.create` permission)
+
+### Request Body (`application/json`)
+```json
+{
+  "doctor_id": 42,
+  "insurance_id": 1,
+  "price": 150000
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `doctor_id` | integer | ✅ | Doctor's numeric ID |
+| `insurance_id` | integer | ✅ | Insurance ID |
+| `price` | integer | ❌ | Visit price for this insurance (Rials) |
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "id": 10,
+    "doctor_id": 42,
+    "insurance": { "id": 1, "name": "بیمه تأمین اجتماعی", "type": "basic" },
+    "price": 150000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the doctor |
+| `ERR_NOT_FOUND_001` | 404 | Doctor or insurance not found |
+| `ERR_CONFLICT_001` | 409 | Insurance already added to doctor |
+
+---
+
+## GET `/api/v1/insurance/{id}`
+
+Get a doctor-insurance link.
+
+**Permission:** `PUBLIC`
+
+### Response `200`
+DoctorInsurance object.
+
+---
+
+## PATCH `/api/v1/insurance/{id}`
+
+Update a doctor-insurance (e.g., change price).
+
+**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.update` permission)
+
+### Request Body
+```json
+{ "price": 200000 }
+```
+
+### Response `200`
+Updated DoctorInsurance object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the doctor |
+| `ERR_NOT_FOUND_001` | 404 | Link not found |
+
+---
+
+## DELETE `/api/v1/insurance/{id}`
+
+Remove an insurance from a doctor's list.
+
+**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.delete` permission)
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "بیمه از لیست حذف شد" } }
+```