# Thèmes

L'apparence d'une boutique repose sur trois choix, les trois onglets de la page Thèmes du tableau de bord (`/dashboard/themes`) : le thème de la boutique, le thème du formulaire de commande Fast Checkout sur les pages produit, et le style du sélecteur de variantes. `GET /v1/themes` liste les thèmes de boutique avec un verdict pour la boutique, et un appel `POST` change chacun des trois choix. Les couleurs, les textes et les autres champs de design se modifient avec `PATCH /v1/store/design` (voir [Boutique](https://dzbuild.com/fr/fr/api-docs/resources/store.md)). Pour l'aspect de chaque thème et ce qui change pour les acheteurs, voir le guide marchand [Thèmes](https://dzbuild.com/fr/fr/docs/customizing/themes.md).

## Avant de commencer[​](#avant-de-commencer "Lien direct vers Avant de commencer")

* `GET /v1/themes` demande `store:read`. Les trois changements demandent `store:write` et une `Idempotency-Key`. Les clés marchand ont les deux scopes.
* Chaque thème et chaque style a un plan minimum. Les plans se classent `free`, `pro`, `unlimited`, `enterprise`, et un plan ouvre tout ce qu'ouvrent les plans en dessous. Passer à un thème ou un style au-dessus du plan de la boutique répond `403 plan_required`. Un plan payant expiré compte comme `free`.
* Une clé marchand appartient à une boutique sur un plan Enterprise actif : tous les thèmes et styles lui sont ouverts. Les jetons d'application installée fonctionnent avec tous les plans et sont soumis à ces limites.
* Un changement est enregistré dès que l'appel répond. Il n'y a pas d'étape de confirmation.
* La première réponse à une `Idempotency-Key` est rejouée pendant 24 heures, erreurs `4xx` comprises. Après un changement de plan de la boutique, renvoyez le changement avec une nouvelle clé. Voir [Idempotence](https://dzbuild.com/fr/fr/api-docs/idempotency.md).
* Chaque changement est enregistré et peut être annulé avec `POST /v1/changes/{change_id}/undo` ; retrouvez son id avec `GET /v1/changes?entity=store.theme`. Le jeton d'une application installée ne peut ni lire ni annuler les changements : les deux répondent `403 forbidden` (`Apps cannot use this endpoint`).

## `GET /v1/themes`[​](#get-v1themes "Lien direct vers get-v1themes")

Liste les thèmes de boutique avec le plan que demande chacun et si cette boutique peut l'utiliser, plus la clé du thème utilisé. La liste entière arrive en une réponse, sans pagination. Un thème qui ne peut plus être choisi reste dans la liste avec `active: false`.

**Auth :** clé plateforme avec `store:read`. Cet appel n'est pas mis en cache : chaque réponse lit l'état actuel.

### Requête[​](#requête "Lien direct vers Requête")

```
curl https://api.dzbuild.app/v1/themes \

  -H "Authorization: Bearer $DZ_KEY"
```

### Réponse 200[​](#réponse-200 "Lien direct vers Réponse 200")

Trois éléments sont montrés. Les titres arrivent dans la langue de la boutique, et cette boutique est réglée en français.

```
{

  "data": {

    "current": "starter",

    "items": [

      {

        "key":           "starter",

        "title":         "Starter",

        "plan_required": "free",

        "active":        true,

        "color_mode":    "light",

        "digital_only":  false,

        "can_use":       true,

        "current":       true

      },

      {

        "key":           "digital",

        "title":         "Digital",

        "plan_required": "free",

        "active":        true,

        "color_mode":    "dark",

        "digital_only":  true,

        "can_use":       true,

        "current":       false

      },

      {

        "key":           "ariana",

        "title":         "Ariana",

        "plan_required": "unlimited",

        "active":        false,

        "color_mode":    "dark",

        "digital_only":  false,

        "can_use":       false,

        "current":       false

      }

    ]

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

### Référence des champs[​](#référence-des-champs "Lien direct vers Référence des champs")

| Champ                   | Type   | Notes                                                                                                                                   |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `current`               | string | Clé du thème utilisé par la boutique.                                                                                                   |
| `items[].key`           | string | La valeur à envoyer dans `theme` à `POST /v1/store/theme`.                                                                              |
| `items[].title`         | string | Le nom du thème dans la langue de la boutique : arabe, ou français pour une boutique en français.                                       |
| `items[].plan_required` | string | Le plan le plus bas qui peut utiliser le thème.                                                                                         |
| `items[].active`        | bool   | `false` pour un thème qui ne peut plus être choisi.                                                                                     |
| `items[].color_mode`    | string | `light` ou `dark`.                                                                                                                      |
| `items[].digital_only`  | bool   | `true` pour un thème réservé aux produits digitaux. Le choisir change le type de la boutique, comme décrit sous `POST /v1/store/theme`. |
| `items[].can_use`       | bool   | `true` quand le thème est actif et que le plan de la boutique atteint `plan_required`.                                                  |
| `items[].current`       | bool   | `true` pour le thème utilisé.                                                                                                           |

### Erreurs[​](#erreurs "Lien direct vers Erreurs")

Les mêmes que `GET /v1/store` : `401 unauthorized`, `402 quota_exceeded`, `403 forbidden`, `404 not_found` et `429 rate_limited`. Voir [Erreurs](https://dzbuild.com/fr/fr/api-docs/errors.md).

## `POST /v1/store/theme`[​](#post-v1storetheme "Lien direct vers post-v1storetheme")

Change le thème de la boutique. Seul le thème change : les couleurs, les textes et les autres valeurs de design restent tels quels, et le nouveau thème affiche ceux qu'il utilise. Passer à `digital` est l'exception décrite plus bas.

**Auth :** clé plateforme avec `store:write`. **Nécessite `Idempotency-Key`.**

### Corps[​](#corps "Lien direct vers Corps")

| Champ   | Type   | Requis | Notes                                                                                        |
| ------- | ------ | ------ | -------------------------------------------------------------------------------------------- |
| `theme` | string | oui    | Une `key` de `GET /v1/themes`. Lettres latines, chiffres, `_` et `-`, jusqu'à 50 caractères. |

### Passer à `digital`[​](#passer-à-digital "Lien direct vers passer-à-digital")

`digital` est le thème qui porte `digital_only: true`. Y passer transforme la boutique en boutique de produits digitaux, et la réponse porte `is_digital: true`. Passer une boutique digitale à n'importe quel autre thème la ramène en boutique de produits physiques. Le guide marchand [Thèmes](https://dzbuild.com/fr/fr/docs/customizing/themes.md) explique ce qui change pour les acheteurs.

Le passage à `digital` remplace aussi les couleurs encore sur les valeurs claires d'origine, comme un fond `#ffffff`, par la palette sombre de Digital. Les couleurs choisies par le marchand sont gardées. Annuler le changement remet le thème précédent et ces couleurs.

### Requête[​](#requête-1 "Lien direct vers Requête")

```
curl -X POST https://api.dzbuild.app/v1/store/theme \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: store-theme-1" \

  -d '{"theme": "bloom"}'
```

### Réponse 200[​](#réponse-200-1 "Lien direct vers Réponse 200")

```
{

  "data": {

    "theme":      "bloom",

    "is_digital": false

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

Via `api.dzbuild.app`, un `GET /v1/store/design` envoyé juste après le changement peut encore montrer l'ancien thème pendant 30 secondes au plus. `GET /v1/themes` n'est pas mis en cache.

### Erreurs[​](#erreurs-1 "Lien direct vers Erreurs")

| HTTP | Code                    | Cause                                                                                                                   |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`           | Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.                                       |
| 403  | `forbidden`             | `Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.                     |
| 403  | `plan_required`         | Le thème demande un plan plus élevé. Le message nomme ce plan et celui de la boutique.                                  |
| 404  | `theme_not_found`       | Aucun thème actif ne porte cette clé.                                                                                   |
| 404  | `store_not_found`       | La boutique a été supprimée.                                                                                            |
| 422  | `invalid_theme`         | `theme` manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, `_` et `-`. |
| 422  | `idempotency_key_reuse` | La même `Idempotency-Key` a été utilisée avec un autre corps.                                                           |

## `POST /v1/store/fast-checkout-theme`[​](#post-v1storefast-checkout-theme "Lien direct vers post-v1storefast-checkout-theme")

Change l'apparence du formulaire de commande Fast Checkout sur les pages produit. Les textes, les couleurs et les options du formulaire, qui sont des champs de `PATCH /v1/store/design`, restent tels quels.

**Auth :** clé plateforme avec `store:write`. **Nécessite `Idempotency-Key`.**

### Corps[​](#corps-1 "Lien direct vers Corps")

| Champ   | Type   | Requis | Notes                                                                                        |
| ------- | ------ | ------ | -------------------------------------------------------------------------------------------- |
| `theme` | string | oui    | Une clé du tableau ci-dessous. Lettres latines, chiffres, `_` et `-`, jusqu'à 50 caractères. |

### Thèmes Fast Checkout[​](#thèmes-fast-checkout "Lien direct vers Thèmes Fast Checkout")

Aucun appel ne liste ces thèmes, et aucune lecture ne renvoie celui qui est utilisé. Chaque boutique démarre sur `classic`. Le guide marchand [Thèmes](https://dzbuild.com/fr/fr/docs/customizing/themes.md) décrit chacun d'eux.

| `theme`     | Plan         |
| ----------- | ------------ |
| `classic`   | `free`       |
| `commerce`  | `pro`        |
| `editorial` | `unlimited`  |
| `compact`   | `enterprise` |
| `stepper`   | `enterprise` |

### Requête[​](#requête-2 "Lien direct vers Requête")

```
curl -X POST https://api.dzbuild.app/v1/store/fast-checkout-theme \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: store-fc-theme-1" \

  -d '{"theme": "stepper"}'
```

### Réponse 200[​](#réponse-200-2 "Lien direct vers Réponse 200")

```
{

  "data": {

    "fast_checkout_theme": "stepper"

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

### Erreurs[​](#erreurs-2 "Lien direct vers Erreurs")

| HTTP | Code                    | Cause                                                                                                                   |
| ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`           | Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.                                       |
| 403  | `forbidden`             | `Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.                     |
| 403  | `plan_required`         | Le thème demande un plan plus élevé que celui de la boutique.                                                           |
| 404  | `theme_not_found`       | Aucun thème Fast Checkout actif ne porte cette clé.                                                                     |
| 404  | `store_not_found`       | La boutique a été supprimée.                                                                                            |
| 422  | `invalid_theme`         | `theme` manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, `_` et `-`. |
| 422  | `idempotency_key_reuse` | La même `Idempotency-Key` a été utilisée avec un autre corps.                                                           |

## `POST /v1/store/variant-style`[​](#post-v1storevariant-style "Lien direct vers post-v1storevariant-style")

Change la façon dont les choix de variantes, comme les tailles et les couleurs, s'affichent sur les pages produit.

**Auth :** clé plateforme avec `store:write`. **Nécessite `Idempotency-Key`.**

### Corps[​](#corps-2 "Lien direct vers Corps")

| Champ   | Type   | Requis | Notes                                                 |
| ------- | ------ | ------ | ----------------------------------------------------- |
| `style` | string | oui    | Une clé du tableau ci-dessous, jusqu'à 50 caractères. |

### Styles de variantes[​](#styles-de-variantes "Lien direct vers Styles de variantes")

Aucun appel ne liste les styles, et aucune lecture ne renvoie celui qui est utilisé. Chaque boutique démarre sur `default`, le sélecteur standard sans style ajouté, et toute boutique peut y revenir. Une clé inconnue ou inactive répond `404 style_not_found` ; l'API ne revient jamais d'elle-même à `default`.

| Plan           | `style`                                         |
| -------------- | ----------------------------------------------- |
| tous les plans | `default`                                       |
| `pro`          | `minimal`, `clay`, `softplay`, `stacked`        |
| `unlimited`    | `editorial`, `material`, `offer`                |
| `enterprise`   | `brutal`, `glass`, `lux`, `mashrabiya`, `pixel` |

### Requête[​](#requête-3 "Lien direct vers Requête")

```
curl -X POST https://api.dzbuild.app/v1/store/variant-style \

  -H "Authorization: Bearer $DZ_KEY" \

  -H "Content-Type: application/json" \

  -H "Idempotency-Key: store-variant-style-1" \

  -d '{"style": "minimal"}'
```

### Réponse 200[​](#réponse-200-3 "Lien direct vers Réponse 200")

```
{

  "data": {

    "variant_card_style": "minimal"

  },

  "meta": { "request_id": "...", "api_version": "v1" }

}
```

### Erreurs[​](#erreurs-3 "Lien direct vers Erreurs")

| HTTP | Code                    | Cause                                                                                               |
| ---- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| 400  | `bad_request`           | Le corps n'est pas un JSON valide, ou `Idempotency-Key` manque ou est mal formée.                   |
| 403  | `forbidden`             | `Missing scope: store:write`, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif. |
| 403  | `plan_required`         | Le style demande un plan plus élevé que celui de la boutique.                                       |
| 404  | `style_not_found`       | Aucun style actif ne porte cette clé.                                                               |
| 404  | `store_not_found`       | La boutique a été supprimée.                                                                        |
| 422  | `invalid_style`         | `style` manque, est vide ou dépasse 50 caractères.                                                  |
| 422  | `idempotency_key_reuse` | La même `Idempotency-Key` a été utilisée avec un autre corps.                                       |