clinicpro/docs/api/insurance.md

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

{
  "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

{
  "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)

{
  "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

{ "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

{
  "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)

{
  "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

{
  "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

{ "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

{ "success": true, "data": { "message": "بیمه از لیست حذف شد" } }