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,254 @@
+# Settlement & Wallet API
+
+> **Prefix:** `/api/v1/wallet`, `/api/v1/settlement`
+
+---
+
+## GET `/api/v1/wallet/balance`
+
+Get authenticated user's wallet balance.
+
+**Permission:** `AUTH`
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": {
+    "balance_rials": 2500000,
+    "recent_transactions": [
+      {
+        "uuid": "...",
+        "type": "credit",
+        "amount_rials": 500000,
+        "balance_after": 2500000,
+        "description": "دریافت از نوبت شماره ...",
+        "created_at": 1717000000
+      }
+    ]
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+
+---
+
+## GET `/api/v1/wallet/transactions`
+
+Get wallet transaction history for the authenticated user.
+
+**Permission:** `AUTH`
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "type": "credit",
+      "amount_rials": 500000,
+      "balance_after": 2500000,
+      "description": "دریافت از نوبت",
+      "created_at": 1717000000
+    },
+    {
+      "uuid": "...",
+      "type": "debit",
+      "amount_rials": 200000,
+      "balance_after": 2300000,
+      "description": "تسویه‌حساب",
+      "created_at": 1716900000
+    }
+  ]
+}
+```
+
+**Transaction Type Values:**
+| Value | Description |
+|-------|-------------|
+| `credit` | Money added to wallet |
+| `debit` | Money removed from wallet |
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+
+---
+
+## POST `/api/v1/settlement`
+
+Request a settlement (withdrawal from wallet to bank account).
+
+**Permission:** `AUTH`
+
+### Request Body (`application/json`)
+```json
+{
+  "amount_rials": 1000000,
+  "bank_account": {
+    "iban": "IR...",
+    "account_number": "1234567890",
+    "bank_name": "بانک ملت",
+    "owner_name": "علی احمدی"
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `amount_rials` | integer | ✅ | Amount to withdraw (must be ≤ wallet balance) |
+| `bank_account` | object | ❌ | Bank account details (saved if not previously set) |
+| `bank_account.iban` | string | ❌ | IBAN (شبا) |
+| `bank_account.account_number` | string | ❌ | Account number |
+| `bank_account.bank_name` | string | ❌ | Bank name |
+| `bank_account.owner_name` | string | ❌ | Account owner name |
+
+### Response `201`
+```json
+{
+  "success": true,
+  "data": {
+    "uuid": "settle-uuid-...",
+    "amount_rials": 1000000,
+    "status": "pending",
+    "bank_account": {
+      "iban": "IR...",
+      "bank_name": "بانک ملت",
+      "owner_name": "علی احمدی"
+    },
+    "created_at": 1717000000
+  }
+}
+```
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_VALIDATION_001` | 422 | Amount exceeds balance or invalid amount |
+
+---
+
+## GET `/api/v1/settlement`
+
+Get authenticated user's settlement requests.
+
+**Permission:** `AUTH`
+
+### Response `200`
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "amount_rials": 1000000,
+      "status": "pending",
+      "note": null,
+      "created_at": 1717000000,
+      "processed_at": null
+    }
+  ]
+}
+```
+
+**Settlement Status Values:**
+| Value | Description |
+|-------|-------------|
+| `pending` | Awaiting admin review |
+| `approved` | Approved, payment sent |
+| `rejected` | Rejected by admin |
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+
+---
+
+## GET `/api/v1/settlement/{uuid}`
+
+Get a single settlement.
+
+**Permission:** `AUTH` — must be the owner or `ROLE_ADMIN`
+
+### Response `200`
+Settlement object with full details including `bank_account`.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_FORBIDDEN_001` | 403 | Not the owner |
+| `ERR_NOT_FOUND_001` | 404 | Settlement not found |
+
+---
+
+## POST `/api/v1/settlement/{uuid}/approve`
+
+Approve a settlement request. Marks it as paid and debits the wallet.
+
+**Permission:** `ROLE_ADMIN`
+
+### Path Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `uuid` | string (UUID) | Settlement UUID |
+
+### Request Body (`application/json`)
+```json
+{
+  "note": "پرداخت شد — شناسه پیگیری: 123456"
+}
+```
+
+| Field | Type | Required |
+|-------|------|----------|
+| `note` | string | ❌ |
+
+### Response `200`
+Updated settlement object with `status: "approved"`.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Settlement not found |
+| `ERR_VALIDATION_001` | 422 | Already processed |
+
+---
+
+## POST `/api/v1/settlement/{uuid}/reject`
+
+Reject a settlement request. Returns the amount back to wallet.
+
+**Permission:** `ROLE_ADMIN`
+
+### Request Body
+```json
+{
+  "note": "حساب بانکی نادرست است"
+}
+```
+
+| Field | Type | Required |
+|-------|------|----------|
+| `note` | string | ✅ | Rejection reason (required) |
+
+### Response `200`
+Updated settlement object with `status: "rejected"`.
+
+### Errors
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_AUTH_001` | 401 | Missing token |
+| `ERR_AUTH_006` | 403 | Not admin |
+| `ERR_NOT_FOUND_001` | 404 | Settlement not found |
+| `ERR_VALIDATION_002` | 422 | Missing note |