268 lines
5.5 KiB
Markdown
268 lines
5.5 KiB
Markdown
# Insurance API
|
|
|
|
> **Prefix:** `/api/v1/insurances`, `/api/v1/insurance`, `/api/v1/admin/insurance`
|
|
|
|
Two resource types:
|
|
1. **Insurance** — master list of insurance companies managed by admin
|
|
2. **DoctorInsurance** — a doctor's acceptance of a specific insurance (with optional price)
|
|
|
|
---
|
|
|
|
## GET `/api/v1/insurances`
|
|
|
|
List all active insurances.
|
|
|
|
**Permission:** `PUBLIC`
|
|
|
|
### Query Parameters
|
|
| Param | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `type` | string | ❌ | `"basic"` or `"supplementary"` |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"name": "بیمه تأمین اجتماعی",
|
|
"type": "basic",
|
|
"logo_url": "https://...",
|
|
"status": "active"
|
|
},
|
|
{
|
|
"id": 2,
|
|
"name": "بیمه ایران",
|
|
"type": "supplementary",
|
|
"logo_url": "https://...",
|
|
"status": "active"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## GET `/api/v1/admin/insurances`
|
|
|
|
List all insurances 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 |
|
|
| `type` | string | ❌ | `"basic"` or `"supplementary"` |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": [ ... ],
|
|
"meta": { "totalRecords": 15, "totalPages": 1, "currentPage": 1 }
|
|
}
|
|
```
|
|
|
|
### Errors
|
|
| Code | HTTP | Description |
|
|
|------|------|-------------|
|
|
| `ERR_AUTH_001` | 401 | Missing token |
|
|
| `ERR_AUTH_006` | 403 | Not admin |
|
|
|
|
---
|
|
|
|
## POST `/api/v1/admin/insurance`
|
|
|
|
Create a new insurance.
|
|
|
|
**Permission:** `ROLE_ADMIN`
|
|
|
|
### Request Body (`application/json`)
|
|
```json
|
|
{
|
|
"name": "بیمه تأمین اجتماعی",
|
|
"type": "basic",
|
|
"logo_url": "https://...",
|
|
"status": "active"
|
|
}
|
|
```
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `name` | string | ✅ | Insurance name |
|
|
| `type` | string | ✅ | `"basic"` or `"supplementary"` |
|
|
| `logo_url` | string | ❌ | Logo image URL |
|
|
| `status` | string | ❌ | `"active"` (default) or `"inactive"` |
|
|
|
|
### Response `201`
|
|
Insurance object.
|
|
|
|
### Errors
|
|
| Code | HTTP | Description |
|
|
|------|------|-------------|
|
|
| `ERR_AUTH_001` | 401 | Missing token |
|
|
| `ERR_AUTH_006` | 403 | Not admin |
|
|
| `ERR_VALIDATION_002` | 422 | Missing required field |
|
|
|
|
---
|
|
|
|
## PATCH `/api/v1/admin/insurance/{id}`
|
|
|
|
Update an insurance.
|
|
|
|
**Permission:** `ROLE_ADMIN`
|
|
|
|
### Path Parameters
|
|
| Param | Type | Description |
|
|
|-------|------|-------------|
|
|
| `id` | integer | Insurance ID |
|
|
|
|
All body fields optional.
|
|
|
|
### Response `200`
|
|
Updated insurance object.
|
|
|
|
### Errors
|
|
| Code | HTTP | Description |
|
|
|------|------|-------------|
|
|
| `ERR_AUTH_001` | 401 | Missing token |
|
|
| `ERR_AUTH_006` | 403 | Not admin |
|
|
| `ERR_NOT_FOUND_001` | 404 | Insurance not found |
|
|
|
|
---
|
|
|
|
## DELETE `/api/v1/admin/insurance/{id}`
|
|
|
|
Delete an insurance.
|
|
|
|
**Permission:** `ROLE_ADMIN`
|
|
|
|
### Response `200`
|
|
```json
|
|
{ "success": true, "data": { "message": "بیمه حذف شد" } }
|
|
```
|
|
|
|
---
|
|
|
|
## POST `/api/v1/admin/insurance/{id}/upload-logo`
|
|
|
|
Upload insurance logo.
|
|
|
|
**Permission:** `ROLE_ADMIN`
|
|
|
|
### Request
|
|
`Content-Type: multipart/form-data`
|
|
|
|
| Field | Type | Required |
|
|
|-------|------|----------|
|
|
| `file` | binary | ✅ |
|
|
|
|
### Response `200`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"url": "https://...",
|
|
"uuid": "...",
|
|
"filename": "insurance_logo.png",
|
|
"filemime": "image/png",
|
|
"filesize": 51200
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## POST `/api/v1/insurance/`
|
|
|
|
Add an insurance to a doctor's accepted list.
|
|
|
|
**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.create` permission)
|
|
|
|
### Request Body (`application/json`)
|
|
```json
|
|
{
|
|
"doctor_id": 42,
|
|
"insurance_id": 1,
|
|
"price": 150000
|
|
}
|
|
```
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `doctor_id` | integer | ✅ | Doctor's numeric ID |
|
|
| `insurance_id` | integer | ✅ | Insurance ID |
|
|
| `price` | integer | ❌ | Visit price for this insurance (Rials) |
|
|
|
|
### Response `201`
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"id": 10,
|
|
"doctor_id": 42,
|
|
"insurance": { "id": 1, "name": "بیمه تأمین اجتماعی", "type": "basic" },
|
|
"price": 150000
|
|
}
|
|
}
|
|
```
|
|
|
|
### Errors
|
|
| Code | HTTP | Description |
|
|
|------|------|-------------|
|
|
| `ERR_AUTH_001` | 401 | Missing token |
|
|
| `ERR_FORBIDDEN_001` | 403 | Not the doctor |
|
|
| `ERR_NOT_FOUND_001` | 404 | Doctor or insurance not found |
|
|
| `ERR_CONFLICT_001` | 409 | Insurance already added to doctor |
|
|
|
|
---
|
|
|
|
## GET `/api/v1/insurance/{id}`
|
|
|
|
Get a doctor-insurance link.
|
|
|
|
**Permission:** `PUBLIC`
|
|
|
|
### Response `200`
|
|
DoctorInsurance object.
|
|
|
|
---
|
|
|
|
## PATCH `/api/v1/insurance/{id}`
|
|
|
|
Update a doctor-insurance (e.g., change price).
|
|
|
|
**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.update` permission)
|
|
|
|
### Request Body
|
|
```json
|
|
{ "price": 200000 }
|
|
```
|
|
|
|
### Response `200`
|
|
Updated DoctorInsurance object.
|
|
|
|
### Errors
|
|
| Code | HTTP | Description |
|
|
|------|------|-------------|
|
|
| `ERR_AUTH_001` | 401 | Missing token |
|
|
| `ERR_FORBIDDEN_001` | 403 | Not the doctor |
|
|
| `ERR_NOT_FOUND_001` | 404 | Link not found |
|
|
|
|
---
|
|
|
|
## DELETE `/api/v1/insurance/{id}`
|
|
|
|
Remove an insurance from a doctor's list.
|
|
|
|
**Permission:** `AUTH` — must be the doctor (or their secretary with `insurances.delete` permission)
|
|
|
|
### Response `200`
|
|
```json
|
|
{ "success": true, "data": { "message": "بیمه از لیست حذف شد" } }
|
|
```
|