This commit adds a comprehensive API documentation for the order management platform, detailing endpoints, request/response formats, authentication methods, and error codes.
1324 lines
23 KiB
Markdown
1324 lines
23 KiB
Markdown
# 📚 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
|