# 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[​](#deux-références "Lien direct vers 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](https://dzbuild.com/api-docs/intro)
* Arabe : [dzbuild.com/ar/api-docs](https://dzbuild.com/ar/api-docs/intro)
* Français : [dzbuild.com/fr/api-docs](https://dzbuild.com/fr/api-docs/intro)

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](https://dzbuild.dev/fr/fr/rate-limits.md), 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](https://dzbuild.dev/openapi/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[​](#envoyer-le-jeton-dinstallation "Lien direct vers 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](https://dzbuild.dev/fr/fr/oauth.md)). 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[​](#réponses "Lien direct vers 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[​](#whoami "Lien direct vers 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[​](#endpoints-fermés-aux-applications "Lien direct vers 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](https://dzbuild.dev/fr/fr/webhooks.md)). |
| `/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`.