# 📄 Leave Management API Documentation
## Flutter App Integrated with Odoo

---

## 1. Overview

This document describes the **Leave Request API** used by a **Flutter mobile application** integrated with **:Odoo**.

> Authentication and employee profile are handled in a **separate existing document**.

The API allows employees to:
- View leave types with balances
- Submit leave requests (days or hours)
- Track request status
- Cancel requests when allowed

---

## 2. Business Rules

1. Each employee has a dedicated leave record.
2. Each employee may have multiple leave types.
3. Leave types can be:
- Limited by balance
- Unlimited
4. Leave requests can be submitted:
- By days
- By hours
5. Leave requests follow a predefined approval workflow.

---

## 3. Core Entities

---

### 3.1 Leave Type (With Balance)

Leave balance is returned **directly with leave types**.

| Field | Type | Description |
|----|----|----|
| id | Integer | Leave type ID |
| name | String | Leave type name |
| request_unit | Enum | `day` or `hour` |
| has_limit | Boolean | Balance limited or not |
| remaining | Float | Remaining balance |

> If `has_limit = false`, balance fields will be `null`.

---

### 3.2 Leave Request

| Field | Type |
|----|----|
| id | Integer |
| leave_type_id | Integer |
| date_from | Date |
| date_to | Date |
| hour_from | Time |
| hour_to | Time |
| duration | Float |
| state | Enum |
| reason | String |
| create_date | Datetime |

---

## 4. Leave Request States

The leave request follows the below workflow states:

| State Key | Label | Description |
|---------|-------|------------|
| draft | To Submit | Request is created but not yet submitted |
| confirm | To Approve | Request has been submitted and is waiting for approval |
| cto_approve | First Approval | First-level approval (e.g. Direct Manager) |
| validate1 | Second Approval | Second-level approval (e.g. HR) |
| validate | Approved | Final approved state |
| refuse | Refused | Request has been rejected |

---

### Workflow Notes

- Requests start in `draft`
- After submission, state becomes `confirm`
- Multi-level approval is supported:
- `cto_approve` → First approval
- `validate1` → Second approval
- Final approval state is `validate`
- Rejected requests move to `refuse`

---

## 5. API Endpoints

> All endpoints require a valid Authorization token
> (Defined in the authentication document)

| # | API | Method | Description |
|--|----|------|------------|
| 1 | /api/leaves/types | GET | Get leave types with balances |
| 2 | /api/leaves/request | POST | Create leave request (day/hour) |
| 3 | /api/leaves/my_requests | GET | Get leave requests list (pagination + search) |
| 4 | /api/leaves/cancel | POST | Cancel leave request |

---

### 5.1 Get Leave Types With Balances

#### Response

[
  {
    "id": 1,
    "name": "Annual Leave",
    "request_unit": "day",
    "has_limit": true, 
    "remaining": 12
  },
  {
    "id": 2,
    "name": "Hourly Permission",
    "request_unit": "hour",
    "has_limit": false, 
    "remaining": null
  }
]

### 5.2 Create Leave Request (Unified Endpoint)
POST /api/leaves/request
This endpoint supports day-based and hour-based leave requests.

#### Request – Day Based

{
    "leave_type_id": 1,
    "date_from": "2026-03-01",
    "date_to": "2026-03-03",
    "hour_from": null,
    "hour_to": null,
    "reason": "Family vacation"
}

#### Request – Hour Based

{
    "leave_type_id": 1,
    "date_from": "2026-03-01",
    "date_to": null,
    "hour_from": "09:00",
    "hour_to": "12:00",
    "reason": "Personal permission",
}

#### Response

{
  "success": true,
  "request_id": 88,
  "state": "confirm"
}

### 5.3 Get Leave Requests List (With Pagination & Search)

GET /api/leaves/my_requests?skip=0&take=10&search=annual

#### Response

{
    "success": true,
    "count": 1,
    "data": [
    {
      "id": 88,
      "leave_type": "Annual Leave",
      "request_unit": "day",
      "date_from": "2026-03-01",
      "date_to": "2026-03-03",
      "hour_from": "09:00",
      "hour_to": "12:00",
      "duration": 3,
      "state": "validate",
      "state_label": "Approved"
    }
  ]
}

### 5.3 Cancel Leave Request
POST /api/leaves/cancel

#### Request

{
  "request_id": 88
}

#### Response

{
  "success": true,
  "message": "Leave request cancelled successfully"
}

## 6. Validation Rules

- Leave type must exist
- Date range must be valid
- If leave has limited balance → remaining balance must be sufficient
- Approved or refused requests cannot be cancelled
- Hour-based requests must respect working hours

---

## 7. Error Response Format

{
  "success": false,
  "message": "Insufficient leave balance"
}

## 8. HTTP Status Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Validation error |
| 401 | Unauthorized |
| 403 | Forbidden |
| 500 | Server error |

---

## 9. Notes

- Pagination is handled using `skip` and `take`
- Search is applied on leave type name, state, and reason
- Leave balances are calculated dynamically from Odoo
- API responses are optimized for Flutter consumption