lionsdev/btpxpress-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7494ed1ec5ec27e13d064e53ae0e87ca8ad6330b
btpxpress-backend/API.md
dahoud f2bb633142 Initial commit
2025-10-01 01:37:34 +00:00

9.2 KiB
Raw Blame History

🌐 API REST - BTPXPRESS BACKEND

📋 Table des matières

🎯 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

🔐 Authentification

OAuth2 / OIDC avec Keycloak

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

1. Obtenir un token

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 :

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

2. Utiliser le token

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

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

Réponse paginée

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

🔍 Filtrage et tri

Filtres

# 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

# 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

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

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

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

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

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

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

🔗 Liens utiles

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