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). Pour l'aspect de chaque thème et ce qui change pour les acheteurs, voir le guide marchand Thèmes.

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.
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`

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

curl https://api.dzbuild.app/v1/themes \
  -H "Authorization: Bearer $DZ_KEY"

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

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

Les mêmes que GET /v1/store : 401 unauthorized, 402 quota_exceeded, 403 forbidden, 404 not_found et 429 rate_limited. Voir Erreurs.

`POST /v1/store/theme`

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

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

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 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

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

{
  "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

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`

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

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

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 décrit chacun d'eux.

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

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

{
  "data": {
    "fast_checkout_theme": "stepper"
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

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`

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

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

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

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

{
  "data": {
    "variant_card_style": "minimal"
  },
  "meta": { "request_id": "...", "api_version": "v1" }
}

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.

Cette page pour les outils IAVoir en MarkdownOuvrir dans ChatGPT Ouvrir dans Claude

Avant de commencer​

GET /v1/themes​

Requête​

Réponse 200​

Référence des champs​

Erreurs​

POST /v1/store/theme​

Corps​

Passer à digital​

Requête​

Réponse 200​

Erreurs​

POST /v1/store/fast-checkout-theme​

Corps​

Thèmes Fast Checkout​

Requête​

Réponse 200​

Erreurs​

POST /v1/store/variant-style​

Corps​

Styles de variantes​

Requête​

Réponse 200​

Erreurs​

Avant de commencer

`GET /v1/themes`

Requête

Réponse 200

Référence des champs

Erreurs

`POST /v1/store/theme`

Corps

Passer à `digital`

Requête

Réponse 200

Erreurs

`POST /v1/store/fast-checkout-theme`

Corps

Thèmes Fast Checkout

Requête

Réponse 200

Erreurs

`POST /v1/store/variant-style`

Corps

Styles de variantes

Requête

Réponse 200

Erreurs