# Concepts clés

## Applications[​](#applications "Lien direct vers 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](https://dzbuild.dev/fr/fr/review-guidelines.md) listent ce que la vérification contrôle.

## Mode test[​](#mode-test "Lien direct vers 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[​](#boutiques "Lien direct vers 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[​](#installations "Lien direct vers 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[​](#plans-et-min_plan "Lien direct vers 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[​](#limite-de-requêtes-par-installation "Lien direct vers 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](https://dzbuild.dev/fr/fr/rate-limits.md) explique comment espacer les nouvelles tentatives.

## Jetons d'installation[​](#jetons-dinstallation "Lien direct vers 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`                                                                          |