188 lines
4.3 KiB
Markdown
188 lines
4.3 KiB
Markdown
# 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.
|