Aller au contenu principal

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 options des trois choix avec un verdict pour la boutique, et un appel POST change chacun d'eux. 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 : la réponse porte son change_id, null dans le cas rare où le changement est enregistré sans trace d'annulation, et GET /v1/changes?entity=store.theme liste les précédents. 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, les thèmes du formulaire Fast Checkout et les styles du sélecteur de variantes, chacun avec le plan qu'il demande et si cette boutique peut l'utiliser, plus la clé du thème de boutique utilisé. La liste entière arrive en une réponse, sans pagination. Un thème ou un style qui ne peut plus être choisi reste dans sa 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 thèmes de boutique et deux éléments de chaque autre liste 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
}
],
"fast_checkout": [
{
"key": "classic",
"title": "Classique",
"plan_required": "free",
"active": true,
"can_use": true,
"current": true
},
{
"key": "stepper",
"title": "Stepper",
"plan_required": "enterprise",
"active": true,
"can_use": false,
"current": false
}
],
"variant_styles": [
{
"key": "default",
"title": "Par défaut",
"plan_required": "free",
"active": true,
"can_use": true,
"current": true
},
{
"key": "lux",
"title": "Luxe",
"plan_required": "enterprise",
"active": true,
"can_use": false,
"current": false
}
]
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Référence des champs​

ChampTypeNotes
currentstringClé du thème utilisé par la boutique.
items[].keystringLa valeur à envoyer dans theme à POST /v1/store/theme.
items[].titlestringLe nom du thème dans la langue de la boutique : arabe, ou français pour une boutique en français.
items[].plan_requiredstringLe plan le plus bas qui peut utiliser le thème.
items[].activeboolfalse pour un thème qui ne peut plus être choisi.
items[].color_modestringlight ou dark.
items[].digital_onlybooltrue 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_usebooltrue quand le thème est actif et que le plan de la boutique atteint plan_required.
items[].currentbooltrue pour le thème utilisé.
fast_checkout[].keystringLa valeur à envoyer dans theme à POST /v1/store/fast-checkout-theme.
fast_checkout[].titlestringLe nom du thème de formulaire dans la langue de la boutique.
fast_checkout[].plan_requiredstringLe plan le plus bas qui peut utiliser le thème de formulaire.
fast_checkout[].activeboolfalse pour un thème de formulaire qui ne peut plus être choisi.
fast_checkout[].can_usebooltrue quand le thème de formulaire est actif et que le plan de la boutique atteint plan_required.
fast_checkout[].currentbooltrue pour le thème de formulaire utilisé. Chaque boutique démarre sur classic.
variant_styles[].keystringLa valeur à envoyer dans style à POST /v1/store/variant-style. Le premier élément est toujours default, le sélecteur standard sans style ajouté, que tous les plans peuvent utiliser et qui est current tant que la boutique l'utilise.
variant_styles[].titlestringLe nom du style dans la langue de la boutique.
variant_styles[].plan_requiredstringLe plan le plus bas qui peut utiliser le style.
variant_styles[].activeboolfalse pour un style qui ne peut plus être choisi.
variant_styles[].can_usebooltrue quand le style est actif et que le plan de la boutique atteint plan_required.
variant_styles[].currentbooltrue pour le style utilisé. Un style enregistré qui n'est plus actif compte comme default.

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​

ChampTypeRequisNotes
themestringouiUne 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,
"change_id": 813
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Via api.dzbuild.app, un GET /v1/store/design envoyé juste après le changement renvoie le nouveau thème. GET /v1/themes est servi à neuf lui aussi.

Erreurs​

HTTPCodeCause
400bad_requestLe corps n'est pas un JSON valide, ou Idempotency-Key manque ou est mal formée.
403forbiddenMissing scope: store:write, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403plan_requiredLe thème demande un plan plus élevé. Le message nomme ce plan et celui de la boutique.
404theme_not_foundAucun thème actif ne porte cette clé.
404store_not_foundLa boutique a été supprimée.
422invalid_themetheme manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, _ et -.
422idempotency_key_reuseLa 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​

ChampTypeRequisNotes
themestringouiUne key de la liste fast_checkout de GET /v1/themes. Lettres latines, chiffres, _ et -, jusqu'à 50 caractères.

Thèmes Fast Checkout​

GET /v1/themes liste ces thèmes dans fast_checkout, avec le plan que demande chacun, si la boutique peut l'utiliser et celui qui est utilisé ; GET /v1/store renvoie aussi celui qui est utilisé dans fast_checkout_theme. Chaque boutique démarre sur classic. Le guide marchand Thèmes décrit chacun d'eux.

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",
"change_id": 814
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Erreurs​

HTTPCodeCause
400bad_requestLe corps n'est pas un JSON valide, ou Idempotency-Key manque ou est mal formée.
403forbiddenMissing scope: store:write, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403plan_requiredLe thème demande un plan plus élevé que celui de la boutique.
404theme_not_foundAucun thème Fast Checkout actif ne porte cette clé.
404store_not_foundLa boutique a été supprimée.
422invalid_themetheme manque, dépasse 50 caractères ou contient un caractère autre que des lettres latines, des chiffres, _ et -.
422idempotency_key_reuseLa 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​

ChampTypeRequisNotes
stylestringouiUne key de la liste variant_styles de GET /v1/themes, jusqu'à 50 caractères.

Styles de variantes​

GET /v1/themes liste les styles dans variant_styles, avec le plan que demande chacun, si la boutique peut l'utiliser et celui qui est utilisé ; GET /v1/store renvoie aussi celui qui est utilisé dans variant_card_style. Chaque boutique démarre sur default, le sélecteur standard sans style ajouté, qui est le premier élément de la liste et auquel toute boutique peut revenir. Une clé inconnue ou inactive répond 404 style_not_found ; l'API ne revient jamais d'elle-même à default.

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",
"change_id": 815
},
"meta": { "request_id": "...", "api_version": "v1" }
}

Erreurs​

HTTPCodeCause
400bad_requestLe corps n'est pas un JSON valide, ou Idempotency-Key manque ou est mal formée.
403forbiddenMissing scope: store:write, ou clé du marchand dont la boutique n'a pas de plan Enterprise actif.
403plan_requiredLe style demande un plan plus élevé que celui de la boutique.
404style_not_foundAucun style actif ne porte cette clé.
404store_not_foundLa boutique a été supprimée.
422invalid_stylestyle manque, est vide ou dépasse 50 caractères.
422idempotency_key_reuseLa même Idempotency-Key a été utilisée avec un autre corps.