Menus de la boutique

Le menu de la boutique est le choix de liens du marchand pour la barre de navigation, le menu latéral sur téléphone et le pied de page. L'API le lit et l'écrit en un seul document : jusqu'à 12 liens en haut avec jusqu'à 10 sous-liens chacun, jusqu'à 3 groupes de 10 liens dans le pied de page, et un interrupteur pour le grand panneau des catégories. Une boutique qui n'a jamais enregistré de menu affiche les liens automatiques, et ces deux endpoints lui répondent automatic: true.

Le marchand modifie le même document dans le tableau de bord, dans Personnaliser, ligne Menu et liens. Voir Menu et liens du pied de page dans la documentation marchand.

Avant de commencer

• Les lectures demandent store:read et les écritures store:write. Les clés marchand portent les deux.
• PUT remplace le document entier. Lisez-le d'abord, changez ce qu'il faut, puis renvoyez-le avec la version lue.
• Idempotency-Key est facultatif sur PUT. Un PUT avec une clé est rejoué pendant 24 heures. Voir Idempotency.

Le document du menu

Champ	Type	Notes
v	int	Toujours 1.
mega	boolean	true active le grand panneau des catégories. Voir Le grand panneau.
top	array d'éléments	Les liens de la barre de navigation, dans l'ordre. De 1 à 12. home, products, categories, track, contact et cart y apparaissent au plus une fois chacun ; les children ne comptent pas.
footer	array de groupes	Les colonnes du pied de page, dans l'ordre. Jusqu'à 3.

Éléments

Champ	Type	Notes
type	string	Un de home, products, categories, category, page, track, contact, cart, url. Voir Types d'éléments.
label	string	Jusqu'à 40 caractères. Vide veut dire le nom de la cible elle-même, dans la langue du visiteur pour les types prévus. Obligatoire pour url.
ref	int ou null	L'id de la catégorie pour category, l'id de la page pour page, null pour les autres types.
url	string	L'adresse pour url, jusqu'à 500 octets. Vide pour les autres types.
show_subcategories	boolean	Éléments category du haut seulement : affiche aussi jusqu'à 10 sous-catégories de cette catégorie. Enregistré false partout ailleurs, children et liens du pied de page compris.
children	array d'éléments	Éléments du haut seulement : jusqu'à 10 sous-liens. Un sous-lien n'a pas de children à lui et ne peut pas être un élément categories.

Groupes

Champ	Type	Notes
key	string ou null	quick_links ou categories pour les deux groupes automatiques, null pour un groupe que vous ajoutez.
label	string	Le titre de la colonne, jusqu'à 40 caractères. Il peut être vide seulement quand key est présent : la boutique affiche alors le titre automatique dans la langue du visiteur. Un titre écrit s'affiche pareil dans toutes les langues.
links	array d'éléments	De 1 à 10 liens. Les liens du pied de page n'ont ni children ni show_subcategories.

Les libellés sont enregistrés en texte simple : les balises HTML sont retirées et les espaces aux bords supprimés. Le document entier fait au plus 16 KB.

Types d'éléments

type	Le lien ouvre
home	/, l'accueil de la boutique.
products	/products, tous les produits.
categories	Une liste déroulante des catégories principales et de leurs sous-catégories, avec une ligne tous les produits. Dans le pied de page, la partie catégories de la page d'accueil.
category	/category/{ref}. ref doit être une catégorie de cette boutique.
page	/pages/{slug} de la page ref. ref doit être une page publiée de cette boutique. Voir Pages de la boutique.
track	/track-order.
contact	La partie contact de la page d'accueil.
cart	/cart.
url	url : un chemin de la boutique comme /pages/delivery, une ancre comme #products, une adresse http:// ou https://, tel: ou mailto:.

Une url sans protocole qui ressemble à un domaine, comme instagram.com/x, est enregistrée https://instagram.com/x. javascript:, data:, //, les barres obliques inverses, les guillemets, les espaces et les chevrons sont refusés avec bad_url.

Sur la boutique, un lien vers une catégorie supprimée depuis, ou vers une page remise en brouillon, est retiré avec ses sous-liens. Une catégorie inactive n'est pas affichée.

Le grand panneau

Avec "mega": true, un élément du haut dont les sous-liens ont leurs propres sous-liens s'affiche sur ordinateur en grand panneau, avec une colonne par sous-lien. C'est le cas de l'élément categories quand une catégorie principale a des sous-catégories. Un élément category avec show_subcategories liste jusqu'à 10 sous-catégories, et avec mega jusqu'à 10 de leurs propres sous-catégories chacune, un troisième niveau. L'élément categories garde les limites du menu automatique : 10 catégories principales avec 5 sous-catégories chacune dans la barre de navigation, 12 avec 6 sur le thème Promobi. Sur téléphone, le menu latéral montre les mêmes niveaux en accordéon.

GET /v1/store/menus

Le menu de la boutique. Pour une boutique qui n'en a jamais enregistré, menus est le menu automatique et automatic vaut true.

Auth : clé plateforme avec store:read.

Requête

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

Réponse 200

version est le jeton à renvoyer avec PUT. max donne les limites et types les types d'éléments acceptés.

{
  "data": {
    "automatic": false,
    "menus": {
      "v": 1,
      "mega": false,
      "top": [
        {"type": "home", "label": "", "ref": null, "url": "", "show_subcategories": false, "children": []},
        {"type": "category", "label": "", "ref": 152, "url": "", "show_subcategories": true, "children": []},
        {"type": "page", "label": "", "ref": 7, "url": "", "show_subcategories": false, "children": []}
      ],
      "footer": [
        {"label": "Infos", "links": [{"type": "track", "label": "", "ref": null, "url": ""}, {"type": "url", "label": "Instagram", "ref": null, "url": "https://instagram.com/my-store"}]}
      ]
    },
    "version": "3f9a1c07d2e4b851",
    "max": {"top": 12, "children": 10, "groups": 3, "links": 10, "label": 40},
    "types": ["home", "products", "category", "page", "track", "contact", "cart", "url", "categories"]
  },
  "meta": {"request_id": "5d2a8e1f07c3b946", "api_version": "v1"}
}

PUT /v1/store/menus

Remplace le menu entier.

Auth : clé plateforme avec store:write. Idempotency-Key facultatif.

Corps

Champ	Type	Obligatoire	Notes
menus	object ou null	oui	Le nouveau document. null remet le menu automatique.
version	string	non	La version que vous avez lue. Quand elle ne correspond plus, l'appel répond 409 write_conflict et ne change rien. Sans elle, l'appel écrase ce qui est enregistré.

Requête

curl -X PUT 'https://api.dzbuild.app/v1/store/menus' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: menus-sizes-1" \
  -d '{"version": "3f9a1c07d2e4b851", "menus": {"v": 1, "mega": false, "top": [{"type": "home", "label": "", "ref": null, "url": "", "show_subcategories": false, "children": []}, {"type": "page", "label": "Guide des tailles", "ref": 9, "url": "", "show_subcategories": false, "children": []}], "footer": []}}'

Réponse 200

menus est le document tel qu'enregistré, version le nouveau jeton et change_id l'id dans le journal des changements. Un corps qui ne change rien répond change_id: null.

{
  "data": {
    "menus": {
      "v": 1,
      "mega": false,
      "top": [
        {"type": "home", "label": "", "ref": null, "url": "", "show_subcategories": false, "children": []},
        {"type": "page", "label": "Guide des tailles", "ref": 9, "url": "", "show_subcategories": false, "children": []}
      ],
      "footer": []
    },
    "version": "b70e4d2a9c15f383",
    "change_id": 90420,
    "automatic": false
  },
  "meta": {"request_id": "a81c3f5e92d07b64", "api_version": "v1"}
}

"menus": null répond automatic: true avec le menu automatique dans menus.

Annuler

PUT répond avec un change_id. POST /v1/changes/{change_id}/undo remet le menu tel qu'il était avant cet appel, menu automatique compris. L'annulation demande store:write et un Idempotency-Key.

• Quand le menu a encore changé depuis cet appel, l'annulation répond 409 menus_changed et ne change rien. Annulez d'abord le changement plus récent.
• Un changement annulé une deuxième fois répond 409 already_undone.
• Les menus que le marchand enregistre dans Personnaliser ne sont pas enregistrés dans le journal, donc on ne peut pas les annuler par l'API.
• GET /v1/changes?entity=store.menus liste les changements du menu, du plus récent au plus ancien, avec store:read. entity_id vaut menus.
• Le jeton d'une application installée ne peut ni lire ni annuler les changements : GET /v1/changes et l'annulation répondent 403 forbidden. Les réponses d'écriture portent quand même le change_id.

curl -X POST 'https://api.dzbuild.app/v1/changes/90420/undo' \
  -H "Authorization: Bearer $DZ_KEY" \
  -H "Idempotency-Key: undo-90420"

Erreurs

HTTP	Code	Cause
400	bad_request	Le corps n'est pas un objet JSON, menus manque ou n'est ni un objet ni null, ou version n'est pas un texte.
401	unauthorized	Clé mauvaise ou absente.
402	quota_exceeded	Le quota mensuel de requêtes de la boutique est épuisé. Voir Limites de taux.
403	forbidden	Missing scope: store:read ou Missing scope: store:write, ou API access requires an active Enterprise plan pour une clé marchand dont la boutique n'a pas de plan Enterprise actif.
404	not_found	La boutique n'existe pas.
409	write_conflict	La version envoyée ne correspond plus : l'erreur porte les menus actuels (null tant que la boutique affiche les liens automatiques) et la version actuelle, pour fusionner et réessayer. Le même code sans eux veut dire qu'une autre écriture est arrivée au même moment : relisez, puis réessayez.
409	menus_changed	Annulation seulement : le menu a changé depuis le changement que vous annulez.
409	already_undone	Annulation seulement : le changement a déjà été annulé.
413	payload_too_large	Le corps dépasse 1 MB.
422	invalid_menus	Une valeur a été refusée. fields donne {path, code} pour elle. Voir les codes ci-dessous.
422	idempotency_key_reuse	Le même Idempotency-Key a servi avec un autre corps.
429	rate_limited	Trop de requêtes. Attendez Retry-After.
500	server_error	La requête a échoué. Réessayez avec le même Idempotency-Key.

path commence par menus. et montre la valeur refusée, comme menus.top.0.url ou menus.footer.1.links.10 ; il vaut menus seul pour too_large. Le code est un de ceux-ci.

code	Cause
bad_url	Une url vide, refusée ou trop longue.
invalid	Une erreur de forme : une liste là où un objet est attendu ou l'inverse, comme un top qui n'est pas un array.
too_many	Plus de 12 éléments en haut, de 10 sous-liens, de 3 groupes ou de 10 liens dans un groupe. path nomme le premier élément au-delà de la limite.
top_required	top est vide. Pour abandonner un menu personnalisé, envoyez "menus": null.
unknown_type	type n'est pas un des neuf types.
unknown_key	Une key de groupe du pied de page autre que quick_links, categories ou null.
unknown_category	ref n'est pas une catégorie de cette boutique.
unknown_page	ref n'est pas une page publiée de cette boutique.
label_required	Un élément url sans libellé, ou un groupe du pied de page sans libellé et sans key.
label_too_long	Un libellé de plus de 40 caractères.
links_required	Un groupe du pied de page sans lien.
duplicate_type	Un deuxième élément home, products, categories, track, contact ou cart dans top.
nested_too_deep	Des children dans un sous-lien ou un lien du pied de page, ou un élément categories comme sous-lien.
too_large	Le document dépasse 16 KB.

{
  "error": {
    "code": "invalid_menus",
    "message": "Invalid menu at menus.top.0.url (bad_url); the caps and types are in GET /v1/store/menus.",
    "fields": [{"path": "menus.top.0.url", "code": "bad_url"}]
  },
  "meta": {"request_id": "c27e90b4f13a5d68", "api_version": "v1"}
}

Limites

• Menu du haut : 12 éléments, chacun avec jusqu'à 10 sous-liens.
• Pied de page : 3 groupes de 10 liens au plus.
• Libellé : 40 caractères. Url : 500 octets. Document : 16 KB.
• Les limites sont les mêmes sur tous les plans.

Outils MCP

Le serveur MCP, version 1.9.0, donne à un assistant IA deux outils de menu avec les mêmes règles : menus_get renvoie le document entier avec sa version et les limites, menus_set le réécrit avec cette version, et change_undo annule une écriture.