hamed
5c4976d65f
- Added SecretaryAccessChecker to manage resource access for secretaries. - Integrated permission checks for payments, inventory, and tags in relevant controllers. - Updated PaymentController and PaymentMethodController to enforce secretary permissions. - Enhanced TenantTagController to check permissions for tag management actions. - Introduced tests for secretary resource enforcement, ensuring proper access control. - Updated DoctorSecretary entity to include inventory and tags permissions. - Created a comprehensive audit document for secretary permissions coverage and enforcement. - Fixed potential crashes in SecretaryDashboard when rendering without doctor data.
160 lines
4.0 KiB
Markdown
160 lines
4.0 KiB
Markdown
# Payment Methods API
|
|
|
|
> **Prefix:** `/api/v1/my/payment-methods`
|
|
|
|
Per-clinic payment methods managed from the settings screen (`/admin/my-financial`,
|
|
tab "مدیریت پرداخت"). Two resources: **bank accounts** and **POS (card reader) devices**.
|
|
|
|
> **دسترسی منشی:** روشهای پرداخت زیرمجموعهٔ منبع `payments` هستند. برای `ROLE_SECRETARY` (`SecretaryAccessChecker`): GET→`payments.view`, POST→`payments.create`, PUT/PATCH→`payments.update`؛ نبودِ مجوز یا رابطهٔ فعال → `403`. جزئیات: [secretary.md](secretary.md).
|
|
Records are stored so a patient invoice can later reference which account/device a
|
|
service payment was made to.
|
|
|
|
All endpoints are scoped to the acting user — a clinic never sees another's records.
|
|
|
|
**Permission:** authenticated user with one of `ROLE_CLINIC`, `ROLE_DOCTOR`,
|
|
`ROLE_SECRETARY`, `ROLE_ADMIN` (otherwise `403 ERR_FORBIDDEN_001`).
|
|
|
|
---
|
|
|
|
## Bank accounts
|
|
|
|
### GET `/api/v1/my/payment-methods/bank-accounts`
|
|
|
|
List the current clinic's bank accounts (newest first).
|
|
|
|
#### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"uuid": "b1e0...-...",
|
|
"bank_name": "ملی",
|
|
"card_number": "6037991234567890",
|
|
"account_number": "0101234567890",
|
|
"shaba_number": "IR820540102680020817909002",
|
|
"is_active": true,
|
|
"created_at": 1752566400
|
|
}
|
|
]
|
|
}
|
|
```
|
|
Empty list returns `"data": []`.
|
|
|
|
---
|
|
|
|
### POST `/api/v1/my/payment-methods/bank-accounts`
|
|
|
|
Create a bank account.
|
|
|
|
#### Body
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `bank_name` | string | ✅ | Bank name |
|
|
| `account_number` | string | ✅ | Account number |
|
|
| `card_number` | string | ❌ | Card number |
|
|
| `shaba_number` | string | ❌ | IBAN / SHABA |
|
|
|
|
#### Response `201`
|
|
Single created record (same shape as list item).
|
|
|
|
#### Errors
|
|
- `422 ERR_VALIDATION_001` — `bank_name` or `account_number` missing (`field` set).
|
|
|
|
---
|
|
|
|
### PUT `/api/v1/my/payment-methods/bank-accounts/{uuid}`
|
|
|
|
Update a bank account. Any subset of the create fields may be sent; only provided
|
|
keys change. Empty `bank_name`/`account_number` → `422`.
|
|
|
|
#### Response `200`
|
|
Updated record.
|
|
|
|
#### Errors
|
|
- `404 ERR_NOT_FOUND_001` — uuid unknown or owned by another clinic.
|
|
- `422 ERR_VALIDATION_001` — provided `bank_name`/`account_number` empty.
|
|
|
|
---
|
|
|
|
### PATCH `/api/v1/my/payment-methods/bank-accounts/{uuid}/status`
|
|
|
|
Toggle `is_active` (active ⇄ inactive). No body.
|
|
|
|
#### Response `200`
|
|
Record with flipped `is_active`.
|
|
|
|
#### Errors
|
|
- `404 ERR_NOT_FOUND_001` — uuid unknown or not owned.
|
|
|
|
---
|
|
|
|
## POS devices
|
|
|
|
### GET `/api/v1/my/payment-methods/pos`
|
|
|
|
List the current clinic's card reader devices (newest first).
|
|
|
|
#### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"uuid": "c2f1...-...",
|
|
"bank_name": "ملت",
|
|
"serial_number": "SN-98765",
|
|
"terminal_number": "123456",
|
|
"account_number": null,
|
|
"is_active": true,
|
|
"created_at": 1752566400
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### POST `/api/v1/my/payment-methods/pos`
|
|
|
|
Create a POS device.
|
|
|
|
#### Body
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `bank_name` | string | ✅ | Bank name |
|
|
| `terminal_number` | string | ✅ | Terminal number |
|
|
| `serial_number` | string | ❌ | Device serial number |
|
|
| `account_number` | string | ❌ | Linked account number |
|
|
|
|
#### Response `201`
|
|
Single created record.
|
|
|
|
#### Errors
|
|
- `422 ERR_VALIDATION_001` — `bank_name` or `terminal_number` missing (`field` set).
|
|
|
|
---
|
|
|
|
### PUT `/api/v1/my/payment-methods/pos/{uuid}`
|
|
|
|
Update a POS device. Partial update; empty `bank_name`/`terminal_number` → `422`.
|
|
|
|
#### Response `200`
|
|
Updated record.
|
|
|
|
#### Errors
|
|
- `404 ERR_NOT_FOUND_001` — uuid unknown or not owned.
|
|
- `422 ERR_VALIDATION_001` — provided `bank_name`/`terminal_number` empty.
|
|
|
|
---
|
|
|
|
### PATCH `/api/v1/my/payment-methods/pos/{uuid}/status`
|
|
|
|
Toggle `is_active`. No body.
|
|
|
|
#### Response `200`
|
|
Record with flipped `is_active`.
|
|
|
|
#### Errors
|
|
- `404 ERR_NOT_FOUND_001` — uuid unknown or not owned.
|