Files
projet_gestion_commande/README.md
T
Xor290andGitHub 5a280b6b01 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.
2026-01-20 19:13:04 +01:00

23 KiB

📚 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
  2. Authentication
  3. API Client (v1)
  4. API Admin (v2)
  5. API Cabine (v1)
  6. API Livreur (v1)
  7. Codes d'Erreur

🎯 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

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é

Login Client

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

Login 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