API Clients - Gestion des clients fidélité

Cette documentation décrit les endpoints de l'API pour la gestion des clients du programme de fidélité.

Base URL

Environnements

Local (Nginx): http://localhost:649/api/publique/clients
Local (Backend direct): http://localhost:3000/api/publique/clients
Staging: https://fidelite.staging.ubsi.fr/api/publique/clients
Pré-production: https://fidelite.preprod.ubsi.fr/api/publique/clients
Production: https://fidelite.prod.ubsi.fr/api/publique/clients

Endpoints

1. Créer un client

POST /api/publique/clients

Crée un nouveau client dans le système de fidélité.

Body (JSON)

{
  "civilite": "M", // Optionnel: "M", "Mme" ou "Mx"
  "nom": "Dupont", // Obligatoire
  "prenom": "Jean", // Obligatoire
  "anniversaire": "1990-05-15", // Optionnel: format YYYY-MM-DD
  "adresseMail": "jean.dupont@example.com", // Obligatoire et unique
  "telephone": "0612345678", // Optionnel
  "adresse": "123 Rue de la Paix, 75001 Paris", // Optionnel
  "idClient": "CLI123", // Optionnel
  "niveauFidelisation": "Standard", // Optionnel: "Standard", "Premium" ou "Platine"
  "pointsFidelite": 0, // Optionnel: nombre >= 0
  "dateDebutFidelisation": "2023-10-10" // Optionnel: format YYYY-MM-DD
}

Réponse succès (201)

{
  "id": 40,
  "civilite": "M",
  "nom": "Dupont",
  "prenom": "Jean",
  "anniversaire": "1990-05-15",
  "adresseMail": "jean.dupont@example.com",
  "telephone": "0612345678",
  "adresse": "123 Rue de la Paix, 75001 Paris",
  "niveauFidelisation": "Standard",
  "pointsFidelite": 0,
  "dateDebutFidelisation": "2023-10-10"
}

Erreurs possibles

400 Bad Request - Validation échouée

{
  "message": ["Le nom est obligatoire", "L'adresse mail n'est pas valide"],
  "error": "Bad Request",
  "statusCode": 400
}

409 Conflict - Email déjà existant

Deux messages possibles selon le statut du client existant :

Client actif :

{
  "statusCode": 409,
  "message": "Un client avec cette adresse mail existe déjà"
}

Client supprimé (soft-deleted) :

{
  "statusCode": 409,
  "message": "Un client avec cette adresse mail a été supprimé. Veuillez contacter un administrateur pour réactiver le compte."
}

Note : Si vous essayez de créer un compte avec l'email d'un client précédemment supprimé, vous devez contacter un administrateur qui peut réactiver le compte via l'API d'import.

Exemple avec curl

curl -X POST 'http://localhost:3000/api/publique/clients' \
  -H 'Content-Type: application/json' \
  -d '{
    "civilite": "M",
    "nom": "Dupont",
    "prenom": "Jean",
    "anniversaire": "1990-05-15",
    "adresseMail": "jean.dupont@example.com",
    "telephone": "0612345678",
    "pointsFidelite": 0
  }'

2. Lister les clients

GET /api/publique/clients

Récupère une liste paginée de tous les clients actifs (non supprimés).

Query Parameters

page (optionnel): Numéro de page (défaut: 1)
limit (optionnel): Nombre d'éléments par page (défaut: 10)
nom (optionnel): Recherche par nom ou prénom

Réponse succès (200)

{
  "data": [
    {
      "id": 1,
      "civilite": "M",
      "nom": "Dupont",
      "prenom": "Jean",
      "anniversaire": "1990-05-15",
      "adresseMail": "jean.dupont@example.com",
      "telephone": "0612345678",
      "niveauFidelisation": "Standard",
      "pointsFidelite": 150,
      "dateDebutFidelisation": "2023-01-15",
      "createdAt": "2023-01-15T10:00:00.000Z",
      "updatedAt": "2023-10-01T14:30:00.000Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

Exemples avec curl

# Liste tous les clients (page 1, 10 éléments)
curl -X GET 'http://localhost:3000/api/publique/clients'

# Liste avec pagination personnalisée
curl -X GET 'http://localhost:3000/api/publique/clients?page=2&limit=20'

# Recherche par nom
curl -X GET 'http://localhost:3000/api/publique/clients?nom=Dupont'

3. Récupérer un client

GET /api/publique/clients/:id

Récupère les détails d'un client spécifique par son ID.

Path Parameters

id: Identifiant du client (nombre)

Réponse succès (200)

{
  "id": 1,
  "civilite": "M",
  "nom": "Dupont",
  "prenom": "Jean",
  "anniversaire": "1990-05-15",
  "adresseMail": "jean.dupont@example.com",
  "telephone": "0612345678",
  "niveauFidelisation": "Premium",
  "pointsFidelite": 500,
  "dateDebutFidelisation": "2023-01-15",
  "createdAt": "2023-01-15T10:00:00.000Z",
  "updatedAt": "2023-10-01T14:30:00.000Z",
  "deletedAt": null
}

Erreur (404)

{
  "statusCode": 404,
  "message": "Client with id 999 not found"
}

Exemple avec curl

curl -X GET 'http://localhost:3000/api/publique/clients/1'

Règles de validation

Champs obligatoires

nom: Chaîne de caractères non vide
prenom: Chaîne de caractères non vide
adresseMail: Email valide et unique

Champs optionnels avec validation

Champ	Type	Validation	Message d'erreur
`civilite`	Enum	"M", "Mme" ou "Mx"	"La civilité doit être une des valeurs suivantes: M, Mme, Mx"
`anniversaire`	Date	Format YYYY-MM-DD, pas dans le futur	"La date d'anniversaire doit être au format YYYY-MM-DD (ex: 1990-05-15)"
`telephone`	String	Chiffres, espaces et caractères +()-.	"Le téléphone ne peut contenir que des chiffres, espaces et caractères +()-."
`niveauFidelisation`	Enum	"Standard", "Premium" ou "Platine"	"Le niveau de fidélisation doit être: Standard, Premium ou Platine"
`pointsFidelite`	Number	Entier >= 0	"Les points de fidélité ne peuvent pas être négatifs"
`dateDebutFidelisation`	Date	Format YYYY-MM-DD	"La date de début de fidélisation doit être au format YYYY-MM-DD"

Comportement par défaut

Si niveauFidelisation n'est pas fourni, il est défini à "Standard"
Si niveauFidelisation est fourni mais pas dateDebutFidelisation, la date du jour est utilisée

Exemples d'erreurs de validation

Points de fidélité négatifs

Requête:

curl -X POST 'http://localhost:3000/api/publique/clients' \
  -H 'Content-Type: application/json' \
  -d '{
    "nom": "Test",
    "prenom": "User",
    "adresseMail": "test@example.com",
    "pointsFidelite": -100
  }'

Réponse (400):

{
  "message": ["Les points de fidélité ne peuvent pas être négatifs"],
  "error": "Bad Request",
  "statusCode": 400
}

Format de date invalide

Requête:

curl -X POST 'http://localhost:3000/api/publique/clients' \
  -H 'Content-Type: application/json' \
  -d '{
    "nom": "Test",
    "prenom": "User",
    "adresseMail": "test@example.com",
    "dateDebutFidelisation": "invalid-date"
  }'

Réponse (400):

{
  "message": [
    "La date de début de fidélisation doit être au format YYYY-MM-DD (ex: 2023-10-10)"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

Civilité invalide

Requête:

curl -X POST 'http://localhost:3000/api/publique/clients' \
  -H 'Content-Type: application/json' \
  -d '{
    "civilite": "Invalid",
    "nom": "Test",
    "prenom": "User",
    "adresseMail": "test@example.com"
  }'

Réponse (400):

{
  "message": [
    "La civilité doit être une des valeurs suivantes: M, Mme, Mx (reçu: Invalid)"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

Documentation Swagger

Pour une documentation interactive complète, accédez à Swagger UI selon votre environnement:

Local: http://localhost:649/api/swagger
Staging: https://fidelite.staging.ubsi.fr/api/swagger
Pré-production: https://fidelite.preprod.ubsi.fr/api/swagger
Production: https://fidelite.prod.ubsi.fr/api/swagger

Cette interface permet de tester directement les endpoints depuis votre navigateur.

Base URL​

Environnements​

Endpoints​

1. Créer un client​

Body (JSON)​

Réponse succès (201)​

Erreurs possibles​

Exemple avec curl​

2. Lister les clients​

Query Parameters​

Réponse succès (200)​

Exemples avec curl​

3. Récupérer un client​

Path Parameters​

Réponse succès (200)​

Erreur (404)​

Exemple avec curl​

Règles de validation​

Champs obligatoires​

Champs optionnels avec validation​

Comportement par défaut​

Exemples d'erreurs de validation​

Points de fidélité négatifs​

Format de date invalide​

Civilité invalide​

Documentation Swagger​

Base URL

Environnements

Endpoints

1. Créer un client

Body (JSON)

Réponse succès (201)

Erreurs possibles

Exemple avec curl

2. Lister les clients

Query Parameters

Réponse succès (200)

Exemples avec curl

3. Récupérer un client

Path Parameters

Réponse succès (200)

Erreur (404)

Exemple avec curl

Règles de validation

Champs obligatoires

Champs optionnels avec validation

Comportement par défaut

Exemples d'erreurs de validation

Points de fidélité négatifs

Format de date invalide

Civilité invalide

Documentation Swagger