GET /v1/analytics renvoie les chiffres que montre la page d'accueil du tableau de bord pour une période : dix KPIs, chacun avec sa valeur sur une période de comparaison et la variation, et huit séries de graphiques. Utilisez-le pour les rapports de vos clients ou un export vers un outil BI, au lieu de recalculer les chiffres depuis GET /v1/orders. L'API et le tableau de bord partagent les mêmes définitions et le même cache : pour une même période, ils affichent les mêmes chiffres. Le sens de chaque chiffre pour le marchand est expliqué sur la page Analytics de la documentation marchand.

L'API compte toujours tout le trafic : pages de la boutique et pages de destination ensemble. Le filtre de trafic du tableau de bord (pages de destination seulement, ou boutique seulement) n'a pas d'équivalent ici.

Avant de commencer

La clé a besoin de analytics:read. Les clés créées depuis le tableau de bord (Paramètres → API, /dashboard/api) l'ont depuis la v1.7. Les portées sont figées à la création de la clé : une clé plus ancienne répond 403 forbidden avec « Missing scope: analytics:read ». Créez alors une nouvelle clé depuis le tableau de bord. Une clé créée par POST /v1/keys n'obtient que les portées que détient la clé qui l'a créée.
Les clés personnelles demandent une boutique avec un plan Enterprise actif. Le jeton d'une app installée n'est pas lié à Enterprise, mais il lui faut analytics:read parmi les portées que le marchand a acceptées. Voir Introduction.
Le revenu, le profit et le panier moyen, ainsi que les valeurs revenue dans les graphiques, ne sont envoyés que si la clé appartient au compte du propriétaire de la boutique. Sinon ces champs sont absents de la réponse : ils ne valent ni 0 ni null.

Portée	Description
`analytics:read`	Lire les statistiques et les KPIs de la boutique. Incluse dans les clés marchand créées à partir de la v1.7 ; une clé plus ancienne demande une nouvelle clé.

GET /v1/analytics

Le rapport d'une période.

Auth : clé plateforme avec analytics:read.

Paramètres de requête

Param	Type	Défaut	Notes
`range`	string	`this_month`	`today`, `yesterday`, `7d`, `30d`, `this_month`, `last_month`, `this_year` ou `custom`. Toute autre valeur renvoie `400 bad_request`.
`from`	`YYYY-MM-DD`	aucun	Premier jour. Obligatoire avec `range=custom`, ignoré sinon.
`to`	`YYYY-MM-DD`	aucun	Dernier jour. Obligatoire avec `range=custom`, ignoré sinon. Jamais avant `from`, au plus 365 jours après.

Périodes

`range`	Période	Comparée à	`group_by`
`today`	Aujourd'hui	Hier	`hour`
`yesterday`	Hier	La veille	`hour`
`7d`	Aujourd'hui et les 6 jours d'avant	Les 7 jours qui précèdent	`day`
`30d`	Aujourd'hui et les 29 jours d'avant	Les 30 jours qui précèdent	`day`
`this_month`	Du 1er au dernier jour du mois en cours	Tout le mois précédent	`day`
`last_month`	Tout le mois précédent	Le mois d'avant	`day`
`this_year`	Du 1er janvier au 31 décembre de l'année en cours	Toute l'année précédente	`month`
`custom`	De `from` à `to`, les deux jours compris	Le même nombre de jours juste avant `from`	`hour`, `day` ou `month`

Pour custom, group_by vaut hour quand to est from ou le lendemain, day quand to tombe au plus 90 jours après from, et month au-delà. this_month et this_year vont jusqu'à la fin du mois ou de l'année : ils comparent donc les jours écoulés à un mois ou une année précédente entière.

Le rapport est mis en cache 120 secondes par boutique et par période, et le tableau de bord lit le même cache. Un appel peut renvoyer des chiffres vieux de deux minutes au plus, et les appels faits dans cet intervalle obtiennent les mêmes chiffres.

Requête

curl 'https://api.dzbuild.app/v1/analytics?range=7d' \
  -H "Authorization: Bearer $DZ_KEY"

Une période personnalisée :

curl 'https://api.dzbuild.app/v1/analytics?range=custom&from=2026-09-01&to=2026-09-30' \
  -H "Authorization: Bearer $DZ_KEY"

Réponse 200

La réponse pour range=7d le 6 octobre 2026, à une clé créée par le propriétaire de la boutique. Les séries temporelles et les listes sont coupées après leurs premiers éléments.

{
  "data": {
    "period": {
      "from": "2026-09-30 00:00:00",
      "to": "2026-10-06 23:59:59",
      "prev_from": "2026-09-23 00:00:00",
      "prev_to": "2026-09-29 23:59:59",
      "label": "7d",
      "group_by": "day"
    },
    "kpis": {
      "total_orders": { "value": 48, "change": 20, "previous": 40 },
      "delivered_orders": { "value": 31, "change": 7, "previous": 29 },
      "cancelled_orders": { "value": 6, "change": -25, "previous": 8 },
      "total_revenue": { "value": 186000, "change": 8, "previous": 172000 },
      "total_profit": { "value": 61500, "change": 6, "previous": 58000 },
      "avg_order_value": { "value": 4350, "change": -1, "previous": 4400 },
      "total_visitors": { "value": 1520, "change": 17, "previous": 1300 },
      "page_views": { "value": 4810, "change": 17, "previous": 4100 },
      "conversion_rate": { "value": 3.2, "change": 3, "previous": 3.1 },
      "new_customers": { "value": 41, "change": 17, "previous": 35 }
    },
    "charts": {
      "revenue_over_time": [
        { "label": "09/30", "orders": 7, "revenue": 24500 },
        { "label": "10/01", "orders": 5, "revenue": 18000 }
      ],
      "orders_by_hour": [
        { "hour": "00:00", "orders": 0, "impressions": 35 },
        { "hour": "01:00", "orders": 1, "impressions": 22 }
      ],
      "orders_by_status": {
        "pending": 5,
        "confirmed": 4,
        "processing": 2,
        "shipped": 9,
        "delivered": 20,
        "cancelled": 6,
        "returned": 2
      },
      "top_products": [
        {
          "id": 12,
          "name": "Classic watch",
          "image": "https://cdn.dzbuild.app/uploads/products/123/123_1700000000_example.webp",
          "qty_sold": 14,
          "revenue": 49000,
          "views": 380
        }
      ],
      "visitors_over_time": [
        { "label": "09/30", "page_views": 690, "unique_visitors": 215, "orders": 7 },
        { "label": "10/01", "page_views": 702, "unique_visitors": 230, "orders": 5 }
      ],
      "devices": {
        "desktop": { "count": 510, "percent": 11 },
        "mobile": { "count": 4180, "percent": 87 },
        "tablet": { "count": 120, "percent": 2 }
      },
      "traffic_sources": [
        { "source": "facebook", "count": 2900, "percent": 60 },
        { "source": "direct", "count": 1210, "percent": 25 },
        { "source": "tiktok", "count": 700, "percent": 15 }
      ],
      "top_wilayas": [
        { "wilaya": "الجزائر", "orders": 9, "revenue": 41000 },
        { "wilaya": "وهران", "orders": 6, "revenue": 27500 }
      ]
    }
  }
}

La période

Champ	Signification
`from`, `to`	Début et fin de la période, `YYYY-MM-DD HH:MM:SS`, heure d'Alger.
`prev_from`, `prev_to`	Début et fin de la période de comparaison.
`label`	Le `range` demandé.
`group_by`	Taille des intervalles de `revenue_over_time` et `visitors_over_time` : `hour`, `day` ou `month`.

KPIs

Chaque KPI porte trois nombres : value pour la période, previous pour la période de comparaison, et change, la variation en pourcentage arrondie à l'entier. Quand previous vaut 0 ou moins, change vaut 100 si value est supérieur à 0, et 0 sinon. Les montants sont arrondis à l'entier.

KPI	Ce qu'il compte
`total_orders`	Commandes créées dans la période, quel que soit leur statut.
`delivered_orders`	Commandes livrées dans la période, comptées le jour de leur livraison.
`cancelled_orders`	Commandes créées dans la période et désormais annulées.
`total_revenue`	Propriétaire uniquement. Sous-total moins remise des commandes livrées dans la période. Livraison et frais de paiement non compris.
`total_profit`	Propriétaire uniquement. `total_revenue` moins quantité × prix de revient des articles de ces commandes. Un produit sans prix de revient compte pour un coût nul.
`avg_order_value`	Propriétaire uniquement. Total moyen des commandes créées dans la période, commandes annulées et retournées exclues.
`total_visitors`	Visiteurs distincts dans la période, pages de la boutique et pages de destination ensemble.
`page_views`	Pages vues dans la période, pages de la boutique et pages de destination ensemble.
`conversion_rate`	`total_orders` ÷ `total_visitors` × 100, avec une décimale. `0` quand il n'y a eu aucun visiteur.
`new_customers`	Fiches clients créées dans la période.

Ces KPIs viennent d'ensembles de commandes différents, ils ne se recoupent donc pas : total_revenue ÷ total_orders ne donne pas avg_order_value.

Graphiques

Graphique	Contenu
`revenue_over_time`	Un élément par intervalle : `label`, les `orders` créées dans l'intervalle et, pour le propriétaire uniquement, `revenue`, la somme des totaux de celles qui sont désormais livrées. Ce n'est pas `total_revenue`, qui compte au jour de livraison et laisse de côté les frais de livraison.
`orders_by_hour`	Toujours 24 éléments, de `00:00` à `23:00` : les commandes créées et les pages vues (`impressions`) à cette heure de la journée, sur toute la période.
`orders_by_status`	Commandes créées dans la période par statut actuel : `pending`, `confirmed`, `processing`, `shipped`, `delivered`, `cancelled` et `returned`.
`top_products`	Jusqu'à 10 produits par quantité vendue dans les commandes créées dans la période, commandes annulées et retournées exclues. Chacun a `id`, `name`, `image` (URL de l'image principale ou `null`), `qty_sold`, `views` (visiteurs distincts sur le produit dans la période) et, pour le propriétaire uniquement, `revenue` (quantité × prix inscrit sur la commande).
`visitors_over_time`	Un élément par intervalle : `label`, `page_views`, `unique_visitors` et `orders`. Un visiteur qui revient un autre jour compte dans les deux intervalles, donc la somme des `unique_visitors` peut dépasser `total_visitors`.
`devices`	Pages vues par appareil : clés `desktop`, `mobile` et `tablet`, chacune avec `count` et `percent`. Un appareil sans vue n'a pas de clé, et le champ est un tableau vide `[]` quand la période n'a eu aucune visite.
`traffic_sources`	Jusqu'à 6 sources par pages vues, la plus forte en premier, chacune avec `source`, `count` et `percent`. `percent` est la part parmi les sources listées.
`top_wilayas`	Jusqu'à 10 wilayas par nombre de commandes créées dans la période, tous statuts : `wilaya` (le nom en arabe, `غير محدد` pour les commandes sans wilaya), `orders` et, pour le propriétaire uniquement, `revenue`, la somme des totaux de ces commandes quel que soit leur statut.

Les libellés suivent group_by : 00:00 à 23:00 pour hour (24 éléments ; une période custom de deux jours additionne les deux jours dans les mêmes heures), MM/DD pour day, et le mois en anglais avec l'année pour month, par exemple Sep 2026. Les jours après aujourd'hui et les mois après le mois en cours sont omis.

La plateforme enregistre source parmi direct, facebook, instagram, tiktok, google, youtube, twitter, snapchat, telegram ou other. Une visite dont le lien porte utm_source est classée selon ce tag (fb compte comme facebook, ig comme instagram, x comme twitter, tout tag hors de la liste comme other) ; une visite sans lui est classée selon le site d'où elle vient.

Erreurs

HTTP	Code	Cause
400	`bad_request`	`range` n'est pas l'une des huit valeurs (« Invalid range. Allowed: ... »), ou une période `custom` dont `from` ou `to` manque ou n'est pas au format `YYYY-MM-DD`, ou dont `to` est avant `from` ou plus de 365 jours après (« Invalid date range ... »).
401	`unauthorized`	Clé invalide ou manquante.
402	`quota_exceeded`	Le quota mensuel de requêtes de la boutique est épuisé. Voir Limites de taux.
403	`forbidden`	« Missing scope: analytics:read », ou une clé personnelle dont la boutique n'a pas de plan Enterprise actif (« API access requires an active Enterprise plan »).
429	`rate_limited`	Plafond par minute de la boutique, partagé par toutes ses clés, ou plafond propre à chaque installation pour le jeton d'application installée. Attendez la durée de `Retry-After`. Voir Limites de taux.

Limites connues

Fins de mois. Quand le numéro du jour n'existe pas dans le mois précédent, comme le 31 octobre, range=last_month renvoie le mois en cours et range=this_month est comparé au mois en cours lui-même. last_month est aussi comparé à lui-même quand le jour n'existe pas deux mois plus tôt, comme le 30 avril. Ces jours-là, demandez les dates voulues avec range=custom.