Aller au contenu principal

Import de clients en masse

Cette documentation explique comment utiliser l'endpoint d'import pour charger plusieurs clients en une seule requête.

Endpoint​

POST /api/privee/clients/import

Note de sécurité : Cette route fait partie de l'API privée car l'import massif de clients est une opération administrative sensible.

Format de la requête​

{
  "clients": [
    {
      "civilite": "M",
      "nom": "Dupont",
      "prenom": "Jean",
      "adresseMail": "jean.dupont@example.com",
      "telephone": "0123456789",
      "adresse": "123 Rue de la Paix, 75001 Paris",
      "niveauFidelisation": "Premium",
      "pointsFidelite": 500
    }
    // ... autres clients
  ]
}

Paramètres​

  • clients (obligatoire) : Array de clients à importer. Chaque client suit le même format que l'endpoint de création (POST /api/publique/clients).

Comportement​

L'import fonctionne en mode upsert (create, update or reactivate) :

  • Si un client actif avec le même email existe → il est mis à jour avec les nouvelles données
  • Si un client supprimé avec le même email existe → il est réactivé (restauré) et mis à jour avec les nouvelles données
  • Si aucun client avec cet email n'existe → un nouveau client est créé

Format de la réponse​

{
  "summary": {
    "createdCount": 10,
    "updatedCount": 5,
    "reactivatedCount": 2,
    "errorCount": 1,
    "total": 18
  },
  "details": {
    "created": [
      {
        "id": 40,
        "nom": "Dupont",
        "prenom": "Jean",
        "adresseMail": "jean.dupont@example.com"
        // ... autres champs
      }
      // ... autres clients créés
    ],
    "updated": [
      {
        "id": 12,
        "nom": "Martin",
        "prenom": "Sophie",
        "adresseMail": "sophie.martin@example.com"
        // ... autres champs
      }
      // ... autres clients mis à jour
    ],
    "reactivated": [
      {
        "id": 5,
        "nom": "Bernard",
        "prenom": "Luc",
        "adresseMail": "luc.bernard@example.com"
        // ... autres champs
      }
      // ... autres clients réactivés
    ],
    "errors": [
      {
        "email": "invalid@example.com",
        "error": "Le téléphone ne peut contenir que des chiffres..."
      }
    ]
  }
}

Exemples d'utilisation​

Import de nouveaux clients​

curl -X POST 'http://localhost:649/api/privee/clients/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "clients": [
      {
        "nom": "Dupont",
        "prenom": "Jean",
        "adresseMail": "jean.dupont@example.com",
        "telephone": "0123456789"
      },
      {
        "nom": "Martin",
        "prenom": "Sophie",
        "adresseMail": "sophie.martin@example.com",
        "niveauFidelisation": "Premium"
      }
    ]
  }'

Résultat : Les nouveaux clients sont créés.

Import avec mise à jour automatique​

curl -X POST 'http://localhost:649/api/privee/clients/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "clients": [
      {
        "nom": "Dupont",
        "prenom": "Jean",
        "adresseMail": "jean.dupont@example.com",
        "pointsFidelite": 1000
      }
    ]
  }'

Résultat : Si le client existe (même email), il est mis à jour automatiquement. Sinon, il est créé.

Fichiers exemples​

Des fichiers JSON d'exemple sont disponibles dans frontend/public/ :

  • sample-clients.json : 2 clients basiques
  • sample-clients-1.json : 2 clients avec plus de détails
  • sample-clients-2.json : Plus d'exemples
  • sample-clients-3.json : Encore plus d'exemples

Validation​

Chaque client importé passe par les mêmes validations que l'endpoint de création :

  • Champs obligatoires : nom, prenom, adresseMail
  • Email unique : L'adresse mail doit être valide et unique
  • Formats de dates : YYYY-MM-DD
  • Énumérations :
    • civilite : M, Mme, Mx
    • niveauFidelisation : Standard, Premium, Platine

Comportement par défaut​

  • Si niveauFidelisation n'est pas fourni → "Standard"
  • Si niveauFidelisation est fourni mais pas dateDebutFidelisation → date du jour

Note importante : le champ idClient est désormais généré automatiquement côté serveur au format CLI_XXXXXXX. Ne fournissez pas idClient dans vos fichiers d'import — la présence de ce champ déclenchera une erreur de validation.

Gestion des erreurs​

  • Erreur de validation : Le client est ajouté à details.errors avec le message d'erreur
  • Client actif existant : Le client est automatiquement mis à jour et ajouté à details.updated
  • Client supprimé existant : Le client est automatiquement réactivé (restauré), mis à jour et ajouté à details.reactivated
  • Nouveau client : Le client est créé et ajouté à details.created

L'import continue même en cas d'erreur sur un client individuel. Le résumé final indique combien de clients ont été créés, mis à jour, réactivés ou en erreur.

Réactivation de clients supprimés​

Si vous importez un client avec un email qui appartenait à un client soft-deleted (supprimé) :

  1. Le système détecte automatiquement le client supprimé
  2. Il réactive le client en mettant deletedAt à null
  3. Il met à jour toutes les données du client avec les nouvelles valeurs fournies
  4. Le client est ajouté à details.reactivated dans la réponse

Cette fonctionnalité permet de restaurer facilement des clients supprimés par erreur ou de réimporter d'anciens clients.

Codes de statut HTTP​

  • 201 Created : Import réussi (même si certains clients ont échoué, consultez le rapport)
  • 400 Bad Request : Format de requête invalide (ex: clients manquant)