Clients

Les clients sont les utilisateurs finaux qui ont passé une commande sur votre vitrine. Ils sont créés automatiquement au premier checkout — il n'y a pas de flux d'inscription public en v1. Chaque client est scopé à une seule boutique : le même numéro de téléphone sur deux boutiques différentes crée deux lignes customer.

Déduplication : à chaque nouveau checkout, on cherche (store_id, phone). Si une ligne existe, on met à jour email/adresse/wilaya et on la réutilise. Sinon on crée. L'email n'est pas utilisé pour la déduplication — historiquement, les marchands reçoivent beaucoup de commandes anonymes sans email.

GET /v1/customers

Liste les clients de votre boutique. Pagination par curseur.

Auth : clé plateforme avec customers:read.

Paramètres de requête

Param	Type	Notes
limit	int 1–200	Défaut 50
cursor	string	Opaque
phone	string	Match exact
email	string	Match exact (sensible à la casse en v1)

Requête

curl 'https://api.dzbuild.app/v1/customers?limit=20' \
  -H "Authorization: Bearer $DZ_KEY"

Réponse 200

{
  "data": {
    "items": [
      {
        "id":           5578,
        "first_name":   "John",
        "last_name":    "Doe",
        "phone":        "0555000000",
        "email":        null,
        "wilaya_id":    16,
        "commune":      "Bab Ezzouar",
        "total_orders": 3,
        "total_spent":  4500,
        "is_banned":    false,
        "created_at":   "2026-03-17 15:18:13",
        "updated_at":   "2026-04-15 12:01:08"
      }
    ],
    "next_cursor": "NDk=",
    "has_more": true
  }
}

total_orders et total_spent sont maintenus à jour par la plateforme à chaque changement de statut des commandes du client ; vous n'avez pas à les recalculer.

GET /v1/customers/{id}

Détail complet.

Auth : clé plateforme avec customers:read.

Réponse 200

{
  "data": {
    "id":           5578,
    "first_name":   "John",
    "last_name":    "Doe",
    "phone":        "0555000000",
    "email":        "[email protected]",
    "wilaya_id":    16,
    "commune":      "Bab Ezzouar",
    "address":      "12 Rue X",
    "notes":        "Prefers afternoon delivery",
    "total_orders": 3,
    "total_spent":  4500,
    "fraud_score":  10,
    "is_banned":    false,
    "created_at":   "2026-03-17 15:18:13",
    "updated_at":   "2026-04-15 12:01:08"
  }
}

Champ	Notes
notes	Commentaire privé marchand, défini dans le tableau de bord
fraud_score	0-100 heuristique interne (haut = suspect)
is_banned	Défini si vous l'avez blacklisté dans le dashboard. Les futures commandes sont auto-rejetées.
device_fingerprint	Non exposé via API pour des raisons de confidentialité

GET /v1/customers/{id}/orders

Commandes du client, paginées par curseur, plus récentes d'abord.

Auth : clé plateforme avec customers:read.

Requête

curl 'https://api.dzbuild.app/v1/customers/5578/orders?limit=10' \
  -H "Authorization: Bearer $DZ_KEY"

Réponse 200

{
  "data": {
    "items": [
      { "id": 6894, "order_number": "ORD-13-20260317-AD3C", "status": "confirmed",
        "payment_status": "pending", "total": 1000, "created_at": "2026-03-17 15:18:13" }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

C'est un sous-ensemble de /v1/orders filtré par customer_id — les champs sont les mêmes que le résumé liste de commandes. Pour le corps complet, appelez /v1/orders/{id}.

Patterns courants

« Trouver un client par téléphone, puis lister ses commandes »

PHONE="0555000000"
CUST=$(curl -sS "https://api.dzbuild.app/v1/customers?phone=$PHONE&limit=1" \
  -H "Authorization: Bearer $DZ_KEY" | jq -r '.data.items[0].id')

[ -z "$CUST" ] && { echo "no customer"; exit 1; }

curl -sS "https://api.dzbuild.app/v1/customers/$CUST/orders" \
  -H "Authorization: Bearer $DZ_KEY"

« Top 10 dépensiers ce mois-ci »

Pas de filtre tri-par-dépense natif en v1. Parcourez la liste clients et triez côté client ; le dataset est petit (boutique typique < 5K clients actifs). Ou requêtez /v1/orders?since=... et agrégez par customer_id.

Notes de confidentialité

• L'API n'expose jamais device_fingerprint ni identity_id (lien d'identité cross-boutique).
• L'email/téléphone client sont des données personnelles — soyez prudent avec les logs.
• Les futures demandes de droit à l'oubli (style RGPD) doivent passer par dashboard / support ; l'API recevra un endpoint DELETE /v1/customers/{id} dans une version future avec des règles de cascade explicites.