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 rapproche sur boutique + téléphone. Si le client existe déjà, son email/adresse/wilaya sont mis à jour et sa fiche réutilisée ; sinon une nouvelle fiche est créée. L'email n'est pas utilisé pour la déduplication — historiquement, les marchands reçoivent beaucoup de commandes anonymes sans email.
Quand un client est créé via POST /v1/orders, la chaîne customer.name entière est stockée dans first_name et last_name est laissé vide — la séparation prénom/nom montrée dans les exemples ci-dessous ne se produit jamais pour les enregistrements créés par l'API. Pour un client existant retrouvé par téléphone, seul first_name est écrasé et tout last_name existant reste intact. Séparez côté client si vous en avez besoin.
GET /v1/customers
Liste les clients de votre boutique. Pagination par curseur.
Auth : n'importe quelle clé plateforme active de la boutique (customers:read est accordé par défaut et n'est pas vérifié séparément en v1).
Paramètres de requête
Param | Type | Notes |
| int 1–200 | Défaut 50 |
| string | Opaque |
| string | Match exact, insensible à la casse |
| string | Match exact, insensible à la casse |
Il n'existe en v1 aucun filtre par date, recherche libre, tri ni filtre is_banned ; les résultats sont toujours triés par id décroissant.
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
}
}
⚠️ Attention — total_orders / total_spent sont des compteurs figés, pas des agrégats en temps réel
Ils ne sont incrémentés que lorsqu'une commande est passée depuis une landing page ou créée manuellement dans le tableau de bord. Ils ne sont jamais ajustés lors d'un changement de statut (une commande annulée reste comptée), et les commandes créées via la vitrine ou POST /v1/orders ne les mettent jamais à jour. Ne les utilisez pas pour du reporting de chiffre d'affaires — agrégez vous-même GET /v1/orders (ou /v1/customers/{id}/orders).
GET /v1/customers/{id}
Détail complet.
Auth : n'importe quelle clé plateforme active de la boutique (customers:read n'est pas vérifié séparément en v1).
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": 0,
"is_banned": false,
"created_at": "2026-03-17 15:18:13",
"updated_at": "2026-04-15 12:01:08"
}
}
Champ | Notes |
| Commentaire privé marchand, défini dans le tableau de bord |
| Toujours |
| Défini quand vous blacklistez le client dans le tableau de bord. Les checkouts vitrine et landing page rejettent les clients blacklistés — mais |
Signaux d'appareil / d'identité | Non exposés 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 : n'importe quelle clé plateforme active de la boutique (customers:read n'est pas vérifié séparément en v1).
L'id client est d'abord contrôlé en propriété : un id inconnu, ou appartenant à une autre boutique, renvoie 404 not_found, pas une liste vide.
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-AD3C91F7", "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 d'empreinte d'appareil ni aucun lien d'identité inter-boutiques.
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.