clinicpro/docs/api/settlement.md

# 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 |

---

## FinancialBreakdown (لاگ مالی)

علاوه بر تسویه‌حساب دستی، کیف‌پول نماینده به‌صورت خودکار از طریق `CommissionService` هنگام پرداخت موفقِ نوبت/اشتراک شارژ می‌شود (`WalletTransaction` credit). هر واریز یک ردیف `FinancialBreakdown` ثبت می‌کند که تفکیک کامل تراکنش (ناخالص، هزینه پیامک، مالیات، خالص، درصد و سهم پورسانت، سهم سیستم) را نگه می‌دارد. ثبت idempotent است (بر اساس `payment_id`). گزارش‌ها از طریق `GET /api/v1/admin/financial-breakdowns` و `GET /api/v1/admin/financial-summary` در دسترس‌اند — جزئیات در `docs/api/admin.md`.