commit 5a280b6b01c62ec2651dca6753a89720b0e98e60
Author: Xor290 <free6nk33@gmail.com>
Date:   Tue Jan 20 19:13:04 2026 +0100

    Add API documentation for order management platform
    
    This commit adds a comprehensive API documentation for the order management platform, detailing endpoints, request/response formats, authentication methods, and error codes.

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..9acecc82
--- /dev/null
+++ b/README.md
@@ -0,0 +1,1323 @@
+# 📚 Documentation API - Plateforme de Gestion de Commandes
+
+**Version:** 4.0.0  
+**Date:** 2025-01-18  
+**Base URL:** `http://localhost:8080`  
+**Technologies:** Go, Gin, PostgreSQL, Redis, TomTom API
+
+---
+
+## 📋 Table des Matières
+
+1. [Vue d'ensemble](#vue-densemble)
+2. [Authentication](#authentication)
+3. [API Client (v1)](#api-client-v1)
+4. [API Admin (v2)](#api-admin-v2)
+5. [API Cabine (v1)](#api-cabine-v1)
+6. [API Livreur (v1)](#api-livreur-v1)
+7. [Codes d'Erreur](#codes-derreur)
+
+---
+
+## 🎯 Vue d'ensemble
+
+Cette API REST complète gère une plateforme de livraison avec assignation automatique GPS des livreurs, suivi en temps réel, et système de pénalités avancé.
+
+### ✨ Fonctionnalités Principales
+
+- **🔐 Authentication JWT** multi-rôles (Client, Admin, Livreur, Cabine)
+- **🚗 Auto-assignation GPS** des livreurs les plus proches
+- **📍 Suivi temps réel** avec ETA et géolocalisation
+- **🔄 Système de queues** optimisé pour les livraisons
+- **⚡ Workers automatiques** (nettoyage, assignation, notifications)
+- **🎯 Système de pénalités** pour la gestion des comportements
+
+---
+
+## 🔐 Authentication
+
+### Register Client
+
+**Créer un nouveau compte client**
+
+```bash
+POST /api/v1/auth/register
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "username": "jean_dupont",
+  "password": "SecurePass123!",
+  "nom": "Dupont",
+  "prenom": "Jean",
+  "telephone": "+33612345678"
+}
+```
+
+**Réponse (201 Created):**
+```json
+{
+  "success": true,
+  "message": "Client créé avec succès",
+  "client": {
+    "id": 42,
+    "username": "jean_dupont",
+    "nom": "Dupont",
+    "prenom": "Jean",
+    "telephone": "+33612345678",
+    "command": 0,
+    "point": 0,
+    "points_zipette": 0,
+    "amende": 0.0,
+    "cancellations_count": 0,
+    "created_at": "2025-01-18T14:30:00Z"
+  }
+}
+```
+
+**Erreurs possibles:**
+- `400` - Données invalides (validation échouée)
+- `409` - Username ou téléphone déjà utilisé
+
+---
+
+### Login Client
+
+**Se connecter et obtenir un token JWT**
+
+```bash
+POST /api/v1/auth/login
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "username": "jean_dupont",
+  "password": "SecurePass123!"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 18000,
+  "user": {
+    "username": "jean_dupont",
+    "role": "client"
+  }
+}
+```
+
+**Erreurs possibles:**
+- `400` - Données manquantes
+- `401` - Identifiants incorrects
+
+---
+
+### Logout Client
+
+**Se déconnecter (invalider le token)**
+
+```bash
+POST /api/v1/auth/logout
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Déconnexion réussie"
+}
+```
+
+---
+
+## 🛒 API Client (v1)
+
+**Toutes les routes clients nécessitent le header:**
+```
+Authorization: Bearer <client_token>
+```
+
+### Produits (Public - Pas d'auth requis)
+
+#### Liste des produits
+
+```bash
+GET /api/v1/products
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "products": [
+    {
+      "id": 1,
+      "nom": "Pizza Margherita",
+      "description": "Pizza traditionnelle avec tomate, mozzarella et basilic",
+      "category": "pizza",
+      "stock": 50,
+      "prix": 12.50,
+      "prices": [
+        {
+          "id": 1,
+          "product_id": 1,
+          "quantity": 1,
+          "price": 12.50
+        }
+      ],
+      "media": [
+        {
+          "id": 1,
+          "product_id": 1,
+          "type": "image",
+          "url": "/uploads/pizza_margherita.jpg"
+        }
+      ],
+      "created_at": "2025-01-18T00:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+#### Produit par ID
+
+```bash
+GET /api/v1/products/:id
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "product": {
+    "id": 1,
+    "nom": "Pizza Margherita",
+    "description": "Pizza traditionnelle avec tomate, mozzarella et basilic",
+    "category": "pizza",
+    "stock": 50,
+    "prix": 12.50,
+    "prices": [...],
+    "media": [...],
+    "created_at": "2025-01-18T00:00:00Z"
+  }
+}
+```
+
+**Erreurs possibles:**
+- `404` - Produit non trouvé
+
+---
+
+### Gestion du Panier
+
+#### Ajouter au panier
+
+```bash
+POST /api/v1/panier/add
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "name_product": "Pizza Margherita",
+  "category": "pizza",
+  "quantity": 2
+}
+```
+
+**Réponse (201 Created):**
+```json
+{
+  "success": true,
+  "message": "Produit ajouté au panier avec succès",
+  "panier": {
+    "id": 15,
+    "username": "jean_dupont",
+    "name_product": "Pizza Margherita",
+    "category": "pizza",
+    "quantity": 2,
+    "price": 25.00,
+    "created_at": "2025-01-18T14:35:00Z"
+  }
+}
+```
+
+**Erreurs possibles:**
+- `400` - Données invalides ou stock insuffisant
+- `401` - Non authentifié
+- `404` - Produit non trouvé
+
+---
+
+#### Voir mon panier
+
+```bash
+GET /api/v1/panier/:username
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Panier récupéré avec succès",
+  "panier": [
+    {
+      "id": 15,
+      "username": "jean_dupont",
+      "name_product": "Pizza Margherita",
+      "category": "pizza",
+      "quantity": 2,
+      "price": 25.00,
+      "created_at": "2025-01-18T14:35:00Z"
+    }
+  ],
+  "count": 1,
+  "total_amount": 25.00
+}
+```
+
+**Erreurs possibles:**
+- `403` - Accès au panier d'un autre utilisateur
+- `404` - Utilisateur non trouvé
+
+---
+
+#### Supprimer du panier
+
+```bash
+DELETE /api/v1/panier/remove
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "id": 15
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Produit supprimé du panier avec succès",
+  "item_id": 15,
+  "stock_released": true
+}
+```
+
+**Erreurs possibles:**
+- `403` - Tentative de supprimer l'article d'un autre utilisateur
+- `404` - Article non trouvé
+
+---
+
+#### Vider le panier
+
+```bash
+DELETE /api/v1/panier/clear
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Panier vidé avec succès",
+  "stock_released": 3
+}
+```
+
+---
+
+### Commandes
+
+#### Valider le panier (Checkout avec Auto-assignation)
+
+```bash
+POST /api/v1/checkout
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "delivery_address": "15 Rue de la Paix, 75002 Paris, France"
+}
+```
+
+**Réponse avec auto-assignation (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Commande créée et livreur assigné automatiquement",
+  "command_id": 1234,
+  "delivery_address": "15 Rue de la Paix, 75002 Paris, France",
+  "status": "assigned",
+  "auto_assigned": true,
+  "assigned_to": {
+    "username": "john_deliveryman",
+    "distance_km": 1.5,
+    "travel_time": 8
+  }
+}
+```
+
+**Réponse sans auto-assignation (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Commande créée - En attente d'assignation",
+  "command_id": 1234,
+  "delivery_address": "15 Rue de la Paix, 75002 Paris, France",
+  "status": "pending",
+  "auto_assigned": false
+}
+```
+
+**Erreurs possibles:**
+- `400` - Panier vide ou adresse manquante
+- `401` - Non authentifié
+- `500` - Erreur création commande
+
+---
+
+#### Mes commandes avec suivi
+
+```bash
+GET /api/v1/my-commands
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "commands": [
+    {
+      "id": 1234,
+      "username": "jean_dupont",
+      "status": "assigned",
+      "total": 25.00,
+      "delivery_address": "15 Rue de la Paix, 75002 Paris",
+      "livreur_assign": "john_deliveryman",
+      "created_at": "2025-01-18T14:40:00Z",
+      "updated_at": "2025-01-18T14:42:00Z",
+      "tracking": {
+        "eta_minutes": 25,
+        "estimated_arrival": "15:05",
+        "deliveryman_status": "en_route",
+        "queue_position": 2
+      }
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+#### Statut temps réel d'une commande
+
+```bash
+GET /api/v1/commands/:id/status
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "command_id": 1234,
+  "status": "en_route",
+  "deliveryman": "john_deliveryman",
+  "updated_at": "2025-01-18T15:20:00Z"
+}
+```
+
+**Statuts possibles:**
+- `pending` - En attente d'assignation
+- `assigned` - Assignée à un livreur
+- `support` - Prise en charge par le livreur
+- `en_route` - Livreur en chemin
+- `arrived` - Livreur arrivé
+- `livre` - Livrée (en attente d'approbation)
+- `approved` - Approuvée par le client
+- `cancelled` - Annulée
+- `failed` - Échec de livraison
+
+---
+
+#### Suivi détaillé avec ETA
+
+```bash
+GET /api/v1/commands/:id/tracking
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "command_id": 1234,
+  "status": "en_route",
+  "deliveryman": "john_deliveryman",
+  "eta": {
+    "minutes": 22,
+    "estimated_arrival": "15:02",
+    "arrival_time_unix": 1705669320,
+    "updated_at": "2025-01-18T14:40:00Z"
+  },
+  "queue_position": 2,
+  "total_queue_size": 5
+}
+```
+
+---
+
+#### ETA de livraison
+
+```bash
+GET /api/v1/commands/:id/eta
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "command_id": 1234,
+  "eta_minutes": 22,
+  "estimated_arrival": "15:02:00",
+  "queue_position": 2,
+  "updated_at": "2025-01-18T14:40:00Z"
+}
+```
+
+---
+
+#### Approuver une livraison
+
+```bash
+POST /api/v1/commands/:id/approve
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "rating": 5,
+  "comment": "Excellent service, livreur très professionnel !"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Livraison approuvée avec succès",
+  "command_id": 1234,
+  "status": "approved",
+  "rating": {
+    "deliveryman": "john_deliveryman",
+    "rating": 5,
+    "comment": "Excellent service, livreur très professionnel !",
+    "created_at": "2025-01-18T15:05:00Z"
+  }
+}
+```
+
+---
+
+#### Annuler une commande
+
+```bash
+POST /api/v1/commands/:id/cancel
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "reason": "Changement de plans"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Commande annulée avec succès",
+  "command_id": 1234,
+  "penalty_applied": true,
+  "penalty_details": {
+    "cancellations_count": 1,
+    "penalty_amount": 20.0,
+    "warning": "Pénalité appliquée pour annulation"
+  }
+}
+```
+
+---
+
+### Profil et Historique
+
+#### Mettre à jour mon profil
+
+```bash
+PUT /api/v1/profile/update
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "nom": "Nouveau Nom",
+  "prenom": "Nouveau Prénom",
+  "telephone": "+33687654321",
+  "password": "NewSecurePass456!"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Profil mis à jour avec succès",
+  "client": {
+    "id": 42,
+    "username": "jean_dupont",
+    "nom": "Nouveau Nom",
+    "prenom": "Nouveau Prénom",
+    "telephone": "+33687654321",
+    "updated_at": "2025-01-18T15:30:00Z"
+  }
+}
+```
+
+---
+
+#### Mes pénalités
+
+```bash
+GET /api/v1/penalties
+Authorization: Bearer <token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "client": {
+    "username": "jean_dupont",
+    "amende": 20.0,
+    "cancellations_count": 1,
+    "last_penalty_reason": "Annulation tardive"
+  },
+  "penalty_scale": {
+    "1st": 20.0,
+    "2nd": 50.0,
+    "3rd": 100.0,
+    "4th+": 150.0
+  },
+  "next_penalty": 50.0,
+  "warning": "La prochaine annulation entraînera une pénalité de 50 points"
+}
+```
+
+---
+
+## 👨‍💼 API Admin (v2)
+
+**Toutes les routes admin nécessitent le header:**
+```
+Authorization: Bearer <admin_token>
+```
+
+### Authentication Admin
+
+#### Login Admin
+
+```bash
+POST /api/v2/admin/auth/login
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "username": "admin_master",
+  "password": "AdminSecure123!"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "Bearer",
+  "expires_in": 7200,
+  "user": {
+    "username": "admin_master",
+    "role": "admin"
+  }
+}
+```
+
+---
+
+### Gestion des Commandes
+
+#### Liste des commandes
+
+```bash
+GET /api/v2/admin/protected/orders
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "orders": [
+    {
+      "id": 1234,
+      "username": "jean_dupont",
+      "status": "assigned",
+      "total": 25.00,
+      "delivery_address": "15 Rue de la Paix, 75002 Paris",
+      "livreur_assign": "john_deliveryman",
+      "dest_latitude": 48.8698,
+      "dest_longitude": 2.3311,
+      "created_at": "2025-01-18T14:40:00Z",
+      "updated_at": "2025-01-18T14:42:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+#### Assignation automatique GPS
+
+```bash
+POST /api/v2/admin/protected/orders/:id/auto-assign
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Commande assignée automatiquement",
+  "command_id": 1234,
+  "assigned_to": "john_deliveryman",
+  "distance": {
+    "km": 1.5,
+    "eta_minutes": 8
+  },
+  "queue_position": 3
+}
+```
+
+**Erreurs possibles:**
+- `404` - Commande non trouvée
+- `400` - Aucun livreur disponible
+- `409` - Commande déjà assignée
+
+---
+
+#### Assigner toutes les commandes en attente
+
+```bash
+POST /api/v2/admin/protected/orders/auto-assign-all
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Auto-assignation effectuée",
+  "assigned_count": 5,
+  "failed_count": 0,
+  "details": [
+    {
+      "command_id": 1234,
+      "assigned_to": "john_deliveryman",
+      "distance_km": 1.5,
+      "eta_minutes": 8
+    }
+  ]
+}
+```
+
+---
+
+### Gestion des Livreurs
+
+#### Livreurs disponibles
+
+```bash
+GET /api/v2/admin/protected/delivery-persons
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "delivery_persons": [
+    {
+      "username": "john_deliveryman",
+      "status": "available",
+      "current_command": 0,
+      "queue_size": 2,
+      "location": {
+        "latitude": 48.8566,
+        "longitude": 2.3522,
+        "last_update": "2025-01-18T16:30:00Z"
+      }
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+#### Position d'un livreur
+
+```bash
+GET /api/v2/admin/protected/delivery-persons/:username/location
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "deliveryman": "john_deliveryman",
+  "location": {
+    "latitude": 48.8566,
+    "longitude": 2.3522,
+    "last_update": "2025-01-18T16:25:00Z"
+  },
+  "status": "available"
+}
+```
+
+---
+
+#### Queues des livreurs
+
+```bash
+GET /api/v2/admin/protected/delivery/queues
+Authorization: Bearer <admin_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "queues": {
+    "john_deliveryman": {
+      "queue_size": 3,
+      "commands": [1234, 1235, 1236],
+      "can_accept_more": true,
+      "capacity": "3/10",
+      "status": "available"
+    }
+  },
+  "total_pending": 3
+}
+```
+
+---
+
+### Gestion des Produits
+
+#### Créer un produit
+
+```bash
+POST /api/v2/admin/protected/products
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "nom": "Pizza Pepperoni",
+  "category": "pizza",
+  "description": "Pizza avec pepperoni et mozzarella",
+  "stock": 30,
+  "prix": 14.50
+}
+```
+
+**Réponse (201 Created):**
+```json
+{
+  "success": true,
+  "message": "Produit créé avec succès",
+  "product": {
+    "id": 10,
+    "nom": "Pizza Pepperoni",
+    "category": "pizza",
+    "description": "Pizza avec pepperoni et mozzarella",
+    "stock": 30,
+    "prix": 14.50,
+    "created_at": "2025-01-18T16:10:00Z"
+  }
+}
+```
+
+---
+
+### Système de Pénalités
+
+#### Appliquer une pénalité
+
+```bash
+POST /api/v2/admin/protected/penalty
+Authorization: Bearer <admin_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "username": "jean_dupont",
+  "amount": 50.0,
+  "reason": "Comportement inapproprié"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Pénalité appliquée",
+  "client": "jean_dupont",
+  "penalty": {
+    "amount": 50.0,
+    "reason": "Comportement inapproprié",
+    "applied_at": "2025-01-18T17:00:00Z"
+  },
+  "total_amende": 70.0
+}
+```
+
+---
+
+## 🏪 API Cabine (v1)
+
+**Toutes les routes cabine nécessitent le header:**
+```
+Authorization: Bearer <cabine_token>
+```
+
+#### Articles d'une commande
+
+```bash
+GET /api/v1/cabine/commands/:id/items
+Authorization: Bearer <cabine_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "command_id": 1234,
+  "items": [
+    {
+      "id": 1,
+      "command_id": 1234,
+      "produit": "Pizza Margherita",
+      "quantite": 2,
+      "prix": 25.0,
+      "status": "pending",
+      "category": "pizza"
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+#### Modifier le statut d'un article
+
+```bash
+PUT /api/v1/cabine/items/:item_id/status
+Authorization: Bearer <cabine_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "status": "prepared"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Statut mis à jour",
+  "item": {
+    "id": 1,
+    "command_id": 1234,
+    "status": "prepared",
+    "updated_at": "2025-01-18T17:15:00Z"
+  }
+}
+```
+
+**Statuts disponibles:** `pending`, `prepared`, `packed`, `ready`
+
+---
+
+## 🚚 API Livreur (v1)
+
+**Toutes les routes livreur nécessitent le header:**
+```
+Authorization: Bearer <livreur_token>
+```
+
+### Livraisons
+
+#### Mes livraisons (données filtrées)
+
+```bash
+GET /api/v1/livreur/deliveries
+Authorization: Bearer <livreur_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "deliveries": [
+    {
+      "id": 1234,
+      "status": "assigned",
+      "adresse": "15 Rue de la Paix, 75002 Paris",
+      "total_prix": 25.0,
+      "created_at": "2025-01-18T14:40:00Z",
+      "client_info": {
+        "nom": "Dupont",
+        "prenom": "Jean"
+      },
+      "items": [
+        {
+          "produit": "Pizza Margherita",
+          "quantite": 2,
+          "prix": 25.0
+        }
+      ],
+      "items_count": 1,
+      "eta": {
+        "minutes": 25,
+        "estimated_arrival": "15:05"
+      }
+    }
+  ],
+  "count": 1
+}
+```
+
+**Note:** Les données sensibles comme le téléphone client sont filtrées pour les livreurs.
+
+---
+
+#### Mettre à jour le statut d'une livraison
+
+```bash
+PUT /api/v1/livreur/deliveries/:id/status
+Authorization: Bearer <livreur_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "status": "en_route",
+  "notes": "En route vers le client",
+  "latitude": 48.8566,
+  "longitude": 2.3522
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Statut mis à jour",
+  "command_id": 1234,
+  "status": "en_route",
+  "eta_minutes": 15,
+  "eta_message": "Arrivée prévue dans 15 minutes"
+}
+```
+
+**Statuts valides pour livreur:**
+- `support` - Prise en charge
+- `assigned` - Assigné
+- `en_route` - En route vers le client
+- `arrived` - Arrivé à destination
+- `livre` - Livré
+- `failed` - Échec de livraison
+- `cancelled` - Annulée
+
+---
+
+### Position GPS
+
+#### Mettre à jour ma position
+
+```bash
+POST /api/v1/livreur/location/update
+Authorization: Bearer <livreur_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "latitude": 48.8566,
+  "longitude": 2.3522
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Position mise à jour",
+  "location": {
+    "latitude": 48.8566,
+    "longitude": 2.3522,
+    "updated_at": "2025-01-18T17:35:00Z"
+  }
+}
+```
+
+---
+
+#### Ma position actuelle
+
+```bash
+GET /api/v1/livreur/location
+Authorization: Bearer <livreur_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "location": {
+    "latitude": 48.8566,
+    "longitude": 2.3522,
+    "last_update": "2025-01-18T17:35:00Z"
+  }
+}
+```
+
+---
+
+### Statut et Queue
+
+#### Mettre à jour mon statut
+
+```bash
+POST /api/v1/livreur/update/status
+Authorization: Bearer <livreur_token>
+Content-Type: application/json
+```
+
+**Requête:**
+```json
+{
+  "status": "available"
+}
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "message": "Statut mis à jour",
+  "status": {
+    "username": "john_deliveryman",
+    "status": "available",
+    "updated_at": "2025-01-18T17:40:00Z"
+  }
+}
+```
+
+**Statuts disponibles:** `available`, `busy`, `offline`
+
+---
+
+#### Ma queue de livraisons
+
+```bash
+GET /api/v1/livreur/queue
+Authorization: Bearer <livreur_token>
+```
+
+**Réponse (200 OK):**
+```json
+{
+  "success": true,
+  "deliveryman": "john_deliveryman",
+  "queue_size": 3,
+  "commands": [
+    {
+      "position": 1,
+      "command_id": 1234,
+      "address": "15 Rue de la Paix, 75002 Paris",
+      "estimated_eta": 12,
+      "total_prix": 25.0
+    }
+  ]
+}
+```
+
+---
+
+## ❌ Codes d'Erreur
+
+### Erreurs HTTP Standards
+
+| Code | Signification | Description |
+|------|---------------|-------------|
+| 200 | OK | Succès |
+| 201 | Created | Ressource créée |
+| 400 | Bad Request | Données invalides |
+| 401 | Unauthorized | Non authentifié |
+| 403 | Forbidden | Non autorisé |
+| 404 | Not Found | Ressource introuvable |
+| 409 | Conflict | Conflit (username déjà pris) |
+| 422 | Unprocessable Entity | Validation échouée |
+| 500 | Internal Server Error | Erreur serveur |
+
+### Exemples d'Erreurs
+
+#### 400 - Bad Request
+```json
+{
+  "error": "Données invalides",
+  "details": "Le champ 'username' est requis"
+}
+```
+
+#### 401 - Unauthorized
+```json
+{
+  "error": "Token invalide ou expiré",
+  "message": "Veuillez vous reconnecter"
+}
+```
+
+#### 403 - Forbidden
+```json
+{
+  "error": "Accès refusé",
+  "message": "Vous n'avez pas les permissions nécessaires"
+}
+```
+
+#### 404 - Not Found
+```json
+{
+  "error": "Ressource introuvable",
+  "message": "Commande avec l'ID 9999 introuvable"
+}
+```
+
+#### 409 - Conflict
+```json
+{
+  "error": "Conflit",
+  "message": "Ce nom d'utilisateur est déjà pris"
+}
+```
+
+#### 422 - Unprocessable Entity
+```json
+{
+  "error": "Validation échouée",
+  "details": {
+    "field": "telephone",
+    "message": "Format de téléphone invalide"
+  }
+}
+```
+
+#### 500 - Internal Server Error
+```json
+{
+  "error": "Erreur serveur interne",
+  "message": "Une erreur inattendue s'est produite"
+}
+```
+
+---
+
+## 📝 Notes Importantes
+
+### Sécurité
+- **Tokens JWT** : Expiration variable selon le rôle (Client: 5h, Admin: 2h)
+- **Validation GPS** : Requis pour certaines actions de livraison
+- **Filtrage des données** : Les livreurs n'ont pas accès aux téléphones clients
+- **Rate Limiting** : Protection contre les abus
+
+### Format des Données
+- **Dates** : Format ISO 8601 (`2025-01-18T14:30:00Z`)
+- **Coordonnées** : Latitude/Longitude en décimal (WGS84)
+- **Prix** : En euros avec 2 décimales
+- **Téléphones** : Format international (`+33612345678`)
+
+### Workers Automatiques
+- **Auto-Assignment Cron** : Toutes les 5 minutes
+- **Queue Cleanup** : Toutes les 5 minutes  
+- **ETA Updates** : Toutes les 30 secondes
+- **Stock Cleanup** : Toutes les 5 minutes
+
+### Fonctionnalités Avancées
+- **Assignation GPS automatique** au checkout
+- **Calcul ETA temps réel** avec TomTom API
+- **Système de queues optimisé** pour les livreurs
+- **Nettoyage automatique** des commandes invalides
+- **Notifications temps réel** via Redis Pub/Sub
+
+---
+
+**Documentation générée le :** 2025-01-18  
+**Version API :** 4.0.0  
+**Technologies :** Go, Gin, PostgreSQL, Redis, TomTom API  
+**Support :** Développé avec ❤️ en Go