Aller au contenu principal

Premiers pas

Cette page vous mène d'une console développeur vide à un premier appel authentifié à l'API. Vous enregistrez une application, vous l'installez sur une boutique dont vous êtes propriétaire, vous échangez le code contre un jeton d'installation et vous appelez GET /v1/whoami.

Avant de commencer​

  • Un compte DZBuild propriétaire d'au moins une boutique. Une installation de test ne fonctionne que sur une boutique appartenant à votre compte, pas sur une boutique dont vous êtes membre d'équipe.
  • Une adresse de redirection en https que votre application contrôle. La console refuse http. Le plus rapide est un Worker sur workers.dev créé depuis /apps/new, enregistré une seule fois ; un tunnel https vers votre machine fonctionne aussi, mais son adresse change à chaque lancement et la console accepte au plus 5 adresses de redirection.
  • curl et openssl sur votre machine.

Partir de l'application exemple​

Le plus rapide est /apps/new : choisissez l'un des trois presets Cloudflare, déployez-le sur une adresse workers.dev gratuite et obtenez les valeurs exactes à saisir dans la console.

  • cloudflare-basic : le flux d'installation, un jeton par boutique et le lien d'ouverture. La base de votre propre application.
  • cloudflare-catalog : une page produits pour le marchand et un export CSV du catalogue.
  • cloudflare-orders : des alertes Telegram à chaque nouvelle commande en interrogeant GET /v1/orders une fois par minute ; les webhooks de commande dès que vous avez un domaine.

Créez le preset cloudflare-basic en une commande, ou déployez-le depuis le navigateur avec le bouton ci-dessous. Cloudflare le clone dans votre compte GitHub et le déploie ; le README du preset liste les étapes qui suivent.

npm create cloudflare@latest my-app -- --template DZBuild-com/dzbuild-app-starter/cloudflare-basic --no-agents --no-git --no-deploy --no-open

Déployer sur Cloudflare

Si vous hébergez plutôt l'application sur votre propre serveur, l'exemple Node.js du même dépôt suit le même flux, sans dépendance et avec des tests hors ligne. Remplissez les variables d'environnement de .env.example depuis votre console.

1. Enregistrer l'application​

Ouvrez la console développeur sur https://dzbuild.com/dashboard/developer et choisissez Nouvelle application (/dashboard/developer/apps/new). Remplissez le formulaire :

ChampÀ saisir
NomLe nom de l'application que les marchands voient sur l'écran de consentement.
Nom du développeurVotre nom ou celui de votre société, affiché sur l'écran de consentement.
DescriptionsUne description en anglais, une en arabe et une en français.
Site webLe site de votre application, en https uniquement. Le bouton Installer de la page Extensions du marchand ouvre cette adresse, ou le lien d'ouverture si elle est vide : elle doit donc mener à votre flux d'installation.
E-mail du supportL'adresse à laquelle les marchands écrivent pour obtenir de l'aide.
Lien d'ouvertureLa page https qui s'ouvre quand un marchand clique sur Ouvrir dans votre application.
Adresses de redirectionD'une à cinq adresses exactes. DZBuild n'envoie le code d'autorisation qu'à ces adresses.
ScopesLes permissions que votre application peut demander. Voir Scopes.
Plan minimumLe plan de boutique le plus bas qui peut utiliser votre application. Laissez Free pour accepter toutes les boutiques.
Adresse et événements du webhookFacultatif. Voir Webhooks.

Enregistrez l'application. La console affiche alors trois identifiants :

IdentifiantFormatOù le garder
client_iddzapp_ suivi de 20 caractères hexadécimauxPublic. Il figure dans l'URL d'autorisation.
Client secretdzas_ suivi de 48 caractères hexadécimauxAffiché une seule fois. Conservez-le sur votre serveur. Générez-en un nouveau dans la console si vous le perdez.
Secret de signature64 caractères hexadécimauxConsultable dans la console. Il signe les webhooks et les jetons d'ouverture.

La nouvelle application est un brouillon. Un brouillon ne fonctionne que sur les boutiques de votre propre compte, ce qui suffit pour tester.

2. Choisir les scopes​

N'enregistrez que les scopes que votre application utilise. Sur l'écran de consentement, le marchand voit une ligne par ressource demandée. À l'installation, le paramètre scope permet d'en demander moins que ceux enregistrés, jamais plus. La liste complète figure sur la page Scopes.

3. Définir les adresses de redirection​

DZBuild compare le redirect_uri envoyé à vos adresses enregistrées, chaîne contre chaîne. Une barre oblique finale, une casse différente ou un paramètre de requête en plus en font une autre adresse. Une adresse qui contient un fragment (#) est refusée à l'enregistrement de l'application.

Si le redirect_uri ne correspond pas, DZBuild affiche une page d'erreur et ne redirige pas du tout.

4. Installer l'application sur votre boutique​

Créez un vérificateur PKCE et son défi S256. Le vérificateur reste sur votre serveur.

CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
STATE=$(openssl rand -hex 16)

Ouvrez l'URL d'autorisation dans votre navigateur. Encodez chaque valeur ; les espaces entre scopes deviennent %20.

GET https://dzbuild.com/oauth/apps/authorize?response_type=code&client_id=dzapp_0123456789abcdef0123&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=store%3Aread%20orders%3Aread&state=STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

Connectez-vous à DZBuild si on vous le demande. L'écran de consentement liste vos boutiques et signale celles qui ne peuvent pas installer l'application. Choisissez une boutique et approuvez. DZBuild redirige vers votre adresse :

HTTP/1.1 302 Found
Location: https://app.example.com/callback?code=CODE&state=STATE

Vérifiez que state est bien la valeur envoyée. Le code est valable 10 minutes et ne sert qu'une fois.

Échangez le code contre un jeton d'installation. Envoyez le formulaire depuis votre serveur, jamais depuis un navigateur.

curl -s https://dzbuild.com/oauth/apps/token \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  --data-urlencode redirect_uri=https://app.example.com/callback \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id="$DZ_CLIENT_ID" \
  -d client_secret="$DZ_CLIENT_SECRET"

Une réponse réussie ressemble à ceci :

{
  "access_token": "dzpk_live_0a1b2c3d4e5f67.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928",
  "token_type": "Bearer",
  "scope": "store:read 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.9f8e7d6c5b4a39281706f5e4d3c2b1a09f8e7d6c5b4a3928"
    }
  ]
}

Conservez chaque access_token avec son store_id et son install_id. Il n'y a ni expires_in ni jeton de rafraîchissement : le jeton fonctionne jusqu'à ce que le marchand désinstalle votre application. La page OAuth liste toutes les erreurs possibles de cet appel.

5. Faire votre premier appel​

Appelez GET /v1/whoami avec le jeton d'installation. Cet endpoint ne demande aucun scope, il fonctionne donc pour toute installation.

curl -s https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer $DZ_TOKEN"
{
  "data": {
    "key_id": "dzpk_live_0a1b2c3d4e5f67",
    "store_id": 141,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["store:read", "orders:read"],
    "app": {
      "app_id": 3,
      "client_id": "dzapp_0123456789abcdef0123",
      "install_id": 7
    }
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

6. Lire l'objet app​

L'objet app n'apparaît que si le jeton appartient à une installation d'application. Il indique à votre serveur quelle application et quelle installation ont fait l'appel.

ChampSignification
app_idL'identifiant numérique de votre application sur DZBuild.
client_idL'identifiant public de votre application. Comparez-le au vôtre pour rejeter les jetons émis pour une autre application.
install_idL'installation à laquelle appartient ce jeton. Il reste le même si le marchand désinstalle puis réinstalle votre application sur la même boutique.

rate_limit_tier vaut enterprise pour tout jeton d'installation, quel que soit le plan de la boutique. Votre vrai quota est la limite par installation décrite dans Concepts clés.

Étapes suivantes​

Cette page pour les outils IAVoir en MarkdownOuvrir dans ChatGPTOuvrir dans Claude