root/New-Thanasoft
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
New-Thanasoft/thanasoft-back/API_DOCUMENTATION.md
Nyavokevin e55cc5253e add back:
2025-11-05 17:09:12 +03:00

19 KiB
Raw Blame History

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):

{
    "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:

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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:

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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):

{
    "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

{
    "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:

{
    "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.