# API Documentation - Employee Management System

## Overview

The ThanaSoft Employee Management System provides comprehensive RESTful API endpoints for managing employees, thanatopractitioners, and their associated documents. This system is built using Laravel and follows RESTful API conventions.

## Base URL

```
https://your-domain.com/api
```

## Authentication

All API endpoints require authentication using Laravel Sanctum. Include the token in the Authorization header:

```
Authorization: Bearer {your_token}
```

## Employee Management System

### Entities

1. **Employees** - Core employee records with personal information
2. **Thanatopractitioners** - Specialized practitioners linked to employees
3. **Practitioner Documents** - Documents associated with thanatopractitioners

---

## Employees API

### Base Endpoint

```
/employees
```

### Endpoints Overview

| Method | Endpoint                          | Description                                     |
| ------ | --------------------------------- | ----------------------------------------------- |
| GET    | `/employees`                      | List all employees with pagination              |
| POST   | `/employees`                      | Create a new employee                           |
| GET    | `/employees/{id}`                 | Get specific employee details                   |
| PUT    | `/employees/{id}`                 | Update employee information                     |
| DELETE | `/employees/{id}`                 | Delete an employee                              |
| GET    | `/employees/searchBy`             | Search employees by criteria                    |
| GET    | `/employees/thanatopractitioners` | Get all thanatopractitioners with employee info |

### 1. List All Employees

**GET** `/api/employees`

**Query Parameters:**

-   `page` (optional): Page number for pagination (default: 1)
-   `per_page` (optional): Items per page (default: 15, max: 100)
-   `search` (optional): Search term for name, email, or employee_number
-   `department` (optional): Filter by department
-   `status` (optional): Filter by employment status (active, inactive, terminated)

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "employee_number": "EMP001",
                "first_name": "Jean",
                "last_name": "Dupont",
                "email": "jean.dupont@thanasoft.com",
                "phone": "+261 34 12 345 67",
                "department": "Direction",
                "position": "Directeur Général",
                "hire_date": "2020-01-15",
                "status": "active",
                "created_at": "2025-11-05T10:30:00.000000Z",
                "updated_at": "2025-11-05T10:30:00.000000Z"
            }
        ],
        "current_page": 1,
        "per_page": 15,
        "total": 25,
        "last_page": 2
    },
    "message": "Employés récupérés avec succès"
}
```

### 2. Create Employee

**POST** `/api/employees`

**Request Body:**

```json
{
    "employee_number": "EMP026",
    "first_name": "Jean",
    "last_name": "Dupont",
    "email": "jean.dupont@thanasoft.com",
    "phone": "+261 34 12 345 67",
    "address": "123 Rue de la Liberté, Antananarivo",
    "birth_date": "1985-06-15",
    "gender": "male",
    "department": "Direction",
    "position": "Directeur Général",
    "hire_date": "2025-11-05",
    "salary": 2500000,
    "status": "active"
}
```

**Success Response (201):**

```json
{
    "success": true,
    "data": {
        "id": 26,
        "employee_number": "EMP026",
        "first_name": "Jean",
        "last_name": "Dupont",
        "email": "jean.dupont@thanasoft.com",
        "phone": "+261 34 12 345 67",
        "address": "123 Rue de la Liberté, Antananarivo",
        "birth_date": "1985-06-15",
        "gender": "male",
        "department": "Direction",
        "position": "Directeur Général",
        "hire_date": "2025-11-05",
        "salary": 2500000,
        "status": "active",
        "created_at": "2025-11-05T12:16:05.000000Z",
        "updated_at": "2025-11-05T12:16:05.000000Z"
    },
    "message": "Employé créé avec succès"
}
```

**Validation Errors (422):**

```json
{
    "success": false,
    "message": "Les données fournies ne sont pas valides",
    "errors": {
        "email": ["L'adresse email doit être unique"],
        "employee_number": ["Le numéro d'employé est requis"]
    }
}
```

### 3. Get Employee Details

**GET** `/api/employees/{id}`

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "id": 1,
        "employee_number": "EMP001",
        "first_name": "Jean",
        "last_name": "Dupont",
        "email": "jean.dupont@thanasoft.com",
        "phone": "+261 34 12 345 67",
        "address": "123 Rue de la Liberté, Antananarivo",
        "birth_date": "1985-06-15",
        "gender": "male",
        "department": "Direction",
        "position": "Directeur Général",
        "hire_date": "2020-01-15",
        "salary": 2500000,
        "status": "active",
        "created_at": "2020-01-15T08:00:00.000000Z",
        "updated_at": "2025-11-05T10:30:00.000000Z"
    },
    "message": "Détails de l'employé récupérés avec succès"
}
```

### 4. Update Employee

**PUT** `/api/employees/{id}`

**Request Body:** Same as create, but all fields are optional.

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "id": 1,
        "employee_number": "EMP001",
        "first_name": "Jean",
        "last_name": "Dupont",
        "email": "jean.dupont@thanasoft.com",
        "phone": "+261 34 12 345 68",
        "department": "Direction",
        "position": "Directeur Général Adjoint",
        "updated_at": "2025-11-05T12:16:05.000000Z"
    },
    "message": "Employé mis à jour avec succès"
}
```

### 5. Search Employees

**GET** `/api/employees/searchBy`

**Query Parameters:**

-   `query` (required): Search term
-   `field` (optional): Field to search in (first_name, last_name, email, employee_number, department, position)

**Example:** `/api/employees/searchBy?query=jean&field=first_name`

**Success Response (200):**

```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "employee_number": "EMP001",
            "first_name": "Jean",
            "last_name": "Dupont",
            "email": "jean.dupont@thanasoft.com",
            "department": "Direction",
            "position": "Directeur Général"
        }
    ],
    "message": "Résultats de recherche récupérés avec succès"
}
```

---

## Thanatopractitioners API

### Base Endpoint

```
/thanatopractitioners
```

### Endpoints Overview

| Method | Endpoint                                       | Description                          |
| ------ | ---------------------------------------------- | ------------------------------------ |
| GET    | `/thanatopractitioners`                        | List all thanatopractitioners        |
| POST   | `/thanatopractitioners`                        | Create a new thanatopractitioner     |
| GET    | `/thanatopractitioners/{id}`                   | Get specific thanatopractitioner     |
| PUT    | `/thanatopractitioners/{id}`                   | Update thanatopractitioner           |
| DELETE | `/thanatopractitioners/{id}`                   | Delete thanatopractitioner           |
| GET    | `/employees/{employeeId}/thanatopractitioners` | Get thanatopractitioners by employee |

### 1. List All Thanatopractitioners

**GET** `/api/thanatopractitioners`

**Query Parameters:**

-   `page` (optional): Page number
-   `per_page` (optional): Items per page
-   `specialization` (optional): Filter by specialization

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "employee_id": 1,
                "specialization": "Thanatopraticien principal",
                "license_number": "TH001",
                "authorization_number": "AUTH001",
                "authorization_date": "2020-01-15",
                "authorization_expiry": "2025-01-15",
                "is_authorized": true,
                "created_at": "2020-01-15T08:00:00.000000Z",
                "updated_at": "2025-11-05T10:30:00.000000Z",
                "employee": {
                    "id": 1,
                    "first_name": "Jean",
                    "last_name": "Dupont",
                    "employee_number": "EMP001",
                    "department": "Direction"
                }
            }
        ],
        "current_page": 1,
        "per_page": 15,
        "total": 5,
        "last_page": 1
    },
    "message": "Thanatopraticiens récupérés avec succès"
}
```

### 2. Create Thanatopractitioner

**POST** `/api/thanatopractitioners`

**Request Body:**

```json
{
    "employee_id": 1,
    "specialization": "Thanatopraticien principal",
    "license_number": "TH001",
    "authorization_number": "AUTH001",
    "authorization_date": "2025-11-05",
    "authorization_expiry": "2026-11-05",
    "is_authorized": true
}
```

**Success Response (201):**

```json
{
    "success": true,
    "data": {
        "id": 6,
        "employee_id": 1,
        "specialization": "Thanatopraticien principal",
        "license_number": "TH001",
        "authorization_number": "AUTH001",
        "authorization_date": "2025-11-05",
        "authorization_expiry": "2026-11-05",
        "is_authorized": true,
        "created_at": "2025-11-05T12:16:05.000000Z",
        "updated_at": "2025-11-05T12:16:05.000000Z"
    },
    "message": "Thanatopraticien créé avec succès"
}
```

### 3. Get Thanatopractitioners by Employee

**GET** `/api/employees/{employeeId}/thanatopractitioners`

**Success Response (200):**

```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "specialization": "Thanatopraticien principal",
            "license_number": "TH001",
            "authorization_number": "AUTH001",
            "authorization_date": "2020-01-15",
            "authorization_expiry": "2025-01-15",
            "is_authorized": true
        }
    ],
    "message": "Thanatopraticiens de l'employé récupérés avec succès"
}
```

---

## Practitioner Documents API

### Base Endpoint

```
/practitioner-documents
```

### Endpoints Overview

| Method | Endpoint                               | Description                          |
| ------ | -------------------------------------- | ------------------------------------ |
| GET    | `/practitioner-documents`              | List all documents                   |
| POST   | `/practitioner-documents`              | Upload new document                  |
| GET    | `/practitioner-documents/{id}`         | Get specific document                |
| PUT    | `/practitioner-documents/{id}`         | Update document info                 |
| DELETE | `/practitioner-documents/{id}`         | Delete document                      |
| GET    | `/practitioner-documents/searchBy`     | Search documents                     |
| GET    | `/practitioner-documents/expiring`     | Get expiring documents               |
| GET    | `/thanatopractitioners/{id}/documents` | Get documents by thanatopractitioner |
| PATCH  | `/practitioner-documents/{id}/verify`  | Verify document                      |

### 1. List All Documents

**GET** `/api/practitioner-documents`

**Query Parameters:**

-   `page` (optional): Page number
-   `per_page` (optional): Items per page
-   `type` (optional): Filter by document type
-   `is_verified` (optional): Filter by verification status

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "data": [
            {
                "id": 1,
                "thanatopractitioner_id": 1,
                "document_type": "diplome",
                "file_name": "diplome_thanatopraticien.pdf",
                "file_path": "/documents/diplome_thanatopraticien.pdf",
                "issue_date": "2019-06-30",
                "expiry_date": "2024-06-30",
                "issuing_authority": "Ministère de la Santé",
                "is_verified": true,
                "verified_at": "2020-01-20T10:00:00.000000Z",
                "created_at": "2020-01-15T08:00:00.000000Z",
                "updated_at": "2020-01-20T10:00:00.000000Z"
            }
        ],
        "current_page": 1,
        "per_page": 15,
        "total": 12,
        "last_page": 1
    },
    "message": "Documents récupérés avec succès"
}
```

### 2. Upload Document

**POST** `/api/practitioner-documents`

**Form Data:**

```
thanatopractitioner_id: 1
document_type: diplome
file: [binary file data]
issue_date: 2019-06-30
expiry_date: 2024-06-30
issuing_authority: Ministère de la Santé
```

**Success Response (201):**

```json
{
    "success": true,
    "data": {
        "id": 13,
        "thanatopractitioner_id": 1,
        "document_type": "diplome",
        "file_name": "diplome_thanatopraticien_2025.pdf",
        "file_path": "/documents/diplome_thanatopraticien_2025.pdf",
        "issue_date": "2019-06-30",
        "expiry_date": "2024-06-30",
        "issuing_authority": "Ministère de la Santé",
        "is_verified": false,
        "created_at": "2025-11-05T12:16:05.000000Z",
        "updated_at": "2025-11-05T12:16:05.000000Z"
    },
    "message": "Document téléchargé avec succès"
}
```

### 3. Get Expiring Documents

**GET** `/api/practitioner-documents/expiring`

**Query Parameters:**

-   `days` (optional): Number of days to look ahead (default: 30)

**Success Response (200):**

```json
{
    "success": true,
    "data": [
        {
            "id": 5,
            "thanatopractitioner_id": 2,
            "document_type": "certificat",
            "file_name": "certificat_renouvellement.pdf",
            "expiry_date": "2025-11-20",
            "days_until_expiry": 15,
            "employee": {
                "first_name": "Marie",
                "last_name": "Rasoa",
                "employee_number": "EMP002"
            }
        }
    ],
    "message": "Documents expirants récupérés avec succès"
}
```

### 4. Verify Document

**PATCH** `/api/practitioner-documents/{id}/verify`

**Success Response (200):**

```json
{
    "success": true,
    "data": {
        "id": 13,
        "document_type": "diplome",
        "is_verified": true,
        "verified_at": "2025-11-05T12:20:00.000000Z"
    },
    "message": "Document vérifié avec succès"
}
```

---

## Data Models

### Employee Model

| Field             | Type    | Required | Description                                      |
| ----------------- | ------- | -------- | ------------------------------------------------ |
| `employee_number` | string  | Yes      | Unique employee identifier                       |
| `first_name`      | string  | Yes      | Employee's first name                            |
| `last_name`       | string  | Yes      | Employee's last name                             |
| `email`           | email   | Yes      | Unique email address                             |
| `phone`           | string  | No       | Phone number                                     |
| `address`         | text    | No       | Physical address                                 |
| `birth_date`      | date    | No       | Date of birth                                    |
| `gender`          | string  | No       | Gender (male, female, other)                     |
| `department`      | string  | No       | Department name                                  |
| `position`        | string  | No       | Job position                                     |
| `hire_date`       | date    | No       | Employment start date                            |
| `salary`          | decimal | No       | Monthly salary                                   |
| `status`          | string  | No       | Employment status (active, inactive, terminated) |

### Thanatopractitioner Model

| Field                  | Type    | Required | Description                    |
| ---------------------- | ------- | -------- | ------------------------------ |
| `employee_id`          | integer | Yes      | Foreign key to employees table |
| `specialization`       | string  | Yes      | Area of specialization         |
| `license_number`       | string  | Yes      | Professional license number    |
| `authorization_number` | string  | Yes      | Authorization number           |
| `authorization_date`   | date    | Yes      | Authorization issue date       |
| `authorization_expiry` | date    | Yes      | Authorization expiry date      |
| `is_authorized`        | boolean | Yes      | Authorization status           |

### Practitioner Document Model

| Field                    | Type      | Required | Description                               |
| ------------------------ | --------- | -------- | ----------------------------------------- |
| `thanatopractitioner_id` | integer   | Yes      | Foreign key to thanatopractitioners table |
| `document_type`          | string    | Yes      | Type of document                          |
| `file`                   | file      | Yes      | Document file upload                      |
| `issue_date`             | date      | No       | Document issue date                       |
| `expiry_date`            | date      | No       | Document expiry date                      |
| `issuing_authority`      | string    | No       | Authority that issued the document        |
| `is_verified`            | boolean   | Yes      | Verification status                       |
| `verified_at`            | timestamp | No       | Verification timestamp                    |

---

## Error Handling

### HTTP Status Codes

-   `200` - Success
-   `201` - Created successfully
-   `400` - Bad Request
-   `401` - Unauthorized
-   `403` - Forbidden
-   `404` - Resource not found
-   `422` - Validation error
-   `500` - Internal server error

### Error Response Format

```json
{
    "success": false,
    "message": "Description of the error",
    "errors": {
        "field_name": ["Error message for this field"]
    }
}
```

---

## File Upload

For document uploads, use multipart/form-data:

```
POST /api/practitioner-documents
Content-Type: multipart/form-data

{
    "thanatopractitioner_id": 1,
    "document_type": "diplome",
    "file": [binary file],
    "issue_date": "2019-06-30",
    "expiry_date": "2024-06-30",
    "issuing_authority": "Ministère de la Santé"
}
```

---

## Pagination

All list endpoints support pagination with the following query parameters:

-   `page`: Page number (default: 1)
-   `per_page`: Items per page (default: 15, max: 100)

Response includes pagination metadata:

```json
{
    "current_page": 1,
    "per_page": 15,
    "total": 50,
    "last_page": 4,
    "from": 1,
    "to": 15
}
```

---

## Rate Limiting

API requests are rate limited to 1000 requests per hour per authenticated user. Exceeding this limit will result in a `429 Too Many Requests` response.

---

## Support

For API support or questions, please contact the development team or refer to the Laravel documentation at https://laravel.com/docs.