Concepts clés

Applications

Une application est la fiche que vous créez dans la console développeur. Elle contient vos identifiants, vos adresses de redirection, les scopes que vous pouvez demander, vos réglages de webhook et un plan minimum. Chaque application a un statut :

Statut	Qui peut l'installer	Effet sur les installations existantes
draft	Le développeur seul, sur les boutiques de son compte	Les jetons fonctionnent sur les boutiques du développeur
in_review	Le développeur seul, sur les boutiques de son compte	Les jetons fonctionnent sur les boutiques du développeur. Une application approuvée renvoyée en vérification après une modification garde chaque installation existante en marche.
approved	Tout propriétaire de boutique	Les jetons fonctionnent
rejected	Personne	Chaque appel répond 403 avec app_suspended
suspended	Personne	Chaque appel répond 403 avec app_suspended

DZBuild vérifie l'application une fois que vous l'avez envoyée depuis la console. Les règles de vérification listent ce que la vérification contrôle.

Mode test

Une application en brouillon ou en vérification fonctionne en mode test. L'écran de consentement ne l'accepte que pour le développeur qui la possède, et seulement sur les boutiques de son compte. Vous pouvez ainsi construire et tester tout le parcours avant la vérification, avec les vraies données de votre boutique.

L'API applique la même règle à chaque appel. Si l'application n'a encore jamais été approuvée et que l'installation appartient à une autre personne que le développeur, l'appel répond 403 avec app_not_approved et le message This app is in test mode and only runs on its developer's stores.

Boutiques

Une boutique est un site de vente DZBuild, avec ses produits, ses commandes et son plan. Un même compte marchand peut posséder plusieurs boutiques.

• Seul le propriétaire de la boutique peut installer une application. L'écran de consentement ne liste que les boutiques du compte connecté ; un membre d'équipe ne peut donc pas choisir une boutique sur laquelle il travaille.
• Un même consentement peut couvrir jusqu'à 10 boutiques. Chaque boutique reçoit sa propre installation et son propre jeton.
• Un jeton ne lit et ne modifie que la boutique pour laquelle il a été émis. La réponse du jeton liste chaque boutique installée dans stores et reprend la première au niveau supérieur.

Installations

Une installation relie une application à une boutique. Il existe au plus une installation par application et par boutique.

Le marchand lance une installation depuis la page Extensions de son tableau de bord. Le bouton Installer ouvre l'adresse de votre site web, ou votre lien d'ouverture si aucun site n'est défini, dans un nouvel onglet. DZBuild n'envoie pas le marchand vers l'URL d'autorisation à votre place : cette page doit donc lancer le flux OAuth.

• L'installation est créée quand votre serveur échange le code sur l'endpoint token, pas quand le marchand clique sur approuver.
• Si le marchand réinstalle votre application sur la même boutique, l'installation garde son install_id. DZBuild émet un nouveau jeton, révoque l'ancien et enregistre les scopes du dernier consentement.
• Seul le marchand peut désinstaller, depuis la page de votre application dans son tableau de bord. Il n'existe pas d'endpoint de révocation pour les applications.

Quand un marchand désinstalle votre application, DZBuild fait quatre choses en une fois : il marque l'installation comme désinstallée, révoque le jeton, abandonne les livraisons de webhook encore en attente pour votre adresse, et met en file un seul événement app.uninstalled si votre adresse est vérifiée et active. Ensuite, l'ancien jeton répond 401.

Plans et min_plan

Chaque boutique DZBuild est sur l'un de quatre plans, du plus bas au plus haut : free, pro, unlimited, enterprise. Tous les plans peuvent installer une application. L'exigence du plan Enterprise pour les clés API des marchands ne s'applique pas aux jetons d'installation.

Vous pouvez relever ce seuil avec min_plan dans la console. La valeur par défaut est free, qui accepte toutes les boutiques.

• Sur l'écran de consentement, une boutique sous min_plan est marquée comme non éligible et ne peut pas être choisie.
• À chaque appel à l'API, une boutique sous min_plan répond 403 avec app_plan_required et un message qui nomme le plan, par exemple This app requires the Pro plan.
• Un plan payant expiré compte comme free dans les deux contrôles.

Limite de requêtes par installation

Chaque installation dispose de son propre quota de 120 requêtes par minute. La fenêtre est une minute fixe d'horloge : le compteur repart à zéro au début de chaque minute.

Le quota de l'installation est vérifié en premier. Ensuite, la requête compte aussi dans le quota par minute partagé de la boutique, qu'utilisent les clés du marchand et les autres applications. Une application qui s'emballe atteint sa propre limite avant d'épuiser celle de la boutique.

Au-delà de la limite, l'API répond 429 avec un en-tête Retry-After et ce corps :

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute API limit exceeded for this app install",
    "retry_after": 42
  },
  "meta": {
    "request_id": "5f2c9a0b1d3e4f60",
    "api_version": "v1"
  }
}

Si le quota de la boutique s'épuise en premier, le message est Per-minute API limit exceeded for this store. La page Limites de requêtes explique comment espacer les nouvelles tentatives.

Jetons d'installation

Un jeton d'installation est le jeton bearer que votre serveur reçoit de l'endpoint token. C'est une clé API du même type que celles que crée un marchand, marquée comme appartenant à votre installation.

Ce qu'est un jeton d'installation :

• Un jeton bearer qui commence par dzpk_live_, envoyé dans Authorization: Bearer ....
• Un jeton par installation, donc un par boutique.
• Limité aux scopes acceptés par le marchand, et contrôlé par les mêmes règles de scope que toute autre clé.
• Présenté par GET /v1/whoami avec rate_limit_tier: enterprise quel que soit le plan, le vrai quota étant la limite par installation ci-dessus.
• Valable sans date d'expiration. L'endpoint token ne renvoie ni expires_in ni jeton de rafraîchissement.
• Révoqué quand le marchand désinstalle votre application, et remplacé quand il la réinstalle.

Ce que n'est pas un jeton d'installation :

• Ce n'est pas une clé marchand. Il n'apparaît pas sur la page des clés API du marchand et ne compte pas dans sa limite de clés.
• Il ne gère ni les clés, ni les webhooks, ni le journal des modifications. Les appels à /v1/keys, /v1/webhooks et /v1/changes répondent 403 avec le code forbidden et le message Apps cannot use this endpoint.
• Il n'est pas lié à la session d'une personne. Il continue de fonctionner quand le marchand se déconnecte.
• Il ne couvre pas plusieurs boutiques. Utilisez le jeton émis pour chaque boutique.

Chaque refus propre aux applications répond 403 avec l'enveloppe d'erreur :

Code	Message	Cause
app_uninstalled	This app is no longer installed on this store	L'installation n'est plus active
app_suspended	This app has been suspended by DZBuild	L'application est suspendue ou refusée
app_not_approved	This app is in test mode and only runs on its developer's stores	L'application n'a encore jamais été approuvée et le propriétaire de la boutique n'est pas le développeur
app_plan_required	This app requires the Pro plan (le nom du plan varie)	La boutique est sous min_plan