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,227 @@
+# Representation (Agent) API
+
+> **Prefix:** `/api/v1/representation`
+
+Representations are sales agents who earn commission on appointments booked through their referral.
+
+---
+
+## POST `/api/v1/representation`
+
+Create a new representation.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "full_name": "علی احمدی",
+  "mobile_number": "09123456789",
+  "city_id": 42,
+  "commission_percent": 10,
+  "bank_account": {
+    "iban": "IR...",
+    "account_number": "1234567890",
+    "bank_name": "بانک ملت",
+    "owner_name": "علی احمدی"
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `full_name` | string | ✅ | Agent full name |
+| `mobile_number` | string | ✅ | Login mobile (creates a User account) |
+| `city_id` | integer | ❌ | City ID (FK to categories where bundle=city) |
+| `commission_percent` | float | ❌ | Commission rate (0–100) |
+| `bank_account` | object | ❌ | Bank details for settlements |
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "rep-uuid-...",
+    "full_name": "علی احمدی",
+    "mobile_number": "09123456789",
+    "city_id": 42,
+    "commission_percent": 10,
+    "active": true,
+    "bank_account": { ... },
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_CONFLICT_001` | 409 | Mobile number already in use |
+| `ERR_VALIDATION_001` | 422 | Invalid input |
+
+---
+
+## GET `/api/v1/representation/{uuid}`
+
+Get representation detail.
+
+**Permission:** `AUTH` — must be the representation's user or `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Representation UUID |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "...",
+    "full_name": "علی احمدی",
+    "mobile_number": "09123456789",
+    "city_id": 42,
+    "city_name": "تهران",
+    "commission_percent": 10,
+    "active": true,
+    "bank_account": { ... },
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not owner or admin |
+| `ERR_NOT_FOUND_001` | 404 | Representation not found |
+
+---
+
+## PATCH `/api/v1/representation/{uuid}`
+
+Update representation.
+
+**Permission:** `AUTH` — must be the representation's user or `ROLE_ADMIN`
+
+### Request Body (`application/json`)
+```json
+{
+  "full_name": "علی احمدی جدید",
+  "city_id": 50,
+  "commission_percent": 12,
+  "bank_account": { ... },
+  "active": true
+}
+```
+
+All fields optional.
+
+### Response `200`
+Updated representation object.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not owner or admin |
+| `ERR_NOT_FOUND_001` | 404 | Representation not found |
+
+---
+
+## DELETE `/api/v1/representation/{uuid}`
+
+Delete a representation.
+
+**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 | Representation not found |
+
+---
+
+## GET `/api/v1/representation/{uuid}/dashboard/monthly`
+
+Get monthly earnings dashboard for a representation.
+
+**Permission:** `AUTH` — must be the representation's user or `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Representation UUID |
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `year` | integer | ✅ | e.g. `2024` |
+| `month` | integer | ✅ | 1–12 |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "period": { "year": 2024, "month": 6 },
+    "stats": {
+      "total_appointments": 15,
+      "total_revenue_rials": 7500000,
+      "commission_rials": 750000,
+      "daily": [
+        { "date": "2024-06-01", "appointments": 2, "revenue": 1000000, "commission": 100000 }
+      ]
+    }
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not owner or admin |
+| `ERR_NOT_FOUND_001` | 404 | Representation not found |
+
+---
+
+## GET `/api/v1/representation/{uuid}/dashboard/yearly`
+
+Get yearly earnings dashboard for a representation.
+
+**Permission:** `AUTH` — must be the representation's user or `ROLE_ADMIN`
+
+### Query Parameters
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `year` | integer | ✅ | e.g. `2024` |
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "period": { "year": 2024 },
+    "months": [
+      { "month": 1, "appointments": 10, "revenue_rials": 5000000, "commission_rials": 500000 },
+      { "month": 2, "appointments": 8, "revenue_rials": 4000000, "commission_rials": 400000 }
+    ],
+    "totals": {
+      "appointments": 97,
+      "revenue_rials": 48500000,
+      "commission_rials": 4850000
+    }
+  }
+}
+```