Customers

Endpoints pour gérer les clients

Customers API

Endpoints pour consulter et créer des clients.

Lister les clients

GET /v1/public-api/customers

Scope requis: read:customers

Paramètres de requête

Paramètre	Type	Description
`page`	number	Numéro de page (défaut: 1)
`limit`	number	Éléments par page (défaut: 20, max: 100)

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/customers" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "data": [
    {
      "id": "cust_001",
      "firstName": "Jean",
      "lastName": "Dupont",
      "email": "jean.dupont@email.com",
      "phone": "+33612345678",
      "loyaltyTier": "GOLD",
      "loyaltyPoints": 1500,
      "totalOrders": 25,
      "totalSpent": 4520.00,
      "createdAt": "2023-06-15T10:00:00Z"
    }
  ],
  "total": 1250,
  "page": 1,
  "limit": 20,
  "totalPages": 63
}

Obtenir un client

GET /v1/public-api/customers/:id

Scope requis: read:customers

Paramètres de chemin

Paramètre	Type	Description
`id`	string	ID du client

Exemple de requête

curl -X GET "https://api.nerpsuite.com/v1/public-api/customers/cust_001" \
  -H "X-API-Key: sk_live_xxx"

Réponse

{
  "id": "cust_001",
  "firstName": "Jean",
  "lastName": "Dupont",
  "email": "jean.dupont@email.com",
  "phone": "+33612345678",
  "loyaltyTier": "GOLD",
  "loyaltyPoints": 1500,
  "totalOrders": 25,
  "totalSpent": 4520.00,
  "createdAt": "2023-06-15T10:00:00Z"
}

Créer un client

POST /v1/public-api/customers

Scope requis: write:customers

Corps de la requête

Champ	Type	Requis	Description
`firstName`	string	Oui	Prénom
`lastName`	string	Oui	Nom de famille
`email`	string	Non	Adresse email
`phone`	string	Non	Numéro de téléphone

Au moins un contact (email ou phone) est recommandé pour identifier le client.

Exemple de requête

curl -X POST "https://api.nerpsuite.com/v1/public-api/customers" \
  -H "X-API-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Marie",
    "lastName": "Martin",
    "email": "marie.martin@email.com",
    "phone": "+33698765432"
  }'

Réponse

{
  "id": "cust_002",
  "firstName": "Marie",
  "lastName": "Martin",
  "email": "marie.martin@email.com",
  "phone": "+33698765432",
  "loyaltyTier": "BRONZE",
  "loyaltyPoints": 0,
  "totalOrders": 0,
  "totalSpent": 0,
  "createdAt": "2024-01-25T14:30:00Z"
}

Champs de réponse

Champ	Type	Description
`id`	string	Identifiant unique
`firstName`	string	Prénom
`lastName`	string	Nom
`email`	string	Adresse email
`phone`	string	Numéro de téléphone
`loyaltyTier`	string	Niveau de fidélité (BRONZE, SILVER, GOLD, PLATINUM)
`loyaltyPoints`	number	Points de fidélité accumulés
`totalOrders`	number	Nombre total de commandes
`totalSpent`	number	Montant total dépensé
`createdAt`	string	Date de création (ISO 8601)

Niveaux de fidélité

Niveau	Seuil
BRONZE	0 - 999 points
SILVER	1000 - 4999 points
GOLD	5000 - 9999 points
PLATINUM	10000+ points

Cas d'usage

Synchronisation CRM

Importez vos clients depuis un CRM externe :

async function syncCustomerFromCRM(crmCustomer) {
  const response = await fetch('/v1/public-api/customers', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      firstName: crmCustomer.first_name,
      lastName: crmCustomer.last_name,
      email: crmCustomer.email,
      phone: crmCustomer.mobile
    })
  });

  return response.json();
}

Vérification avant commande

Vérifiez si un client existe avant de créer une commande :

async function getOrCreateCustomer(email, customerData) {
  // Chercher le client existant
  const customers = await fetch(`/v1/public-api/customers?email=${email}`, opts)
    .then(r => r.json());

  if (customers.data.length > 0) {
    return customers.data[0];
  }

  // Créer si non trouvé
  return fetch('/v1/public-api/customers', {
    method: 'POST',
    headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
    body: JSON.stringify(customerData)
  }).then(r => r.json());
}