# Download Inception API

Base path: `/employeeRest`

Generates an Excel (`.xlsx`) export of **enrolled** employees for the selected client, branch, and policy. The API returns a download URL; the file is fetched in a second request.

**Authentication:** JWT + app signature (same filters as other `employeeRest` routes)

**HTTP status:** Responses use HTTP `200` (or `500` on unhandled exceptions). Check JSON `status` and `code` for success or failure.

---

## Endpoints

| Route | Method | Description |
|-------|--------|-------------|
| `/employeeRest/download_inception` | `POST` | Generate Excel export |
| `/employeeRest/download_file?file={filename}` | `GET` | Download generated file |

---

## 1. Generate inception export

| | |
|---|---|
| **Method** | `POST` |
| **URL** | `/employeeRest/download_inception` |
| **Content-Type** | `application/json` **or** `application/x-www-form-urlencoded` |

### Request body

| Field | Required | Type | Description |
|-------|----------|------|-------------|
| `client` | No | integer / string | Client ID (or MD5 client hash) |
| `branch` | No | integer | Client branch ID |
| `policies` | No | integer | Client policy ID |
| `status` | No | array / string | Accepted in payload; export currently uses **enrolled** status only |
| `empCode` | No | string | Filter by employee code |
| `empName` | No | string | Filter by employee name (partial match) |

### Sample request (JSON)

```http
POST /employeeRest/download_inception
Content-Type: application/json
Authorization: Bearer {token}

{
  "client": 12,
  "branch": 1,
  "policies": 12,
  "status": ["enrolled"],
  "empCode": "",
  "empName": ""
}
```

### Sample request (form)

```http
POST /employeeRest/download_inception
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {token}

client=12&branch=1&policies=12&empCode=&empName=
```

### Success response

```json
{
  "status": true,
  "code": 200,
  "message": "Inception export generated successfully.",
  "data": {
    "downloadUrl": "https://example.com/employeeRest/download_file?file=inception_export_20260625_121435.xlsx",
    "filename": "inception_export_20260625_121435.xlsx",
    "rowCount": 9
  }
}
```

### Error responses

**Invalid JSON**

```json
{
  "status": false,
  "code": 400,
  "message": "Invalid JSON request body.",
  "data": []
}
```

**No data**

```json
{
  "status": false,
  "code": 404,
  "message": "No data found for given filters.",
  "data": []
}
```

**Export / server error**

```json
{
  "status": false,
  "code": 500,
  "message": "Failed to generate inception export.",
  "data": []
}
```

---

## 2. Download file

After a successful export, download the file using `data.downloadUrl`.

```http
GET /employeeRest/download_file?file=inception_export_20260625_121435.xlsx
Authorization: Bearer {token}
```

| Query param | Required | Description |
|-------------|----------|-------------|
| `file` | Yes | Filename from the generate response (`data.filename`) |

Returns the `.xlsx` file as a download. Only the basename is allowed (path traversal is blocked).

---

## Excel columns

Each row includes (with `S.NO` as the first column):

| Column | Source |
|--------|--------|
| S.NO | Row index |
| Emp ID | Employee code |
| Name of Emp/Dep | Employee / dependent name |
| DOB | Date of birth |
| Gender | Gender |
| Relationship | Relationship |
| Basic cover SI | Sum insured |
| Date of Coverage | Coverage date |
| DOJ | Date of joining |
| Basic Pay | Basic pay |
| Band/Grade | Band / grade |
| Designation | Designation |
| Phone | Mobile |
| Email | Corporate email |
| PRE EXISTING AILMENTS | Pre-existing flag |
| change_event | Change event |
| date_of_exit | Exit date |
| reason_for_exit | Exit reason |
| unit | Unit |

Only **active** employees with **enrolled** policy status are included.

---

## Flow

```mermaid
sequenceDiagram
    participant Client
    participant API as employeeRest/download_inception
    participant Storage as writable/exports

    Client->>API: POST filters (client, branch, policies, ...)
    API->>Storage: Save inception_export_*.xlsx
    API-->>Client: JSON with downloadUrl + filename
    Client->>API: GET employeeRest/download_file?file=...
    API-->>Client: Excel file download
```

---

## Notes

- Files are stored under `writable/exports/` and named `inception_export_{Ymd_His}.xlsx`.
- Use the returned `downloadUrl` promptly; files may be removed by other processes.