Référence de l'API

Votre application appelle la même API REST que les marchands, à l'adresse https://api.dzbuild.app/v1. Deux références la décrivent, et cette page couvre ce qui change quand vous l'appelez avec un jeton d'installation.

Deux références

La documentation de l'API sur dzbuild.com détaille les principales ressources avec leurs paramètres, leurs réponses et des exemples, en trois langues :

• Anglais : dzbuild.com/api-docs
• Arabe : dzbuild.com/ar/api-docs
• Français : dzbuild.com/fr/api-docs

Ces pages sont écrites pour les clés API des marchands. Avec un jeton d'installation, les règles de cette page priment là où elles diffèrent : tous les plans peuvent utiliser votre application, les limites sont dans Limites de requêtes, et certains endpoints sont fermés aux apps.

La description OpenAPI pour les applications est un fichier JSON au format OpenAPI 3.1. Elle liste les 92 opérations qu'un jeton d'installation peut appeler, avec leurs scopes, leurs paramètres et la forme de leurs réponses. Importez-la dans Postman ou Insomnia, ou générez-en des types.

Télécharger dzbuild-apps-v1.json

curl -sO https://dzbuild.dev/openapi/dzbuild-apps-v1.json

Le fichier déclare https://api.dzbuild.app comme serveur. Son schéma de sécurité dzOAuth liste chaque scope avec une description en anglais.

Envoyer le jeton d'installation

L'échange de jeton vous donne un jeton d'accès par boutique approuvée par le marchand (voir OAuth). Chaque jeton commence par dzpk_live_. Envoyez-le dans l'en-tête Authorization avec le schéma Bearer :

curl https://api.dzbuild.app/v1/whoami \
  -H "Authorization: Bearer dzpk_live_xxxxxxxx"

Le jeton détermine la boutique. Les requêtes n'ont pas de paramètre de boutique : pour travailler sur une autre boutique du même marchand, utilisez le jeton de cette boutique dans la liste stores de la réponse d'échange. Gardez les jetons sur votre serveur. Ils n'expirent pas d'eux-mêmes. Un jeton cesse de fonctionner quand le marchand désinstalle votre application, ou quand il la réinstalle sur la même boutique, ce qui remplace le jeton.

Statut	Message	Cause
401	Missing Authorization header	Pas d'en-tête Authorization.
401	Unsupported Authorization scheme	L'en-tête ne commence pas par Bearer.
401	Invalid or revoked API key	Le jeton est faux, ou il a été révoqué par une désinstallation.

Chaque jeton d'installation est aussi contrôlé par rapport à l'état de votre application et de la boutique. Un appel refusé répond 403 avec l'un de ces codes :

Code	Signification
app_uninstalled	L'application n'est plus installée sur cette boutique.
app_suspended	DZBuild a suspendu l'app.
app_not_approved	L'application est en mode test et ne tourne que sur les boutiques de son développeur.
app_plan_required	Le plan de la boutique est inférieur au plan minimum fixé pour l'app.

Réponses

Une réponse réussie place le résultat dans data. Une erreur place un code et un message dans error. Les deux portent meta.request_id : citez-le quand vous contactez DZBuild au sujet d'un appel.

{
  "error": { "code": "forbidden", "message": "Missing scope: orders:write" },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

Les endpoints de liste répondent ainsi :

{
  "data": { "items": [...], "next_cursor": "...", "has_more": true },
  "meta": { "request_id": "...", "api_version": "v1" }
}

Renvoyez next_cursor dans le paramètre cursor pour obtenir la page suivante, et arrêtez-vous quand has_more vaut false. GET /v1/orders accepte aussi since (les commandes créées à partir de cet instant), status et customer_phone.

whoami

GET /v1/whoami n'exige aucun scope. Il indique à quelle boutique appartient un jeton et ce qu'il peut faire. Pour un jeton d'installation, il ajoute un objet app :

{
  "data": {
    "key_id": "dzpk_live_3c9e1a7f5b2d80",
    "store_id": 1234,
    "type": "platform",
    "rate_limit_tier": "enterprise",
    "pilot": true,
    "scopes": ["orders:read", "whatsapp:read", "whatsapp:send"],
    "app": {
      "app_id": 12,
      "client_id": "dzapp_4e1b9c07d2a86f35e0b1",
      "install_id": 57
    }
  },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

Champ	Signification
store_id	La boutique sur laquelle ce jeton agit.
scopes	Les scopes accordés par le marchand.
rate_limit_tier	Toujours enterprise pour les jetons d'installation, quel que soit le plan de la boutique.
app.app_id	L'identifiant de votre app.
app.client_id	L'identifiant client OAuth de votre app.
app.install_id	L'installation sur cette boutique. Les payloads de webhook comme app.uninstalled utilisent le même identifiant.

Endpoints fermés aux applications

Ces endpoints répondent 403 à un jeton d'installation, quels que soient ses scopes :

Endpoints	Réponse	Pourquoi
/v1/keys et /v1/keys/{key_id}	Apps cannot use this endpoint	Les clés API appartiennent au marchand.
/v1/webhooks et tous ses sous-chemins	Apps cannot use this endpoint	Le webhook de votre application se règle une seule fois dans la console développeur pour toutes les boutiques (voir Webhooks).
/v1/changes et tous ses sous-chemins, annulation comprise	Apps cannot use this endpoint	Le journal des modifications et l'annulation restent au marchand.

POST /v1/landing-pages/generate exige le scope ai:generate, que les applications ne peuvent pas demander car il consomme les crédits IA du marchand. Il répond 403 avec Missing scope: ai:generate.