Scopes

Un scope est une permission sur un type de données de la boutique. Vous enregistrez les scopes dont votre application a besoin dans la console développeur, et la demande d'autorisation peut les demander tous ou une partie. Le jeton d'accès porte exactement les scopes que le marchand a approuvés.

Scopes qu'une application peut demander

Les descriptions de ce tableau sont celles que le marchand lit à l'écran de consentement.

Scope	Description
analytics:read	Consulter les statistiques de votre boutique
customers:read	Consulter vos clients et leurs coordonnées (nom, téléphone, adresse)
delivery:send	Remettre vos commandes au transporteur
landing_pages:read	Consulter vos pages de destination
landing_pages:write	Consulter, créer, modifier et publier des pages de destination
orders:read	Consulter les commandes (lecture seule, aucune création ni modification)
orders:write	Créer et modifier des commandes
pixels:read	Consulter vos pixels de suivi publicitaire
pixels:write	Consulter, ajouter et modifier vos pixels de suivi publicitaire
products:read	Consulter vos produits
products:write	Consulter, créer, modifier et supprimer des produits
promos:read	Consulter vos codes promo
promos:write	Consulter, créer et modifier des codes promo (cela change les prix payés par vos clients)
shipping:read	Consulter vos tarifs et réglages de livraison
shipping:write	Consulter et modifier vos tarifs de livraison, et connecter ou déconnecter vos transporteurs
store:read	Consulter les informations et les réglages de votre boutique
store:write	Consulter et modifier les réglages, le design et le thème de votre boutique
whatsapp:read	Consulter les modèles de messages WhatsApp, votre solde et l'historique des messages envoyés
whatsapp:send	Envoyer des messages WhatsApp à vos acheteurs au sujet de leurs commandes (chaque message est débité de votre solde WhatsApp)

Règles des scopes d'application

• Seuls les scopes du tableau ci-dessus peuvent être enregistrés sur une application ou lui être accordés. Tout autre scope dans la demande d'autorisation échoue avec invalid_scope.
• Les applications ne peuvent pas demander ai:generate. Ce scope lance des générations IA qui consomment les crédits IA du marchand.
• Les applications ne peuvent pas demander usage:read, webhooks:read ni webhooks:write. Votre application reçoit ses webhooks par l'URL de webhook de son enregistrement, pas par /v1/webhooks.
• Un paramètre scope absent ou vide accorde tous les scopes enregistrés sur l'application.
• Demandez le moins de scopes possible. Le marchand voit une ligne par ressource sur l'écran de consentement avant d'approuver.

Endpoints ouverts par chaque scope

Cette liste est celle que déclare la description OpenAPI. Quelques écritures demandent aussi le scope de lecture : POST /v1/orders, PATCH /v1/orders/{id} et POST /v1/orders/{id}/cancel demandent orders:read et orders:write, POST /v1/products et PATCH /v1/products/{id} demandent products:read et products:write, et POST /v1/landing-pages, PATCH /v1/landing-pages/{id} et POST /v1/landing-pages/{id}/publish demandent landing_pages:read et landing_pages:write. Ces écritures répondent avec l'enregistrement mis à jour, et sa lecture demande le scope de lecture. Sans ce scope, l'écriture s'exécute quand même, puis l'appel répond 403 avec un message comme Missing scope: orders:read, et une nouvelle tentative avec le même Idempotency-Key renvoie ce 403 enregistré. Enregistrez et demandez les deux scopes.

Scope	Endpoints
analytics:read	GET /v1/analytics
customers:read	GET /v1/customers, GET /v1/customers/{id}, GET /v1/customers/{id}/orders
delivery:send	POST /v1/orders/{id}/send-to-delivery
landing_pages:read	GET /v1/landing-page-section-types, GET /v1/landing-pages, GET /v1/landing-pages/{id}, GET /v1/landing-pages/{id}/check, GET /v1/landing-pages/{id}/sections, GET /v1/landing-pages/generate/{id}
landing_pages:write	POST /v1/landing-pages, PATCH /v1/landing-pages/{id}, DELETE /v1/landing-pages/{id}, POST /v1/landing-pages/{id}/publish, POST /v1/landing-pages/{id}/sections, POST /v1/landing-pages/{id}/sections/batch, POST /v1/landing-pages/{id}/sections/reorder, PATCH /v1/landing-pages/{id}/sections/{section_id}, DELETE /v1/landing-pages/{id}/sections/{section_id}
orders:read	GET /v1/orders, GET /v1/orders/{id}
orders:write	POST /v1/orders, PATCH /v1/orders/{id}, POST /v1/orders/{id}/cancel
pixels:read	GET /v1/pixels
pixels:write	POST /v1/pixels, PATCH /v1/pixels/{id}, DELETE /v1/pixels/{id}
products:read	GET /v1/categories, GET /v1/categories/{id}, GET /v1/products, GET /v1/products/{id}, GET /v1/products/{id}/addons, GET /v1/products/{id}/offers, GET /v1/products/{id}/quantity-rules, GET /v1/products/{id}/stock
products:write	POST /v1/categories, POST /v1/categories/reorder, PATCH /v1/categories/{id}, DELETE /v1/categories/{id}, POST /v1/products, PATCH /v1/products/{id}, DELETE /v1/products/{id}, POST /v1/products/{id}/addons, POST /v1/products/{id}/images, PATCH /v1/products/{id}/images/{image_id}, DELETE /v1/products/{id}/images/{image_id}, POST /v1/products/{id}/offers, POST /v1/products/{id}/quantity-rules, POST /v1/products/{id}/stock, PUT /v1/products/{id}/variants
promos:read	GET /v1/promo-codes
promos:write	POST /v1/promo-codes, PATCH /v1/promo-codes/{id}, DELETE /v1/promo-codes/{id}
shipping:read	GET /v1/shipping/coverage, GET /v1/shipping/providers, GET /v1/shipping/rates, GET /v1/shipping/settings, GET /v1/wilayas, GET /v1/wilayas/{id}/communes
shipping:write	POST /v1/shipping/providers, POST /v1/shipping/providers/default, POST /v1/shipping/providers/test, DELETE /v1/shipping/providers/{provider}, POST /v1/shipping/rates, POST /v1/shipping/rates/sync, PATCH /v1/shipping/settings
store:read	GET /v1/store, GET /v1/store/design, GET /v1/store/design/fields, GET /v1/store/home-sections, GET /v1/store/home-layout, GET /v1/themes
store:write	PATCH /v1/store, PATCH /v1/store/design, PATCH /v1/store/home-sections, PUT /v1/store/home-layout, POST /v1/store/home-layout/sections, PATCH /v1/store/home-layout/sections/{id}, DELETE /v1/store/home-layout/sections/{id}, POST /v1/store/home-layout/reorder, POST /v1/store/theme, POST /v1/store/fast-checkout-theme, POST /v1/store/variant-style
whatsapp:read	GET /v1/whatsapp/templates, GET /v1/whatsapp/balance, GET /v1/whatsapp/messages
whatsapp:send	POST /v1/orders/{id}/whatsapp

GET /v1/whoami ne demande aucun scope. GET /v1/ping ne demande aucun jeton. Un appel sans le scope nécessaire répond 403 avec le code forbidden et un message qui nomme le scope, par exemple Missing scope: orders:read.

Endpoints fermés aux jetons d'application

Ces endpoints répondent 403 avec le message Apps cannot use this endpoint, quels que soient les scopes du jeton : /v1/keys, /v1/webhooks, /v1/changes et POST /v1/changes/{id}/undo. Le marchand garde la gestion des clés, les abonnements webhook et l'historique d'annulation. Les endpoints de connexion des assistants, GET /v1/connection et POST /v1/connection/active-store, répondent 403 sans store:read ou store:write, et 404 sinon, car un jeton d'application n'a pas été créé par une connexion d'assistant.

Scopes et webhooks

Chaque événement de commande (order.created, order.confirmed, order.processing, order.shipped, order.delivered, order.cancelled, order.returned) contient le nom, le téléphone et l'adresse de l'acheteur. Votre installation ne reçoit les événements de commande que si le marchand a accordé orders:read. L'événement app.uninstalled est envoyé quels que soient les scopes. Voir webhooks.

Ce que voit le marchand

L'écran de consentement regroupe les scopes par ressource et affiche une ligne par ressource : la ligne d'écriture quand l'application demande l'écriture, la ligne de lecture sinon. La ligne est rédigée dans la langue du marchand. Modifier les scopes enregistrés sur l'application ne change pas les jetons déjà émis ; une boutique reçoit les nouveaux scopes quand le marchand installe de nouveau l'application.