Aller au contenu principal

Créez des applications pour les boutiques DZBuild

DZBuild est la plateforme e-commerce des marchands algériens. Une application DZBuild est un service web que vous hébergez, sur votre propre compte Cloudflare ou votre propre serveur. Un marchand l'installe sur sa boutique, et votre application lit et modifie les commandes, les produits, la livraison, les clients et les messages WhatsApp de cette boutique via l'API REST.

Créer une applicationConnecter votre agent de code

Le marchand approuve sur DZBuild

Installer orders-bot sur votre boutique

orders-bot demande l'accès à votre boutique. Une fois approuvé, il pourra uniquement faire ce qui suit.

Ce que cette application pourra faire

Consulter les commandes (lecture seule ; aucune création ni modification) orders:read

RefuserApprouver et installer

Vous pouvez retirer l'application à tout moment depuis la page Extensions.

Votre serveur échange le code contre le jeton d'installation

POST https://dzbuild.com/oauth/apps/token

200 OK
{
  "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e...",
  "token_type": "Bearer",
  "scope": "orders:read",
  "store_id": 141,
  "install_id": 7,
  "stores": [
    {
      "store_id": 141,
      "store_name": "My test store",
      "install_id": 7,
      "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e..."
    }
  ]
}
Le flux OAuth

Comment fonctionne une application

  1. Enregistrez l'application

    Créez-la dans la console développeur. Vous obtenez un client_id, un secret client affiché une seule fois et un secret de signature pour les webhooks et les liens d'ouverture.

    Premiers pas

  2. Un marchand l'installe

    Envoyez le marchand vers l'URL d'autorisation avec un défi PKCE. Il approuve sur un écran de consentement DZBuild, et votre serveur échange le code contre un jeton d'installation par boutique.

    Le flux OAuth

  3. Appelez l'API

    Envoyez le jeton à api.dzbuild.app/v1. Interrogez GET /v1/orders?since= pour les nouvelles commandes, ou recevez des événements de commande signés sur une URL de webhook d'un domaine qui vous appartient (DZBuild refuse les adresses workers.dev). Testez sur votre propre boutique, puis soumettez l'application à la vérification.

    Webhooks

Ce que votre application peut atteindre

Un scope par type de données de boutique. Le marchand voit une ligne par ressource sur l'écran de consentement et n'accorde que ce que vous demandez. Tous les scopes

  • Commandes

    Lire les commandes et leurs articles. Créer des commandes, changer leur statut, les annuler.

    orders:readorders:write
  • Livraison

    Remettre une commande au transporteur de la boutique.

    delivery:send
  • Produits

    Catalogue et catégories, avec images, variantes, offres, règles de quantité et stock.

    products:readproducts:write
  • Clients

    Les clients et les commandes de chacun.

    customers:read
  • Pages de destination

    Les pages de destination et leurs sections, et le contrôle effectué avant la publication.

    landing_pages:readlanding_pages:write
  • Expédition

    Tarifs et réglages, transporteurs liés, couverture, listes des wilayas et des communes.

    shipping:readshipping:write
  • Boutique

    Profil, design, sections de la page d'accueil et thèmes.

    store:readstore:write
  • Codes promo et pixels

    Codes de réduction et pixels de suivi.

    promos:readpromos:writepixels:readpixels:write
  • Statistiques

    Statistiques et indicateurs de la boutique.

    analytics:read
  • WhatsApp

    Modèles de commande approuvés, solde du portefeuille de la boutique, journal des messages et envoi.

    whatsapp:readwhatsapp:send

Des règles sur lesquelles construire

Un jeton par boutique
Les jetons d'installation commencent par dzpk_live_, n'ont pas de date d'expiration et sont révoqués dès que le marchand désinstalle votre application.
120 requêtes par minute
Par installation, contrôlées avant le budget partagé de la boutique. Une réponse 429 porte l'en-tête Retry-After.
Idempotency-Key sur les écritures
POST, PATCH et DELETE en ont besoin. La réponse est conservée 24 heures et rejouée quand vous réessayez.
Webhooks HMAC-SHA256
X-DZ-Signature couvre l'horodatage et le corps brut. Rejetez tout ce qui a plus de 5 minutes. Jusqu'à 5 tentatives de livraison.
Les webhooks exigent votre propre domaine
DZBuild refuse les URL de webhook sur workers.dev. Tant que l'application ne tourne pas sur un domaine qui vous appartient, interrogez GET /v1/orders?since= une fois par minute.
Tous les plans
Chaque plan peut installer une application. Fixez un plan minimum dans la console si votre application en a besoin.
Vérification avant publication
Une application en brouillon ne tourne que sur vos boutiques. DZBuild la vérifie avant que d'autres marchands puissent l'installer.

Enregistrez votre première application

La console développeur se trouve dans votre tableau de bord DZBuild. Tout compte qui possède une boutique peut l'ouvrir, et une application en brouillon s'installe tout de suite sur votre boutique.

Ouvrir la console développeurRègles de vérification