New-Thanasoft/thanasoft-back/FILE_API_DOCUMENTATION.md

File Management API Documentation

Overview

The File Management API provides a complete CRUD system for handling file uploads with organized storage, metadata management, and file organization by categories and clients.

Base URL

/api/files

Authentication

All file routes require authentication using Sanctum tokens.

File Organization Structure

Files are automatically organized in storage following this structure:

storage/app/public/
├── client/{client_id}/{category}/{subcategory}/filename.pdf
├── client/{client_id}/devis/DEVIS_2024_12_01_10_30_45.pdf
├── client/{client_id}/facture/FACT_2024_12_01_10_30_45.pdf
└── general/{category}/{subcategory}/filename.pdf

Supported Categories

• devis - Quotes/Devis
• facture - Invoices/Factures
• contrat - Contracts
• document - General Documents
• image - Images
• autre - Other files

Endpoints Overview

1. List All Files

GET /api/files

Parameters:

• per_page (optional): Number of files per page (default: 15)
• search (optional): Search by filename
• mime_type (optional): Filter by MIME type
• uploaded_by (optional): Filter by uploader user ID
• category (optional): Filter by category
• client_id (optional): Filter by client ID
• date_from (optional): Filter files uploaded after date (YYYY-MM-DD)
• date_to (optional): Filter files uploaded before date (YYYY-MM-DD)
• sort_by (optional): Sort field (default: uploaded_at)
• sort_direction (optional): Sort direction (default: desc)

Response:

{
    "data": [
        {
            "id": 1,
            "file_name": "document.pdf",
            "mime_type": "application/pdf",
            "size_bytes": 1024000,
            "size_formatted": "1000.00 KB",
            "extension": "pdf",
            "storage_uri": "client/123/devis/DEVIS_2024_12_01_10_30_45.pdf",
            "organized_path": "client/123/devis/DEVIS_2024_12_01_10_30_45.pdf",
            "sha256": "abc123...",
            "uploaded_by": 1,
            "uploader_name": "John Doe",
            "uploaded_at": "2024-12-01 10:30:45",
            "is_image": false,
            "is_pdf": true,
            "category": "devis",
            "subcategory": "general"
        }
    ],
    "pagination": {
        "current_page": 1,
        "from": 1,
        "last_page": 5,
        "per_page": 15,
        "to": 15,
        "total": 75,
        "has_more_pages": true
    },
    "summary": {
        "total_files": 15,
        "total_size": 15360000,
        "total_size_formatted": "14.65 MB",
        "categories": {
            "devis": {
                "count": 8,
                "total_size_formatted": "8.24 MB"
            },
            "facture": {
                "count": 7,
                "total_size_formatted": "6.41 MB"
            }
        }
    }
}

2. Upload File

POST /api/files

Content-Type: multipart/form-data

Parameters:

• file (required): The file to upload (max 10MB)
• file_name (optional): Custom filename (uses original name if not provided)
• category (required): File category (devis|facture|contrat|document|image|autre)
• client_id (optional): Associated client ID
• subcategory (optional): Subcategory for better organization
• description (optional): File description (max 500 chars)
• tags (optional): Array of tags (max 10 tags, 50 chars each)
• is_public (optional): Whether file is publicly accessible

Example Request:

curl -X POST \
  http://localhost/api/files \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/document.pdf" \
  -F "category=devis" \
  -F "client_id=123" \
  -F "subcategory=annual" \
  -F "description=Annual quote for client" \
  -F 'tags[]=quote' \
  -F 'tags[]=annual'

Success Response (201):

{
    "data": {
        "id": 1,
        "file_name": "document.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 1024000,
        "storage_uri": "client/123/devis/annual/document_2024_12_01_10_30_45.pdf",
        "category": "devis",
        "subcategory": "annual",
        "uploaded_at": "2024-12-01 10:30:45"
    },
    "message": "Fichier téléchargé avec succès."
}

3. Get File Details

GET /api/files/{id}

Response: Same as file object in list endpoint

4. Update File Metadata

PUT /api/files/{id}

Parameters:

• file_name (optional): New filename
• description (optional): Updated description
• tags (optional): Updated tags array
• is_public (optional): Updated public status
• category (optional): Move to new category
• client_id (optional): Change associated client
• subcategory (optional): Update subcategory

Note: If category, client_id, or subcategory are changed, the file will be automatically moved to the new location.

5. Delete File

DELETE /api/files/{id}

Response:

{
    "message": "Fichier supprimé avec succès."
}

6. Get Files by Category

GET /api/files/by-category/{category}

Parameters: Same as list endpoint with additional per_page

7. Get Files by Client

GET /api/files/by-client/{clientId}

Parameters: Same as list endpoint with additional per_page

8. Get Organized File Structure

GET /api/files/organized

Response:

{
    "data": {
        "devis/general": {
            "category": "devis",
            "subcategory": "general",
            "files": [...],
            "count": 25
        },
        "facture/annual": {
            "category": "facture",
            "subcategory": "annual",
            "files": [...],
            "count": 15
        }
    },
    "message": "Structure de fichiers récupérée avec succès."
}

9. Get Storage Statistics

GET /api/files/statistics

Response:

{
    "data": {
        "total_files": 150,
        "total_size_bytes": 1073741824,
        "total_size_formatted": "1.00 GB",
        "by_type": {
            "application/pdf": {
                "count": 85,
                "total_size": 734003200
            },
            "image/jpeg": {
                "count": 45,
                "total_size": 209715200
            }
        },
        "by_category": {
            "devis": {
                "count": 60,
                "total_size": 429496729
            },
            "facture": {
                "count": 50,
                "total_size": 322122547
            }
        }
    },
    "message": "Statistiques de stockage récupérées avec succès."
}

10. Generate Download URL

GET /api/files/{id}/download

Response:

{
    "data": {
        "download_url": "/storage/client/123/devis/document_2024_12_01_10_30_45.pdf",
        "file_name": "document.pdf",
        "mime_type": "application/pdf"
    },
    "message": "URL de téléchargement générée avec succès."
}

Error Responses

Validation Error (422)

{
    "message": "Les données fournies ne sont pas valides.",
    "errors": {
        "file": ["Le fichier est obligatoire."],
        "category": ["La catégorie est obligatoire."]
    }
}

Not Found (404)

{
    "message": "Fichier non trouvé."
}

Server Error (500)

{
    "message": "Une erreur est survenue lors du traitement de la requête.",
    "error": "Detailed error message (only in debug mode)"
}

File Features

Automatic Organization

• Files are automatically organized by category and client
• Timestamps are added to prevent filename conflicts
• Safe slug generation for subcategories

Security

• SHA256 hash calculation for file integrity
• User-based access control
• File size validation (10MB limit)

Metadata Support

• MIME type detection
• File size tracking
• Upload timestamp
• User attribution
• Custom tags and descriptions

Storage Management

• Public storage disk usage
• Efficient path organization
• Duplicate prevention through hashing
• Automatic file moving on metadata updates

Usage Examples

Upload a Quote for Client

curl -X POST \
  http://localhost/api/files \
  -H "Authorization: Bearer {token}" \
  -F "file=@quote_2024.pdf" \
  -F "category=devis" \
  -F "client_id=123" \
  -F "subcategory=annual_2024" \
  -F 'tags[]=quote' \
  -F 'tags[]=annual'

Get All Client Files

curl -X GET \
  "http://localhost/api/files/by-client/123?per_page=20&sort_by=uploaded_at&sort_direction=desc" \
  -H "Authorization: Bearer {token}"

Get File Statistics

curl -X GET \
  "http://localhost/api/files/statistics" \
  -H "Authorization: Bearer {token}"

Search Files

curl -X GET \
  "http://localhost/api/files?search=annual&category=devis" \
  -H "Authorization: Bearer {token}"

Notes

• All file operations are logged for audit purposes
• Files are stored in storage/app/public/ directory
• The system automatically handles file moving when categories change
• Download URLs are generated on-demand for security
• Pagination is applied to all list endpoints
• French language is used for all API messages and validations