================================================================================ EUROFAT API - TRAJETS ENDPOINTS ================================================================================ BASE URL: http://localhost/EUROFAT_API/public/api ================================================================================ 1. GET ALL TRAJETS ================================================================================ Method: GET Endpoint: /api/trajets Headers: - Accept: application/json Description: Récupère tous les trajets avec pagination Parameters (optional): - status: Filter by status - type_voyage: Filter by type (Aller simple/Aller-retour) - id_chauffeur: Filter by chauffeur ID - id_vehicule: Filter by vehicule ID - id_demande: Filter by demande ID - date_from: Filter by date (start) - date_to: Filter by date (end) - per_page: Items per page (default: 15) Example Request: GET /api/trajets GET /api/trajets?status=En%20cours GET /api/trajets?id_chauffeur=1&per_page=20 GET /api/trajets?date_from=2025-12-01&date_to=2025-12-31 ================================================================================ 2. GET TRAJETS STATISTICS ================================================================================ Method: GET Endpoint: /api/trajets/statistics Headers: - Accept: application/json Description: Récupère les statistiques des trajets (total, par statut, etc.) Example Request: GET /api/trajets/statistics Response Example: { "data": { "total": 100, "by_status": { "Planifié": 20, "En cours": 15, "Terminé": 60, "Annulé": 5 }, "by_type": { "Aller simple": 70, "Aller-retour": 30 } } } ================================================================================ 3. CREATE NEW TRAJET ================================================================================ Method: POST Endpoint: /api/trajets Headers: - Content-Type: application/json - Accept: application/json Body (JSON): { "id_demande": 1, "id_chauffeur": 1, "id_vehicule": 1, "id_client": 1, "id_depot": 1, "type_voyage": "Aller simple", "date_depart": "2025-12-20 08:00:00", "date_arrivee_prevue": "2025-12-20 12:00:00", "id_ville_depart": 1, "id_ville_arrivee": 2, "adresse_depart": "123 Rue de Départ, Casablanca", "adresse_arrivee": "456 Avenue d'Arrivée, Rabat", "distance_km": 90.5, "cout_carburant": 250.00, "peage": 50.00, "autres_frais": 20.00, "status": "Planifié", "notes": "Transport urgent de marchandises" } Required Fields: - id_demande - id_chauffeur - id_vehicule - id_client - type_voyage (Aller simple or Aller-retour) - date_depart - id_ville_depart - id_ville_arrivee - adresse_depart - adresse_arrivee Optional Fields: - id_depot - date_arrivee_prevue - date_arrivee_reelle - distance_km - cout_carburant - peage - autres_frais - status (default: Planifié) - notes ================================================================================ 4. GET SINGLE TRAJET ================================================================================ Method: GET Endpoint: /api/trajets/{id} Headers: - Accept: application/json Description: Récupère un trajet spécifique par son ID avec toutes les relations Example Request: GET /api/trajets/1 GET /api/trajets/5 Response includes: - Trajet details - Chauffeur information - Vehicule information - Client information - Demande information - Depot information - Ville depart/arrivee ================================================================================ 5. UPDATE TRAJET STATUS ================================================================================ Method: PATCH Endpoint: /api/trajets/{id}/status Headers: - Content-Type: application/json - Accept: application/json Body (JSON): { "status": "En cours" } Valid Status Values: - Planifié - En cours - Terminé - Annulé Example Request: PATCH /api/trajets/1/status Body: { "status": "En cours" } ================================================================================ 6. UPDATE TRAJET ================================================================================ Method: PUT Endpoint: /api/trajets/{id} Headers: - Content-Type: application/json - Accept: application/json Body (JSON) - All fields are optional: { "id_chauffeur": 2, "id_vehicule": 3, "date_depart": "2025-12-21 09:00:00", "date_arrivee_prevue": "2025-12-21 13:00:00", "date_arrivee_reelle": "2025-12-21 12:45:00", "distance_km": 95.0, "cout_carburant": 260.00, "peage": 55.00, "autres_frais": 25.00, "notes": "Updated notes", "status": "Terminé" } Example Request: PUT /api/trajets/1 Body: { "distance_km": 95.0, "cout_carburant": 260.00 } ================================================================================ 7. GET TRAJETS BY DEMANDE ================================================================================ Method: GET Endpoint: /api/trajets/demande/{demandeId} Headers: - Accept: application/json Description: Récupère tous les trajets associés à une demande spécifique Example Request: GET /api/trajets/demande/1 GET /api/trajets/demande/5 Use Case: Show all trips for a specific customer request ================================================================================ 8. GET TRAJETS BY CHAUFFEUR ================================================================================ Method: GET Endpoint: /api/trajets/chauffeur/{chauffeurId} Headers: - Accept: application/json Description: Récupère tous les trajets d'un chauffeur spécifique Parameters (optional): - status: Filter by status - date_from: Filter by date (start) - Format: YYYY-MM-DD - date_to: Filter by date (end) - Format: YYYY-MM-DD Example Request: GET /api/trajets/chauffeur/1 GET /api/trajets/chauffeur/1?status=En%20cours GET /api/trajets/chauffeur/1?date_from=2025-12-01 GET /api/trajets/chauffeur/1?date_from=2025-12-01&date_to=2025-12-31 GET /api/trajets/chauffeur/1?date_from=2025-12-25&status=En%20cours Use Case: - View driver's trip history - Check driver's current assignments - Schedule new trips for a driver - Generate monthly reports for a driver cURL Examples: # Trajets du chauffeur pour aujourd'hui curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/chauffeur/1?date_from=2025-12-25" \ -H "Accept: application/json" # Trajets du chauffeur pour ce mois curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/chauffeur/1?date_from=2025-12-01&date_to=2025-12-31" \ -H "Accept: application/json" # Trajets en cours aujourd'hui curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/chauffeur/1?date_from=2025-12-25&status=En%20cours" \ -H "Accept: application/json" ================================================================================ 9. GET MY TRAJETS (CHAUFFEUR CONNECTÉ) 🆕 ================================================================================ Method: GET Endpoint: /api/trajets/my-trajets Headers: - Accept: application/json - Authorization: Bearer {JWT_TOKEN} Description: Récupère tous les trajets du chauffeur actuellement connecté Authentification JWT requise - L'utilisateur doit être un chauffeur Parameters (optional): - status: Filter by status - date_from: Filter by date (start) - Format: YYYY-MM-DD - date_to: Filter by date (end) - Format: YYYY-MM-DD Example Request: GET /api/trajets/my-trajets GET /api/trajets/my-trajets?date_from=2025-12-25 GET /api/trajets/my-trajets?date_from=2025-12-25&date_to=2025-12-31 GET /api/trajets/my-trajets?status=En%20cours GET /api/trajets/my-trajets?date_from=2025-12-25&status=En%20cours Response includes: - Trajet details with all relationships - Client information with nom_complet (full name) - Demande information with code_barre (barcode) - Chauffeur metadata in meta section Success Response Example: { "success": true, "data": [ { "id": 1, "type_voyage": "Transport", "client": { "id": 10, "nom": "Bennani", "prenom": "Fatima", "nom_complet": "Fatima Bennani", "raison_sociale": null, "email": "f.bennani@example.com", "telephone": "+212661234567" }, "demande": { "id": 123, "code_barre": "DEM-20251225-00001", "type_demande": "Transport", "status": "En livraison", "date_enlevement": "2025-12-25 08:00:00", "date_enlevement_formatted": "25/12/2025 08:00" }, "ville_depart": { "id": 4, "nom": "Casablanca" }, "ville_arrivee": { "id": 5, "nom": "Rabat" }, "status": "En cours", "date_depart_formatted": "25/12/2025 08:00", ... } ], "meta": { "total": 5, "chauffeur": { "id": 5, "nom": "Alami", "prenom": "Mohammed" }, "filters": { "status": "En cours", "date_from": "2025-12-25", "date_to": null } } } Use Case: - Mobile app for drivers - Driver dashboard - Daily trip overview - Real-time trip tracking cURL Examples: # Get all my trips curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/my-trajets" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Accept: application/json" # Get today's trips curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/my-trajets?date_from=2025-12-25" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Accept: application/json" # Get trips for this week curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/my-trajets?date_from=2025-12-22&date_to=2025-12-28" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Accept: application/json" # Get trips in progress curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/my-trajets?status=En%20cours" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Accept: application/json" # Get today's trips in progress curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/my-trajets?date_from=2025-12-25&status=En%20cours" \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Accept: application/json" Security Notes: - JWT Token is REQUIRED - Only accessible by users with chauffeur profile - Returns 403 Forbidden if user is not a chauffeur - Returns 401 Unauthorized if token is missing/invalid Special Features: - ✅ Includes client's full name (nom_complet) - ✅ Includes demande barcode (code_barre) - ✅ Auto-detects chauffeur from JWT token - ✅ Returns chauffeur info in metadata - ✅ Supports date range filtering ================================================================================ 10. DELETE TRAJET ================================================================================ Method: DELETE Endpoint: /api/trajets/{id} Headers: - Accept: application/json Description: Supprime un trajet Example Request: DELETE /api/trajets/1 Response: { "message": "Trajet supprimé avec succès" } ================================================================================ RESPONSE FORMATS ================================================================================ Success Response (Single Trajet): { "data": { "id": 1, "demande": { "id": 1, "type_demande": "Transport", "status": "Planifiée" }, "chauffeur": { "id": 1, "nom": "Bennani", "prenom": "Hassan", "telephone": "0661234567", "email": "hassan.bennani@eurofat.com" }, "vehicule": { "id": 1, "immatriculation": "ABC-123", "marque": "Mercedes", "modele": "Sprinter", "type": "Camion" }, "client": { "id": 1, "nom": "Alami", "prenom": "Mohammed", "raison_sociale": "ACME Corporation" }, "depot": { "id": 1, "nom": "Dépôt Central Casablanca" }, "type_voyage": "Aller simple", "date_depart": "2025-12-20 08:00:00", "date_depart_formatted": "20/12/2025 08:00", "date_arrivee_prevue": "2025-12-20 12:00:00", "date_arrivee_prevue_formatted": "20/12/2025 12:00", "date_arrivee_reelle": null, "ville_depart": { "id": 4, "nom": "Casablanca" }, "ville_arrivee": { "id": 5, "nom": "Rabat" }, "adresse_depart": "123 Rue de Départ, Casablanca", "adresse_arrivee": "456 Avenue d'Arrivée, Rabat", "distance_km": 90.5, "cout_carburant": 250.00, "peage": 50.00, "autres_frais": 20.00, "cout_total": 320.00, "status": "Planifié", "notes": "Transport urgent de marchandises", "created_at": "2025-12-17 14:30:00", "updated_at": "2025-12-17 14:30:00" } } Success Response (Create/Update): { "message": "Trajet créé avec succès", "data": { /* trajet object */ } } Success Response (List with Pagination): { "data": [ { /* trajet object */ }, { /* trajet object */ } ], "links": { "first": "http://localhost/EUROFAT_API/public/api/trajets?page=1", "last": "http://localhost/EUROFAT_API/public/api/trajets?page=5", "prev": null, "next": "http://localhost/EUROFAT_API/public/api/trajets?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 5, "per_page": 15, "to": 15, "total": 75 } } Error Response: { "message": "Error message", "errors": { "field_name": ["Error description"] } } Not Found Response: { "message": "Trajet non trouvé" } ================================================================================ BUSINESS LOGIC & WORKFLOWS ================================================================================ Workflow 1: Create a Trajet from a Demande ------------------------------------------- 1. Client creates a Demande (Transport request) 2. Admin reviews the Demande 3. Admin assigns: - Chauffeur (available driver) - Vehicule (appropriate vehicle) - Depot (pickup location) 4. Admin creates Trajet with all details 5. Demande status changes from "À planifier" → "Planifiée" 6. Trajet status is "Planifié" Workflow 2: Execute a Trajet ----------------------------- 1. Chauffeur receives assignment (Trajet status: Planifié) 2. Chauffeur starts journey → Update status to "En cours" → Record actual departure time 3. Chauffeur completes journey → Update status to "Terminé" → Record actual arrival time → Record actual costs (fuel, tolls, etc.) 4. System updates Demande status to "Livrée" Workflow 3: Track Driver Performance ------------------------------------- 1. Get all trajets for a chauffeur: GET /api/trajets/chauffeur/{id} 2. Filter by date range to see monthly performance 3. Calculate statistics: - Total trips - On-time delivery rate - Average costs - Total distance covered ================================================================================ FIELD DESCRIPTIONS ================================================================================ Trajet Fields: -------------- id : Unique identifier id_demande : Reference to the originating Demande id_chauffeur : Driver assigned to this trip id_vehicule : Vehicle used for this trip id_client : Client who requested the transport id_depot : Depot where goods are stored/picked up type_voyage : Type of trip (Aller simple/Aller-retour) date_depart : Scheduled departure date and time date_arrivee_prevue : Expected arrival date and time date_arrivee_reelle : Actual arrival date and time (filled after completion) id_ville_depart : Departure city id_ville_arrivee : Arrival city adresse_depart : Full departure address adresse_arrivee : Full arrival address distance_km : Distance in kilometers cout_carburant : Fuel cost (MAD) peage : Toll fees (MAD) autres_frais : Other expenses (MAD) cout_total : Total cost (calculated: carburant + peage + autres_frais) status : Current status of the trip notes : Additional notes or remarks Relationships: -------------- demande : The original transport request chauffeur : Driver information (from users table) vehicule : Vehicle details client : Customer information depot : Storage/pickup location villeDepart : Departure city details villeArrivee : Arrival city details ================================================================================ VALIDATION RULES ================================================================================ Create Trajet: -------------- - id_demande: required, must exist in demandes table - id_chauffeur: required, must exist in users table with profile_id=2 - id_vehicule: required, must exist in vehicules table - id_client: required, must exist in clients table - type_voyage: required, must be "Aller simple" or "Aller-retour" - date_depart: required, must be valid datetime - id_ville_depart: required, must exist in villes table - id_ville_arrivee: required, must exist in villes table, different from depart - adresse_depart: required, string, max 255 characters - adresse_arrivee: required, string, max 255 characters - distance_km: optional, numeric, min 0 - cout_carburant: optional, numeric, min 0 - peage: optional, numeric, min 0 - autres_frais: optional, numeric, min 0 - status: optional, must be valid status value - notes: optional, string Update Status: -------------- - status: required, must be one of: Planifié, En cours, Terminé, Annulé ================================================================================ NOTES & TIPS ================================================================================ 1. All endpoints require proper headers (Accept: application/json) 2. POST/PUT/PATCH endpoints require Content-Type: application/json 3. Status values are case-sensitive (use exact spelling) 4. Date format: YYYY-MM-DD HH:MM:SS 5. Amounts are in MAD (Moroccan Dirham) 6. Distance is in kilometers 7. Total cost is automatically calculated (no need to send it) 8. When status is "Terminé", fill date_arrivee_reelle 9. One Demande can have multiple Trajets (e.g., round trips) 10. Use byDemande endpoint to see all trips for a request Security Notes: --------------- - Validate that chauffeur exists and has correct profile - Validate that vehicule is available for the date range - Check that demande status allows creating trajets - Prevent overlapping assignments for same driver/vehicle Performance Tips: ----------------- - Use pagination for large lists - Filter by date range to reduce data load - Use specific endpoints (byDemande, byChauffeur) instead of filtering all - Cache statistics if they don't need real-time accuracy Integration with Demandes: -------------------------- When a Trajet is created: → Update Demande status to "Planifiée" When all Trajets are "Terminé": → Update Demande status to "Livrée" When a Trajet is "Annulé": → Check if other Trajets exist → If no active Trajets, revert Demande to "À planifier" ================================================================================ COMMON HTTP CODES ================================================================================ 200 - OK (successful GET, PUT, PATCH) 201 - Created (successful POST) 400 - Bad Request (validation errors) 404 - Not Found (resource doesn't exist) 405 - Method Not Allowed (wrong HTTP method) 422 - Unprocessable Entity (validation failed) 500 - Internal Server Error (server error) ================================================================================ TESTING EXAMPLES ================================================================================ Using cURL: ----------- # Get all trajets curl -X GET "http://localhost/EUROFAT_API/public/api/trajets" \ -H "Accept: application/json" # Get single trajet curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/1" \ -H "Accept: application/json" # Create new trajet curl -X POST "http://localhost/EUROFAT_API/public/api/trajets" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "id_demande": 1, "id_chauffeur": 1, "id_vehicule": 1, "id_client": 1, "type_voyage": "Aller simple", "date_depart": "2025-12-20 08:00:00", "id_ville_depart": 1, "id_ville_arrivee": 2, "adresse_depart": "123 Rue Test", "adresse_arrivee": "456 Avenue Test" }' # Update status curl -X PATCH "http://localhost/EUROFAT_API/public/api/trajets/1/status" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{"status": "En cours"}' # Get trajets by chauffeur curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/chauffeur/1" \ -H "Accept: application/json" # Get trajets by demande curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/demande/1" \ -H "Accept: application/json" # Get statistics curl -X GET "http://localhost/EUROFAT_API/public/api/trajets/statistics" \ -H "Accept: application/json" Using Postman: -------------- 1. Import the EUROFAT_Demandes_API.postman_collection.json 2. Set base URL variable: EUROFAT_API_URL = http://localhost/EUROFAT_API/public/api 3. All trajet endpoints are under "Trajets" folder 4. Use "Get Single Trajet" to see full response structure 5. Use "Update Status" with PATCH method (not PUT) ================================================================================