# 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[​](#scopes-quune-application-peut-demander "Lien direct vers 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[​](#règles-des-scopes-dapplication "Lien direct vers 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[​](#endpoints-ouverts-par-chaque-scope "Lien direct vers 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[​](#endpoints-fermés-aux-jetons-dapplication "Lien direct vers 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[​](#scopes-et-webhooks "Lien direct vers 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](https://dzbuild.dev/fr/fr/webhooks.md). ## Ce que voit le marchand[​](#ce-que-voit-le-marchand "Lien direct vers 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.