# 🌐 API REST - BTPXPRESS BACKEND

## 📋 Table des matières

- [Vue d'ensemble](#vue-densemble)
- [Authentification](#authentification)
- [Endpoints par concept](#endpoints-par-concept)
- [Codes de réponse](#codes-de-réponse)
- [Pagination](#pagination)
- [Filtrage et tri](#filtrage-et-tri)
- [Gestion des erreurs](#gestion-des-erreurs)
- [Exemples complets](#exemples-complets)

---

## 🎯 Vue d'ensemble

### **Base URL**

| Environnement | URL |
|---------------|-----|
| **Développement** | `http://localhost:8080/api/v1` |
| **Production** | `https://api.btpxpress.fr/api/v1` |

### **Format**

- **Content-Type** : `application/json`
- **Accept** : `application/json`
- **Charset** : `UTF-8`

### **Versioning**

L'API utilise le versioning dans l'URL : `/api/v1/...`

### **Documentation interactive**

- **Swagger UI** : http://localhost:8080/q/swagger-ui
- **OpenAPI Spec** : http://localhost:8080/q/openapi

---

## 🔐 Authentification

### **OAuth2 / OIDC avec Keycloak**

Toutes les requêtes (sauf `/auth/login`) nécessitent un token JWT.

#### **1. Obtenir un token**

```bash
curl -X POST http://localhost:8180/realms/btpxpress/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=btpxpress-backend" \
  -d "client_secret=your-secret" \
  -d "username=admin" \
  -d "password=admin123"
```

**Réponse** :
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}
```

#### **2. Utiliser le token**

```bash
curl -X GET http://localhost:8080/api/v1/chantiers \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
```

---

## 📚 Endpoints par concept

### **1. CHANTIERS** (`/api/v1/chantiers`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/chantiers` | Liste tous les chantiers | CHANTIERS_READ |
| GET | `/chantiers/{id}` | Détails d'un chantier | CHANTIERS_READ |
| POST | `/chantiers` | Créer un chantier | CHANTIERS_CREATE |
| PUT | `/chantiers/{id}` | Modifier un chantier | CHANTIERS_UPDATE |
| DELETE | `/chantiers/{id}` | Supprimer un chantier | CHANTIERS_DELETE |
| GET | `/chantiers/search` | Rechercher des chantiers | CHANTIERS_READ |
| GET | `/chantiers/stats` | Statistiques chantiers | CHANTIERS_READ |

### **2. CLIENTS** (`/api/v1/clients`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/clients` | Liste tous les clients | CLIENTS_READ |
| GET | `/clients/{id}` | Détails d'un client | CLIENTS_READ |
| POST | `/clients` | Créer un client | CLIENTS_CREATE |
| PUT | `/clients/{id}` | Modifier un client | CLIENTS_UPDATE |
| DELETE | `/clients/{id}` | Supprimer un client | CLIENTS_DELETE |

### **3. MATÉRIELS** (`/api/v1/materiels`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/materiels` | Liste tous les matériels | MATERIELS_READ |
| GET | `/materiels/{id}` | Détails d'un matériel | MATERIELS_READ |
| POST | `/materiels` | Créer un matériel | MATERIELS_CREATE |
| PUT | `/materiels/{id}` | Modifier un matériel | MATERIELS_UPDATE |
| DELETE | `/materiels/{id}` | Supprimer un matériel | MATERIELS_DELETE |
| GET | `/materiels/disponibles` | Matériels disponibles | MATERIELS_READ |
| GET | `/materiels/stock-faible` | Stock faible | MATERIELS_READ |

### **4. RÉSERVATIONS** (`/api/v1/reservations-materiel`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/reservations-materiel` | Liste réservations | RESERVATIONS_READ |
| POST | `/reservations-materiel` | Créer réservation | RESERVATIONS_CREATE |
| GET | `/reservations-materiel/conflits` | Détecter conflits | RESERVATIONS_READ |

### **5. DEVIS** (`/api/v1/devis`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/devis` | Liste devis | DEVIS_READ |
| GET | `/devis/{id}` | Détails devis | DEVIS_READ |
| POST | `/devis` | Créer devis | DEVIS_CREATE |
| PUT | `/devis/{id}/envoyer` | Envoyer devis | DEVIS_UPDATE |
| GET | `/devis/{id}/pdf` | Générer PDF | DEVIS_READ |

### **6. EMPLOYÉS** (`/api/v1/employes`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/employes` | Liste employés | EMPLOYES_READ |
| GET | `/employes/{id}` | Détails employé | EMPLOYES_READ |
| POST | `/employes` | Créer employé | EMPLOYES_CREATE |
| GET | `/employes/disponibles` | Employés disponibles | EMPLOYES_READ |

### **7. PLANNING** (`/api/v1/planning`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/planning` | Liste événements | PLANNING_READ |
| POST | `/planning` | Créer événement | PLANNING_CREATE |
| GET | `/planning/periode` | Par période | PLANNING_READ |

### **8. NOTIFICATIONS** (`/api/v1/notifications`)

| Méthode | Endpoint | Description | Permission |
|---------|----------|-------------|------------|
| GET | `/notifications` | Liste notifications | - |
| GET | `/notifications/non-lues` | Non lues | - |
| PUT | `/notifications/{id}/lire` | Marquer comme lue | - |

---

## 📊 Codes de réponse

| Code | Signification | Description |
|------|---------------|-------------|
| **200** | OK | Requête réussie |
| **201** | Created | Ressource créée |
| **204** | No Content | Suppression réussie |
| **400** | Bad Request | Données invalides |
| **401** | Unauthorized | Non authentifié |
| **403** | Forbidden | Accès refusé |
| **404** | Not Found | Ressource non trouvée |
| **409** | Conflict | Conflit (ex: email déjà existant) |
| **500** | Internal Server Error | Erreur serveur |

---

## 📄 Pagination

### **Paramètres**

| Paramètre | Type | Défaut | Description |
|-----------|------|--------|-------------|
| `page` | Integer | 0 | Numéro de page (commence à 0) |
| `size` | Integer | 20 | Nombre d'éléments par page |
| `sort` | String | - | Champ de tri (ex: `nom,asc`) |

### **Exemple**

```bash
GET /api/v1/chantiers?page=0&size=10&sort=nom,asc
```

### **Réponse paginée**

```json
{
  "content": [...],
  "totalElements": 150,
  "totalPages": 15,
  "size": 10,
  "number": 0,
  "first": true,
  "last": false
}
```

---

## 🔍 Filtrage et tri

### **Filtres**

```bash
# Filtrer par statut
GET /api/v1/chantiers?statut=EN_COURS

# Filtrer par type
GET /api/v1/materiels?type=VEHICULE

# Filtrer par date
GET /api/v1/devis?dateDebut=2025-01-01&dateFin=2025-12-31
```

### **Recherche**

```bash
# Recherche textuelle
GET /api/v1/chantiers/search?q=villa

# Recherche avancée
GET /api/v1/clients/search?nom=Dupont&ville=Paris
```

---

## ❌ Gestion des erreurs

### **Format d'erreur standard**

```json
{
  "timestamp": "2025-09-30T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Le nom du chantier est obligatoire",
  "path": "/api/v1/chantiers",
  "errors": [
    {
      "field": "nom",
      "message": "Le nom est obligatoire"
    }
  ]
}
```

### **Erreurs de validation**

```json
{
  "status": 400,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Email invalide"
    },
    {
      "field": "telephone",
      "message": "Le téléphone doit contenir 10 chiffres"
    }
  ]
}
```

---

## 💡 Exemples complets

### **Créer un chantier complet**

```bash
curl -X POST http://localhost:8080/api/v1/chantiers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nom": "Construction Villa Moderne",
    "code": "CHANT-2025-001",
    "description": "Construction d une villa moderne de 150m²",
    "adresse": "123 Rue de la Paix",
    "codePostal": "75001",
    "ville": "Paris",
    "clientId": "client-uuid",
    "statut": "PLANIFIE",
    "dateDebut": "2025-10-01",
    "dateFinPrevue": "2026-03-31",
    "montantPrevu": 250000.00,
    "surfaceM2": 150.00
  }'
```

### **Rechercher des chantiers**

```bash
curl -X GET "http://localhost:8080/api/v1/chantiers/search?q=villa&statut=EN_COURS&page=0&size=10" \
  -H "Authorization: Bearer $TOKEN"
```

### **Créer un devis avec lignes**

```bash
curl -X POST http://localhost:8080/api/v1/devis \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client-uuid",
    "chantierId": "chantier-uuid",
    "dateEmission": "2025-10-01",
    "dateValidite": "2025-11-01",
    "lignes": [
      {
        "designation": "Terrassement",
        "quantite": 1,
        "prixUnitaireHT": 5000.00
      },
      {
        "designation": "Maçonnerie",
        "quantite": 45,
        "prixUnitaireHT": 120.00
      }
    ]
  }'
```

### **Télécharger un PDF**

```bash
curl -X GET http://localhost:8080/api/v1/devis/{id}/pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/pdf" \
  --output devis.pdf
```

---

## 🔗 Liens utiles

- [Swagger UI](http://localhost:8080/q/swagger-ui)
- [Health Check](http://localhost:8080/q/health)
- [Metrics](http://localhost:8080/q/metrics)
- [OpenAPI Spec](http://localhost:8080/q/openapi)

---

**Dernière mise à jour**: 2025-09-30  
**Version**: 1.0  
**Auteur**: Équipe BTPXpress