Créer une application e-commerce en Algérie avec DZBuild.dev
Un export de catalogue, une notification de commande ou un outil pour une agence qui gère les boutiques de ses clients : chaque projet pose la même question. Comment l'application obtient-elle l'accord du propriétaire pour accéder aux bonnes données ?
dzbuild.dev est le portail développeur de DZBuild. Il rassemble l'API e-commerce, les applications de démarrage, les guides d'installation et les ressources pour les assistants de programmation. Ce guide suit un premier projet concret : une application qui permet au marchand de télécharger son catalogue de produits au format CSV, avec la seule permission de lire les produits.
Le créateur d'applications public, capturé le 1er octobre 2026. La capture ne contient aucun compte marchand ni aucune donnée de boutique.
Ce que vous pouvez construire avec l'API DZBuild
Une application DZBuild est un service web que vous hébergez. Un marchand approuve ses permissions sur DZBuild et votre serveur reçoit un jeton d'accès pour cette boutique. Votre application appelle ensuite l'API REST pour accéder aux ressources autorisées. Chaque boutique où l'application est installée dispose de son propre jeton. L'introduction pour les développeurs explique ce fonctionnement.
Pour les projets e-commerce en Algérie, l'API couvre les produits, les commandes, les clients, la livraison, les paramètres d'expédition, les pages de destination, la personnalisation de la boutique, les statistiques et les modèles de messages WhatsApp liés aux commandes. L'accès dépend des permissions demandées et des conditions propres à chaque fonctionnalité. Envoyer un colis ou un message WhatsApp reste une action distincte ; installer une application ne déclenche aucun de ces envois.
Vous pouvez, par exemple, développer un export de catalogue, une connexion à votre outil de reporting ou des alertes de commande pour une équipe. Les applications de démarrage officielles fournissent des bases pour ces usages :
| Application de démarrage | Ce qu'elle fournit | Quand la choisir |
|---|---|---|
| Application de base | Installation sur une boutique, lien d'ouverture et gestion des jetons | Vous voulez ajouter vos propres écrans et votre logique métier |
| Export du catalogue | Liste de produits et téléchargement CSV | Vous cherchez un premier projet qui lit les produits sans modifier la boutique |
| Notifications de commandes | Alertes Telegram pour les nouvelles commandes, par interrogation périodique de l'API par défaut | Vous avez besoin d'un exemple d'alertes et savez que les données de commande seront transmises à un autre service |
Le créateur d'applications génère les instructions de configuration correspondant au modèle choisi. Le dépôt de démarrage public comprend aussi un exemple Node.js pour votre propre serveur.
Applications installées et clés API personnelles ont des conditions différentes
Un marchand n'a pas besoin du plan Entreprise uniquement pour installer une application approuvée. Les applications sont accessibles sur les différents plans, sous réserve du plan minimum fixé par l'application et des conditions propres aux fonctionnalités utilisées. Les clés API personnelles des marchands nécessitent un abonnement Entreprise actif. Les concepts clés et la référence de l'API expliquent cette distinction.
Pour un outil destiné aux marchands, utilisez le parcours d'installation d'application. Le propriétaire voit les permissions avant de donner son accord et l'application reçoit un jeton distinct par boutique. Ne demandez pas à un client de partager son mot de passe de tableau de bord ou de coller une clé API personnelle dans une conversation.
Les applications en brouillon sont réservées aux boutiques appartenant au compte développeur. Être membre de l'équipe d'une autre boutique ne suffit pas. L'application doit être approuvée avant que d'autres marchands puissent l'installer.
Créer une application d'export de catalogue
Le modèle d'export utilise products:read. Il n'a pas besoin de lire les clients, de modifier les commandes ou d'envoyer des colis. Le résultat est donc facile à vérifier : la liste des produits doit correspondre à celle de la boutique et le fichier téléchargé doit contenir les lignes attendues.
Il vous faut un compte DZBuild propriétaire d'une boutique et un hébergement pour votre application. Pour le modèle Cloudflare, prévoyez aussi votre propre compte Cloudflare et les accès de déploiement décrits dans son README. Les limites et les frais d'hébergement dépendent de votre fournisseur.
1. Choisir Export du catalogue
Ouvrez Créer une application, choisissez Export du catalogue et conservez uniquement les permissions nécessaires à cette fonctionnalité. Donnez un nom à votre application. Les règles d'enregistrement interdisent « dzbuild » dans son nom.
Le créateur fournit une option de déploiement, des commandes à exécuter sur votre machine et les champs à recopier dans la console développeur. Gardez le README du modèle d'export ouvert ; il contient les étapes de configuration de ce modèle.
2. Déployer et configurer le stockage
Déployez le modèle sur votre compte d'hébergement. Le bouton de déploiement ne suffit pas à terminer la configuration du modèle d'export. Son README demande d'appliquer la migration de base de données fournie après le premier déploiement par bouton, ou de configurer la commande de déploiement documentée pour qu'elle l'applique. Cette étape prépare le stockage de l'application pour les données d'installation.
Utilisez l'adresse HTTPS exacte attribuée à votre application. Le modèle peut démarrer sur une adresse workers.dev. Si vous ajoutez ensuite des webhooks, il vous faudra un domaine adapté dont vous êtes propriétaire.
3. Enregistrer l'application et protéger ses identifiants
Ouvrez la console développeur et créez une application. Recopiez les adresses de retour et d'ouverture indiquées dans vos instructions de déploiement, sélectionnez products:read, puis renseignez les descriptions et les coordonnées du support.
Pour une application hébergée à l'adresse d'exemple https://app.example.com, les adresses du modèle seraient :
| Champ d'enregistrement | Valeur d'exemple |
|---|---|
| URI de redirection | https://app.example.com/oauth/callback |
| Lien d'ouverture | https://app.example.com/launch |
| Scope | products:read |
| URL du webhook | Laisser vide pour ce premier exemple d'export |
Remplacez le domaine d'exemple par le vôtre. L'adresse de retour doit correspondre exactement à la valeur enregistrée, y compris la barre oblique finale. Consultez le guide des premiers pas pour le formulaire complet.
Remplacez l'identifiant client du modèle par celui obtenu lors de l'enregistrement, puis redéployez comme indiqué dans son README. Enregistrez le secret client et le secret de signature dans le stockage de secrets de votre hébergeur, comme indiqué par le modèle. Conservez les jetons d'accès aux boutiques sur votre serveur. Aucun de ces secrets ne doit figurer dans le code du navigateur, une capture d'écran, un dépôt public ou une consigne envoyée à un assistant de programmation.
4. Installer l'application sur votre boutique
Ouvrez la page d'installation de votre application et approuvez la permission de lecture des produits pour votre boutique. Le modèle gère le parcours d'autorisation OAuth avec PKCE et conserve le jeton de cette installation.
Les tests d'une application en brouillon utilisent les vraies données de la boutique. Il ne s'agit pas d'un environnement de test isolé. Utilisez une boutique que vous contrôlez et commencez par cette fonctionnalité en lecture seule. Si vous ajoutez des permissions d'écriture, vos tests devront tenir compte des modifications réelles et de leurs effets.
Le premier contrôle API documenté est GET /v1/whoami, qui confirme la boutique et les permissions du jeton. Dans votre environnement de développement sécurisé, où DZ_TOKEN contient déjà le jeton d'installation, la requête est :
curl -sS https://api.dzbuild.app/v1/whoami \
-H "Authorization: Bearer $DZ_TOKEN"
Cette requête lit l'identité de l'installation. Elle ne crée ni ne modifie de commande. Ne partagez pas les identifiants de compte retournés ni le jeton.
5. Ouvrir l'application et vérifier le CSV
Utilisez l'action Ouvrir dans le tableau de bord marchand, puis téléchargez le catalogue. Comparez le fichier avec les produits de votre boutique de test. Le modèle exporte l'identifiant du produit, le nom, le slug, le SKU, le prix et le statut ; son README décrit la sortie UTF-8 pour les noms en arabe.
Vérifiez un catalogue vide, un nom de produit en arabe et un nom contenant une virgule ou des guillemets. Pour un catalogue plus volumineux, contrôlez le nombre de lignes exportées sans supposer que le premier écran affiche tous les produits. L'écran du modèle affiche jusqu'à 200 produits ; l'export parcourt les pages de résultats, dans les limites d'exécution de l'hébergeur.
Un export qui échoue est une erreur à corriger. Une permission manquante, une session d'application expirée ou une limite de requêtes ne doit pas se traduire par un fichier incomplet présenté au marchand comme son catalogue entier.
Connecter un assistant de programmation à la documentation
La page de connexion des agents fournit les instructions pour les assistants de programmation. Le serveur public @dzbuild/docs-mcp donne aux clients compatibles accès à la documentation développeur et à la référence de l'API. Il n'accède pas à votre compte marchand et n'effectue aucune action sur votre boutique.
Vous pouvez aussi transmettre à un assistant l'index de la documentation, la compétence de création d'applications et la description OpenAPI. Voici une consigne ciblée :
Lis la documentation développeur DZBuild et le modèle d'export du catalogue. Aide-moi à créer une application d'export utilisant uniquement
products:read. Conserve les identifiants dans un stockage de secrets côté serveur. Teste les catalogues vides, les noms en arabe, la pagination, le refus d'installation et la révocation d'accès.
Relisez le code généré et exécutez ses tests avant de lui donner accès aux données d'une boutique. Le guide Développer avec l'IA décrit les erreurs courantes, comme demander des permissions inutiles ou supposer qu'un jeton donne accès à plusieurs boutiques.
Avant d'ajouter des webhooks ou des actions qui modifient une boutique
L'exemple d'export fonctionne sans webhook. Pour les événements de commande ou les notifications de désinstallation, enregistrez et vérifiez l'URL du webhook dans la console développeur. Une adresse workers.dev n'est pas acceptée comme destination ; l'application a besoin d'un domaine adapté dont vous êtes propriétaire. Les jetons d'installation ne permettent pas de gérer l'endpoint marchand /v1/webhooks. Suivez le guide des webhooks pour les applications.
Vérifiez la signature des webhooks avant de traiter leur contenu, gérez les livraisons en double et cessez d'utiliser le jeton d'une boutique lorsque l'accès est révoqué. Les requêtes POST, PATCH et DELETE nécessitent un Idempotency-Key, et une réponse 429 impose d'attendre le délai indiqué par Retry-After. Le guide des limites de requêtes détaille ces règles.
Pour ajouter des envois WhatsApp, consultez d'abord le guide d'intégration WhatsApp. Une permission accordée à l'application ne supprime pas les conditions de plan ou de crédits de messages propres à cette fonctionnalité.
Préparer l'application pour sa validation
Avant de la soumettre, testez l'application sur votre boutique et préparez son logo, ses descriptions en anglais, en arabe et en français, l'adresse e-mail du support, son adresse d'ouverture HTTPS, son adresse de retour et les permissions nécessaires. Si vous avez configuré un webhook, il doit être vérifié. La liste des conditions de validation donne les exigences exactes.
Décrivez ce que l'application lit, ce qu'elle modifie et comment les marchands peuvent obtenir de l'aide. Un export de catalogue devrait demander la permission de lire les produits ; ajouter des accès sans rapport rend son usage plus difficile à évaluer. Consultez les exigences de sécurité pour la gestion des identifiants et des données marchandes.
Une fois approuvée, l'application devient accessible aux marchands éligibles. L'approbation ne garantit ni installations ni revenus : les marchands doivent encore y trouver un usage clair et un support fiable.
Questions avant de commencer
DZBuild héberge-t-il mon application ?
Vous hébergez l'application sur votre propre compte d'hébergement ou serveur. DZBuild fournit la connexion à la boutique et l'API. Les modèles officiels prennent en charge Cloudflare Workers et le dépôt comprend un exemple Node.js.
Puis-je tester un brouillon sur la boutique d'un client ?
Les installations en brouillon fonctionnent uniquement sur les boutiques appartenant à votre compte développeur. Pour la boutique d'un client, l'application doit être approuvée avant que son propriétaire puisse l'installer.
Que se passe-t-il lorsqu'un marchand désinstalle l'application ?
Le jeton d'installation est révoqué. L'application doit gérer la perte d'accès. Le modèle d'export explique comment traiter les réponses non autorisées lorsqu'aucun webhook de désinstallation n'est configuré.
Par où commencer ?
Ouvrez Créer une application sur dzbuild.dev, sélectionnez Export du catalogue et suivez les instructions du modèle avec le guide des premiers pas. Si vous n'avez pas encore de compte DZBuild, utilisez la page d'inscription.