# 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": "بیمه از لیست حذف شد" } }
```