657 lines
19 KiB
Markdown
657 lines
19 KiB
Markdown
# 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.
|