Pour les revendeurs

Si vous construisez des vitrines pour des clients — agences, freelances, prestataires de fulfillment, opérateurs de marketplace — l'API DZBuild est conçue pour être votre colonne vertébrale opérationnelle.

Ce guide est pour vous si l'un de ces points s'applique :

Vous gérez 5+ boutiques DZBuild pour différents clients.
Vous facturez vos clients par commande ou au mois et avez besoin d'un signal d'usage fiable.
Vous construisez des thèmes ou vitrines personnalisés pour le compte de clients.
Vous vendez DZBuild en white-label (« MyAgency Commerce, propulsé par DZBuild »).
Vous voulez scripter des opérations en masse : import produits, mise à jour prix, confirmation de commandes.

Comment les revendeurs utilisent l'API en pratique

Setup typique :

                                ┌─────────────────────────┐
                                │ Votre back-office /     │
                                │ dashboard agence        │
                                │ (votre code, votre UI)  │
                                └──────────┬──────────────┘
                                           │  Bearer dzpk_live_…
                                           ▼
                            ┌─────────────────────────────┐
                            │  api.dzbuild.app/v1/*       │
                            └──────────┬──────────────────┘
                                       ▼
                           ┌──────────┬─────────┬──────────┐
                           │ Boutique A │ Boutique B │ Boutique C │   ← clients que vous gérez
                           └──────────┴─────────┴──────────┘

Chaque client a sa propre boutique DZBuild (son compte marchand, son plan, ses commandes). Vous détenez une clé API par boutique et orchestrez tout — onboarding, customizing, reporting — depuis votre propre dashboard.

Modèle de clés pour revendeurs

Pas de type « clé revendeur » spécial. Chaque revendeur travaille avec une clé plateforme par boutique cliente. Vous avez deux options :

A) Chaque client crée la clé et vous la partage (recommandé pour les relations à distance)

Le client se connecte à son dashboard, crée une clé, et vous donne le secret. Vous stockez les secrets clients dans votre back-office, chiffrés. Chaque opération sur le client X utilise la clé du client X.

Pour : consentement clair, le client possède la clé, peut la révoquer. Contre : friction d'onboarding (le client doit faire une étape).

B) Vous avez un accord algérien global avec DZBuild, et nous créons les clés pour vous

Pour les agences gérant 20+ boutiques, contactez-nous. On peut émettre une « umbrella agence » qui vous laisse créer les clés programmatiquement à mesure que vous onboardez. (Feature Pro+ / Enterprise.)

Pour : onboarding sans friction. Contre : nécessite un accord écrit ; vous êtes opérationnellement responsable de tout abus sur ces clés.

Imports produits en masse

Vous construisez un catalogue pour un client ? Boucle CSV → API :

import requests, csv, uuid, os

KEY = os.environ['DZ_KEY_CLIENT_X']
HEADERS = {
    'Authorization': f'Bearer {KEY}',
    'Content-Type':  'application/json',
}

with open('products.csv') as f:
    for row in csv.DictReader(f):
        body = {
            'name':           row['name'],
            'price':          float(row['price']),
            'compare_price':  float(row['compare_price']) if row['compare_price'] else None,
            'sku':            row['sku'],
            'description':    row['description'],
            'stock_quantity': int(row['stock']),
            'track_stock':    True,
            'status':         'active',
        }
        r = requests.post(
            'https://api.dzbuild.app/v1/products',
            headers={**HEADERS, 'Idempotency-Key': str(uuid.uuid4())},
            json=body,
        )
        if r.status_code == 201:
            print(f"OK {row['sku']} → id {r.json()['data']['id']}")
        else:
            print(f"FAIL {row['sku']}: {r.text}")

Astuces :

Utilisez une clé Idempotency déterministe (ex. import-{client}-{sku}-{run}) pour que les retries skippent les lignes déjà importées.
La limite pro_plus est de 5000 req/min — assez pour ~1000 produits en 30 secondes.
Les uploads d'images passent par le dashboard pour l'instant ; l'API supportera les R2 PUT presigned en v1.1.

Opérations bulk sur commandes

Confirmer toutes les pending d'un client

KEY="$(cat /etc/secrets/client-x.key)"
# 1. Lister pending
curl -sS 'https://api.dzbuild.app/v1/orders?status=pending&limit=200' \
  -H "Authorization: Bearer $KEY" \
| jq -r '.data.items[].id' \
| while read OID; do
    # 2. Confirmer chacune
    curl -sS -X PATCH "https://api.dzbuild.app/v1/orders/$OID" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: confirm-$OID" \
      -d '{"status":"confirmed"}'
  done

Rapport de revenu quotidien sur tous les clients

clients = json.load(open('clients.json'))  # [{name, key}, ...]
today = date.today().isoformat() + 'T00:00:00Z'

for c in clients:
    orders = requests.get(
        f'https://api.dzbuild.app/v1/orders?since={today}&limit=200',
        headers={'Authorization': f'Bearer {c["key"]}'},
    ).json()['data']['items']
    revenue = sum(o['total'] for o in orders if o['status'] == 'delivered')
    print(f"{c['name']}: {len(orders)} commandes, {revenue} DZD")

White-labeling

Vous voulez que vos vitrines aient l'aspect de votre marque, pas DZBuild. L'API le permet :

Construisez le front-end vous-même avec n'importe quelle stack/branding (voir Thèmes & vitrines personnalisés).
Utilisez votre propre domaine (shop.yourbrand.com) — pointez-le vers votre vitrine custom, qui parle à DZBuild via API.
Le dashboard marchand sur dzbuild.com/dashboard reste DZBuild-brandé — c'est là que vous (ou votre client) confirmez les commandes. Vos clients finaux ne voient jamais DZBuild.

Pour du white-label end-to-end avec dashboard marchand custom, voir les plans Enterprise.

Webhooks pour revendeurs

Enregistrez un webhook par boutique cliente pointant sur votre back-office :

curl -X POST 'https://api.dzbuild.app/v1/webhooks' \
  -H "Authorization: Bearer $CLIENT_X_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url":    "https://api.youragency.com/dz-hooks?store=client-x",
    "events": ["order.created","order.confirmed","order.shipped","order.delivered","order.cancelled"]
  }'

Utilisez le query parameter ?store=client-x pour qu'un seul endpoint gère tous les clients. Vérifiez la signature avec le secret par client pour confirmer que c'est bien DZBuild qui appelle.

Comptes multi-boutique

Certains clients gèrent plusieurs boutiques sur un compte DZBuild (feature Multi-store). Chaque boutique a sa propre clé — indépendantes. Nommez-les clairement dans votre coffre :

DZ_KEY_CLIENT_X_BRAND_A=dzpk_live_...
DZ_KEY_CLIENT_X_BRAND_B=dzpk_live_...

Plans — ce qu'on recommande

Taille client	Plan recommandé	Pourquoi
0–30 commandes/mois	Free	Validez l'idée avant de s'engager
30–500 commandes/mois	Pro	Lève les limites de commandes + ouvre l'API (tier `pro`)
500–2000 commandes/mois	Pro+	Limite API à 5000 req/min — nécessaire pour syncs en bulk
2000+ / multi-brand	Enterprise	Limite illimitée, contrat custom, support prioritaire

L'API en elle-même est inclus à partir de Pro. Les boutiques Free ne peuvent pas créer de clés API.

Facturer vos clients

L'API vous donne des signaux d'usage fiables :

GET /v1/usage — count des appels API du mois en cours, par groupe d'endpoints
GET /v1/usage/history — 12 derniers mois
GET /v1/orders?status=delivered&since=... — pour des modèles de commission par commande

La plupart des revendeurs facturent :

Forfait mensuel fixe pour l'hébergement vitrine + revente de la licence DZBuild
% de commission sur les commandes livrées (lu via ?status=delivered)
Ou un abonnement bundlé (ex. « 10000 DZD/mois pour tout »)

Choisissez le modèle attendu par votre marché.

Conseils opérationnels

Un environnement par client. Secrets dev en dev. Secrets prod en prod. Jamais de mélange.
Utilisez des Idempotency-Keys déterministes pour toute boucle de retry (surtout imports en bulk / confirmations en bulk).
Cachez les lectures produits. L'edge cache déjà 30 s mais vous pouvez ajouter une couche 5 min — les produits changent rarement à la minute.
Auto-rate-limitez-vous. Ne spikez pas à 5000 req/min dès que vous le pouvez — laissez de la marge pour le trafic organique du marchand.
Mettez des alertes Telegram sur 429 rate_limited, 5xx, ou échecs de webhook.
Audit trimestriel : rotation des clés pour les boutiques que vous ne gérez plus. Utilisez DELETE /v1/keys/{key_id}.

Référence

Authentification — Bearer + DZ-Public
Idempotence — requise sur toutes les écritures
Limites de taux — caps par tier
Webhooks — push au lieu de polling
Thèmes & vitrines personnalisés — build headless complet

Comment les revendeurs utilisent l'API en pratique​

Modèle de clés pour revendeurs​

A) Chaque client crée la clé et vous la partage (recommandé pour les relations à distance)​

B) Vous avez un accord algérien global avec DZBuild, et nous créons les clés pour vous​

Imports produits en masse​

Opérations bulk sur commandes​

Confirmer toutes les pending d'un client​

Rapport de revenu quotidien sur tous les clients​

White-labeling​

Webhooks pour revendeurs​

Comptes multi-boutique​

Plans — ce qu'on recommande​

Facturer vos clients​

Conseils opérationnels​

Référence​