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,249 @@
+# Location API (Province & City)
+
+> **Prefix:** `/api/v1/provinces`, `/api/v1/cities`, `/api/v1/admin/province`, `/api/v1/admin/city`
+
+---
+
+## GET `/api/v1/provinces`
+
+List all active provinces.
+
+**Permission:** `PUBLIC`
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 1, "name": "تهران", "status": "active", "weight": 1 },
+    { "id": 2, "name": "اصفهان", "status": "active", "weight": 2 }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/cities`
+
+List cities, optionally filtered by province.
+
+**Permission:** `PUBLIC`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `province_id` | integer | ❌ | Filter cities by province |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 10, "name": "تهران", "province_id": 1, "status": "active", "weight": 1 },
+    { "id": 11, "name": "کرج", "province_id": 1, "status": "active", "weight": 2 }
+  ]
+}
+```
+
+---
+
+## GET `/api/v1/admin/provinces`
+
+List all provinces 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 |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [ ... ],
+  "meta": { "totalRecords": 31, "totalPages": 2, "currentPage": 1 }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+
+---
+
+## GET `/api/v1/admin/cities`
+
+List all cities with pagination (admin view).
+
+**Permission:** `ROLE_ADMIN`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | integer | ❌ | Default: 1 |
+| `limit` | integer | ❌ | Default: 20 |
+| `search` | string | ❌ | Search in name |
+| `province_id` | integer | ❌ | Filter by province |
+
+### Response `200`
+Paginated city list.
+
+---
+
+## POST `/api/v1/admin/province`
+
+Create a new province.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "تهران",
+  "status": "active",
+  "weight": 1
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | Province name |
+| `status` | string | ❌ | `"active"` (default) or `"inactive"` |
+| `weight` | integer | ❌ | Sort weight |
+
+### Response `201`
+Province object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_VALIDATION_002` | 422 | Missing name |
+
+---
+
+## PATCH `/api/v1/admin/province/{id}`
+
+Update a province.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `id` | integer | Province ID |
+
+All fields optional.
+
+### Response `200`
+Updated province object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Province not found |
+
+---
+
+## DELETE `/api/v1/admin/province/{id}`
+
+Delete a province.
+
+**Permission:** `ROLE_ADMIN`
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "استان حذف شد" } }
+```
+
+---
+
+## POST `/api/v1/admin/city`
+
+Create a new city.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "name": "تهران",
+  "province_id": 1,
+  "status": "active",
+  "weight": 1
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | City name |
+| `province_id` | integer | ❌ | Parent province ID |
+| `status` | string | ❌ | `"active"` or `"inactive"` |
+| `weight` | integer | ❌ | Sort weight |
+
+### Response `201`
+City object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_VALIDATION_002` | 422 | Missing name |
+
+---
+
+## PATCH `/api/v1/admin/city/{id}`
+
+Update a city.
+
+**Permission:** `ROLE_ADMIN`
+
+All body fields optional.
+
+### Response `200`
+Updated city object.
+
+---
+
+## DELETE `/api/v1/admin/city/{id}`
+
+Delete a city.
+
+**Permission:** `ROLE_ADMIN`
+
+### Response `200`
+```json
+{ "success": true, "data": { "message": "شهر حذف شد" } }
+```
+
+---
+
+## GET `/api/v1/categorys/{bundle}` *(Legacy)*
+
+Legacy endpoint that proxies to the new endpoints.
+
+**Permission:** `PUBLIC`
+
+### Path Parameters
+| Bundle | Maps to |
+|--------|---------|
+| `state` | `/api/v1/provinces` |
+| `city` | `/api/v1/cities` |
+| `specially_doctor` | `/api/v1/specialties` |
+| `doctor_services` | `/api/v1/doctor-services` |
+| `insurance_type` | `/api/v1/insurances?type=basic` |
+| `supplementary_insurance` | `/api/v1/insurances?type=supplementary` |
+| `tag` | `/api/v1/tags` |
+
+> ⚠️ Response is **triple-nested**: `data?.data?.data ?? []`  
+> Note: `categorys` (not `categories`) is intentional — legacy route name.