# API DZBuild Créez vos applications DZBuild Créez des applications que les marchands peuvent installer sur leurs boutiques DZBuild. Consultez le [portail développeur dzbuild.dev](https://dzbuild.dev/fr/) pour les modèles officiels et les guides, ou [créez une application](https://dzbuild.dev/fr/apps/new). Le plan Entreprise mentionné ci-dessous concerne les clés API personnelles des marchands. Les applications installées suivent des [règles d'accès distinctes](https://dzbuild.dev/fr/concepts), dont le plan minimum et les permissions demandés par l'application. L'API DZBuild vous permet de gérer votre boutique de manière programmatique : produits, commandes, clients, landing pages, ainsi qu'un **traqueur d'inscriptions** à fort volume pour les marchands qui intègrent DZBuild à leurs propres plateformes. **URL de base :** `https://api.dzbuild.app/v1` — la seule URL de base publique prise en charge. **Versionnage :** stable `v1`. Tout changement majeur nécessite un nouveau préfixe de chemin. **Format :** JSON entrée et sortie, UTF-8. **Authentification :** voir [Authentification](https://dzbuild.com/fr/fr/api-docs/authentication.md). **Clés API personnelles :** elles nécessitent une boutique avec un plan Entreprise actif. Cette condition ne concerne pas les jetons d'installation des applications, qui suivent les règles d'accès indiquées ci-dessus. **Statut :** Pilote. Le propriétaire d'une boutique avec un plan Enterprise actif crée ses clés personnelles depuis le tableau de bord, dans **Paramètres → API** (`/dashboard/api`). Une nouvelle clé est inscrite au pilote automatiquement et fonctionne tout de suite : il n'y a rien à demander au support. Pointez votre intégration vers `api.dzbuild.app`, rien d'autre `https://dzbuild.com/api/v1` est un alias interne, pas une cible d'intégration. Sur cet hôte : `/v1/signups` et `/v1/events` n'existent pas (`404`), les appels par clé publique (`DZ-Public`) sont rejetés avec `401`. Le rejeu idempotent et la limite de débit par boutique s'appliquent sur les deux hôtes. ## Démarrage rapide[​](#démarrage-rapide "Lien direct vers Démarrage rapide") ``` curl https://api.dzbuild.app/v1/ping ``` Réponse : ``` { "data": { "pong": true, "time": "2026-04-30T20:15:59.836Z", "edge": true }, "meta": { "request_id": "...", "api_version": "v1", "edge": true } } ``` Requête authentifiée : ``` curl https://api.dzbuild.app/v1/whoami \ -H "Authorization: Bearer ." ``` Réponse : ``` { "data": { "key_id": "dzpk_live_xxxxxxxxxxxxxx", "store_id": 10, "type": "platform", "rate_limit_tier": "enterprise", "pilot": true, "scopes": ["store:read", "store:write", "products:read", "products:write", "orders:read", "orders:write", "customers:read", "landing_pages:read", "landing_pages:write", "promos:read", "promos:write", "pixels:read", "pixels:write", "shipping:read", "shipping:write", "webhooks:read", "webhooks:write", "usage:read", "analytics:read", "whatsapp:read", "whatsapp:send"] }, "meta": { "request_id": "...", "api_version": "v1" } } ``` `scopes` liste ce que cette clé peut appeler : un endpoint qui demande un scope absent de la liste répond `403` avec `Missing scope:` suivi du nom du scope. Appelé avec le jeton d'une application installée, `whoami` renvoie aussi `app`, avec ses `app_id`, `client_id` et `install_id`. ## Enveloppe de réponse[​](#enveloppe-de-réponse "Lien direct vers Enveloppe de réponse") Toutes les réponses suivent la même structure : **Succès** ``` { "data": ..., "meta": { "request_id": "...", "api_version": "v1" } } ``` **Erreur** ``` { "error": { "code": "rate_limited", "message": "...", "retry_after": 12 }, "meta": { "request_id": "...", "api_version": "v1" } } ``` ## En-têtes de réponse[​](#en-têtes-de-réponse "Lien direct vers En-têtes de réponse") | En-tête | Quand | Signification | | -------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `X-Request-Id` | Sur chaque réponse | Même valeur que `meta.request_id`, sauf sur un rejeu idempotent : son corps est celui qui a été stocké et garde le `meta.request_id` du premier appel. Envoyez votre propre `X-Request-Id` et nous vous le renvoyons tel quel, pour que vos journaux et les nôtres concordent. | | `X-Api-Version` | Sur la plupart des réponses | Toujours `v1`. | | `X-Cache` | Sur `GET /v1/products`, `GET /v1/landing-pages`, `GET /v1/store` et ses sous-chemins | Toujours `MISS` : ces lectures sont servies à neuf. | | `Idempotency-Replay` | Sur les écritures rejouées | `1` signifie qu'il s'agit de la réponse stockée d'un appel antérieur portant la même `Idempotency-Key` — aucun nouvel effet de bord n'a eu lieu. Voir [Idempotence](https://dzbuild.com/fr/fr/api-docs/idempotency.md). | ## Bon à savoir[​](#bon-à-savoir "Lien direct vers Bon à savoir") * Votre clé est vérifiée à chaque requête — Bearer tokens comme signatures HMAC de clé publique. * La limite par minute s'applique **par boutique** — toutes les clés d'une boutique partagent un seul budget — sur une fenêtre fixe de 60 secondes (le compteur est remis à zéro à chaque minute d'horloge). L'application est approximative lors de rafales : gérez les `429` de façon défensive plutôt que de caler votre cadence exactement sur la limite. Elle s'applique aux appels API uniquement — la vitrine, le tunnel de commande et le tableau de bord d'un marchand ne la consomment jamais. Voir [Limites de taux](https://dzbuild.com/fr/fr/api-docs/rate-limits.md). * Chaque `GET` est servi à neuf depuis la plateforme : il n'y a pas de cache de lecture en bordure sur `api.dzbuild.app`, donc `GET /v1/products`, `GET /v1/landing-pages`, `GET /v1/store` et chaque `GET` en dessous renvoient les valeurs courantes à chaque appel. Mettez en cache de votre côté quand vous lisez à grande échelle. * Les écritures à fort volume (`/v1/signups`, `/v1/events`) sont acceptées de façon asynchrone et retournent `202 Accepted` immédiatement — votre appel n'attend pas la fin du traitement.