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

POST /api/v1/auth/register
Content-Type: application/json

Requête:

{
  "username": "jean_dupont",
  "password": "SecurePass123!",
  "nom": "Dupont",
  "prenom": "Jean",
  "telephone": "+33612345678"
}

Réponse (201 Created):

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

Se connecter et obtenir un token JWT

POST /api/v1/auth/login
Content-Type: application/json

Requête:

{
  "username": "jean_dupont",
  "password": "SecurePass123!"
}

Réponse (200 OK):

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

POST /api/v1/auth/logout
Authorization: Bearer <token>

Réponse (200 OK):

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

GET /api/v1/products

Réponse (200 OK):

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

GET /api/v1/products/:id

Réponse (200 OK):

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

POST /api/v1/panier/add
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "name_product": "Pizza Margherita",
  "category": "pizza",
  "quantity": 2
}

Réponse (201 Created):

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

GET /api/v1/panier/:username
Authorization: Bearer <token>

Réponse (200 OK):

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

DELETE /api/v1/panier/remove
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "id": 15
}

Réponse (200 OK):

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

DELETE /api/v1/panier/clear
Authorization: Bearer <token>

Réponse (200 OK):

{
  "success": true,
  "message": "Panier vidé avec succès",
  "stock_released": 3
}

Commandes

Valider le panier (Checkout avec Auto-assignation)

POST /api/v1/checkout
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "delivery_address": "15 Rue de la Paix, 75002 Paris, France"
}

Réponse avec auto-assignation (200 OK):

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

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

GET /api/v1/my-commands
Authorization: Bearer <token>

Réponse (200 OK):

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

GET /api/v1/commands/:id/status
Authorization: Bearer <token>

Réponse (200 OK):

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

GET /api/v1/commands/:id/tracking
Authorization: Bearer <token>

Réponse (200 OK):

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

GET /api/v1/commands/:id/eta
Authorization: Bearer <token>

Réponse (200 OK):

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

POST /api/v1/commands/:id/approve
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "rating": 5,
  "comment": "Excellent service, livreur très professionnel !"
}

Réponse (200 OK):

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

POST /api/v1/commands/:id/cancel
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "reason": "Changement de plans"
}

Réponse (200 OK):

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

PUT /api/v1/profile/update
Authorization: Bearer <token>
Content-Type: application/json

Requête:

{
  "nom": "Nouveau Nom",
  "prenom": "Nouveau Prénom",
  "telephone": "+33687654321",
  "password": "NewSecurePass456!"
}

Réponse (200 OK):

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

GET /api/v1/penalties
Authorization: Bearer <token>

Réponse (200 OK):

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

POST /api/v2/admin/auth/login
Content-Type: application/json

Requête:

{
  "username": "admin_master",
  "password": "AdminSecure123!"
}

Réponse (200 OK):

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "user": {
    "username": "admin_master",
    "role": "admin"
  }
}

Gestion des Commandes

Liste des commandes

GET /api/v2/admin/protected/orders
Authorization: Bearer <admin_token>

Réponse (200 OK):

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

POST /api/v2/admin/protected/orders/:id/auto-assign
Authorization: Bearer <admin_token>

Réponse (200 OK):

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

POST /api/v2/admin/protected/orders/auto-assign-all
Authorization: Bearer <admin_token>

Réponse (200 OK):

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

GET /api/v2/admin/protected/delivery-persons
Authorization: Bearer <admin_token>

Réponse (200 OK):

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

GET /api/v2/admin/protected/delivery-persons/:username/location
Authorization: Bearer <admin_token>

Réponse (200 OK):

{
  "success": true,
  "deliveryman": "john_deliveryman",
  "location": {
    "latitude": 48.8566,
    "longitude": 2.3522,
    "last_update": "2025-01-18T16:25:00Z"
  },
  "status": "available"
}

Queues des livreurs

GET /api/v2/admin/protected/delivery/queues
Authorization: Bearer <admin_token>

Réponse (200 OK):

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

POST /api/v2/admin/protected/products
Authorization: Bearer <admin_token>
Content-Type: application/json

Requête:

{
  "nom": "Pizza Pepperoni",
  "category": "pizza",
  "description": "Pizza avec pepperoni et mozzarella",
  "stock": 30,
  "prix": 14.50
}

Réponse (201 Created):

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

POST /api/v2/admin/protected/penalty
Authorization: Bearer <admin_token>
Content-Type: application/json

Requête:

{
  "username": "jean_dupont",
  "amount": 50.0,
  "reason": "Comportement inapproprié"
}

Réponse (200 OK):

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

GET /api/v1/cabine/commands/:id/items
Authorization: Bearer <cabine_token>

Réponse (200 OK):

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

PUT /api/v1/cabine/items/:item_id/status
Authorization: Bearer <cabine_token>
Content-Type: application/json

Requête:

{
  "status": "prepared"
}

Réponse (200 OK):

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

GET /api/v1/livreur/deliveries
Authorization: Bearer <livreur_token>

Réponse (200 OK):

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

PUT /api/v1/livreur/deliveries/:id/status
Authorization: Bearer <livreur_token>
Content-Type: application/json

Requête:

{
  "status": "en_route",
  "notes": "En route vers le client",
  "latitude": 48.8566,
  "longitude": 2.3522
}

Réponse (200 OK):

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

POST /api/v1/livreur/location/update
Authorization: Bearer <livreur_token>
Content-Type: application/json

Requête:

{
  "latitude": 48.8566,
  "longitude": 2.3522
}

Réponse (200 OK):

{
  "success": true,
  "message": "Position mise à jour",
  "location": {
    "latitude": 48.8566,
    "longitude": 2.3522,
    "updated_at": "2025-01-18T17:35:00Z"
  }
}

Ma position actuelle

GET /api/v1/livreur/location
Authorization: Bearer <livreur_token>

Réponse (200 OK):

{
  "success": true,
  "location": {
    "latitude": 48.8566,
    "longitude": 2.3522,
    "last_update": "2025-01-18T17:35:00Z"
  }
}

Statut et Queue

Mettre à jour mon statut

POST /api/v1/livreur/update/status
Authorization: Bearer <livreur_token>
Content-Type: application/json

Requête:

{
  "status": "available"
}

Réponse (200 OK):

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

GET /api/v1/livreur/queue
Authorization: Bearer <livreur_token>

Réponse (200 OK):

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

{
  "error": "Données invalides",
  "details": "Le champ 'username' est requis"
}

401 - Unauthorized

{
  "error": "Token invalide ou expiré",
  "message": "Veuillez vous reconnecter"
}

403 - Forbidden

{
  "error": "Accès refusé",
  "message": "Vous n'avez pas les permissions nécessaires"
}

404 - Not Found

{
  "error": "Ressource introuvable",
  "message": "Commande avec l'ID 9999 introuvable"
}

409 - Conflict

{
  "error": "Conflit",
  "message": "Ce nom d'utilisateur est déjà pris"
}

422 - Unprocessable Entity

{
  "error": "Validation échouée",
  "details": {
    "field": "telephone",
    "message": "Format de téléphone invalide"
  }
}

500 - Internal Server Error

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

README.md

📚 Documentation API - Plateforme de Gestion de Commandes

📋 Table des Matières

🎯 Vue d'ensemble

✨ Fonctionnalités Principales

🔐 Authentication

Register Client

Login Client

Logout Client

🛒 API Client (v1)

Produits (Public - Pas d'auth requis)

Liste des produits

Produit par ID

Gestion du Panier

Ajouter au panier

Voir mon panier

Supprimer du panier

Vider le panier

Commandes

Valider le panier (Checkout avec Auto-assignation)

Mes commandes avec suivi

Statut temps réel d'une commande

Suivi détaillé avec ETA

ETA de livraison

Approuver une livraison

Annuler une commande

Profil et Historique

Mettre à jour mon profil

Mes pénalités

👨‍💼 API Admin (v2)

Authentication Admin

Login Admin

Gestion des Commandes

Liste des commandes

Assignation automatique GPS

Assigner toutes les commandes en attente

Gestion des Livreurs

Livreurs disponibles

Position d'un livreur

Queues des livreurs

Gestion des Produits

Créer un produit

Système de Pénalités

Appliquer une pénalité

🏪 API Cabine (v1)

Articles d'une commande

Modifier le statut d'un article

🚚 API Livreur (v1)

Livraisons

Mes livraisons (données filtrées)

Mettre à jour le statut d'une livraison

Position GPS

Mettre à jour ma position

Ma position actuelle

Statut et Queue

Mettre à jour mon statut

Ma queue de livraisons

❌ Codes d'Erreur

Erreurs HTTP Standards

Exemples d'Erreurs

400 - Bad Request

401 - Unauthorized

403 - Forbidden

404 - Not Found

409 - Conflict

422 - Unprocessable Entity

500 - Internal Server Error

📝 Notes Importantes

Sécurité

Format des Données

Workers Automatiques

Fonctionnalités Avancées