nhance/docs/dependent-approval-apis.md

# Dependent Approval APIs

Base path: `/employeeRest/`

Auth: JWT + App-Signature (`authJWT`, `appSignature`)

---

## 1. Get Employee Policy (Dependent Add UI)

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `/employeeRest/getEmployeePolicy` |
| **Handler** | `EmployeeRestController::getEmployeeByPolicyv2` |

> **Note:** Route currently maps to `getEmployeePolicyv2` (method missing). Intended handler is `getEmployeeByPolicyv2`.

### Query Params

| Param | Required | Description |
|---|---|---|
| `id` | Yes | Self employee id |
| `emp_code` | Yes | Employee code |
| `client_id` | Yes | Client id |
| `client_branch_id` | Yes | Branch id |
| `client_policy_id` | Yes | GMC client policy id |

### Success Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Employee policy and dependent details fetched successfully",
  "data": {
    "...": "policy details, mapped_family_floaters, allowed_relationships"
  },
  "EmployeePolicy": [],
  "add_button_show": true
}
```

### Error Responses

| code | message |
|---|---|
| 400 | Required parameters missing |
| 400 | Only GMC policy is supported for dependent add |
| 404 | Employee policy not found |
| 500 | Something went wrong while fetching employee policy details |

---

## 2. Add / Update Dependent (Pending Approval)

| | |
|---|---|
| **Method** | `POST` |
| **URL** | `/employeeRest/addEmployeeAndDependence` |
| **Handler** | `EmployeeRestController::addEmployeeAndDependencev2` |
| **Content-Type** | `application/json` |

### Request Body

JSON **array** of dependent objects:

```json
[
  {
    "emp_code": "E001",
    "client_id": 10,
    "client_branch_id": 5,
    "client_policy_id": 100,
    "name": "John Doe",
    "relationship": "Spouse",
    "dob": "01/01/1990",
    "basic_cover_si": 500000,
    "dependent_effective_date": "01/08/2026",
    "hr_id": 12
  }
]
```

### Fields

| Field | Required | Notes |
|---|---|---|
| `emp_code` | Yes | Parent employee code |
| `client_id` | Yes | Client id |
| `client_branch_id` | Yes | Used for premium update |
| `client_policy_id` | Yes | Client policy id |
| `name` | Yes | Dependent name |
| `relationship` | Yes | e.g. Spouse / Son / Daughter |
| `dob` | Yes | Converted to `Y-m-d` |
| `basic_cover_si` | Yes | Sum insured |
| `dependent_effective_date` | Yes (new) | Coverage start date |
| `hr_id` | No | If set → created by HR; else USER |
| `id` | No | If set → update existing dependent |

### Behavior

- Creates/updates dependent with `emp_status = pending_approval`
- Creates employee policy with `status = pending_approval`
- Recalculates premium for the family

### Success Response

```json
{
  "status": "success",
  "code": 200,
  "data": []
}
```

### Error Responses

| code | data |
|---|---|
| 404 | Requested parameters are required |
| 404 | No Matches |
| 500 | Exception message |

---

## 3. Delete Dependent

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `/employeeRest/deleteDependence` |
| **Handler** | `EmployeeRestController::deleteDependencev2` |

### Query Params

| Param | Required | Description |
|---|---|---|
| `id` | Yes | Dependent employee id |

### Behavior

Soft-deletes employee and policy:

- `emp_status` / `status` → `truncated`
- `is_active` → `0`

### Success Response

```json
{
  "status": "success",
  "code": 200,
  "data": []
}
```

### Error Responses

| code | data |
|---|---|
| 404 | `[]` (missing `id`) |
| 500 | Exception message |

---

## 4. List Pending Approval Dependents

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `/employeeRest/getPendingApprovalDependents` |
| **Handler** | `EmployeeRestController::getPendingApprovalDependents` |

### Query Params

| Param | Required | Description |
|---|---|---|
| `client_id` | No | Client filter |
| `client_branch_id` / `branch_id` | No | Branch filter |
| `client_policy_id` / `policy_id` | No | Policy filter |
| `search` | No | Name / emp_code search |

### Success Response

```json
{
  "status": "success",
  "code": 200,
  "message": "Pending approval dependents fetched successfully",
  "data": []
}
```

### Error Responses

| code | message |
|---|---|
| 404 | No pending approval dependents found |
| 500 | Exception message |

---

## 5. Approve / Reject Dependent

| | |
|---|---|
| **Method** | `POST` |
| **URL** | `/employeeRest/processDependentAdd` |
| **Handler** | `EmployeeRestController::processDependentAdd` |
| **Content-Type** | `application/json` |

### Request Body

```json
{
  "employee_id": 123,
  "client_policy_id": 100,
  "status": "approved",
  "hr_id": 12
}
```

### Fields

| Field | Required | Notes |
|---|---|---|
| `employee_id` | Yes | Dependent employee id |
| `client_policy_id` | Yes | Policy id |
| `status` | Yes | `approved` or `rejected` (default: `approved`) |
| `hr_id` | No | If set → approved by HR; else ACM |

### Behavior

| status | Employee | Policy |
|---|---|---|
| `approved` | `emp_status = active` | `status = active` |
| `rejected` | `emp_status = rejected`, `is_active = 0` | `status = rejected`, `is_active = 0` |

### Success Response

```json
{
  "status": "success",
  "code": 200,
  "data": []
}
```

### Error Responses

| code | data |
|---|---|
| 400 | Request body is required |
| 400 | employee_id is required |
| 400 | client_policy_id is required |
| 400 | status is invalid |
| 400 | Dependent is already approved |
| 400 | Dependent is not pending approval |
| 404 | Employee not found or inactive |
| 404 | Employee policy not found or inactive |
| 500 | Failed to update employee/policy status |

---

## Typical Flow

```
1. getEmployeePolicy
      → show family slots / add buttons

2. addEmployeeAndDependence
      → submit dependent → pending_approval

3. getPendingApprovalDependents
      → HR / ACM review list

4. processDependentAdd
      → approve or reject

5. deleteDependence
      → soft-delete if needed
```