Référence complète de tous les points de terminaison de l'API REST Zenovay. Pour bien démarrer, consultez Aperçu de l'API.
Une spécification OpenAPI lisible par machine est publiée à https://api.zenovay.com/api/external/v1/openapi.json si vous préférez générer un client.
API externe
L'API externe utilise l'authentification par clé API et est une fonctionnalité payante - elle est disponible pour les plans Pro, Scale et Enterprise. Les clés du niveau gratuit sont rejetées avec un 403 API_PAID_PLAN_REQUIRED.
URL de base
https://api.zenovay.com/api/external/v1
Authentification
Générez une clé sous Compte → Sécurité et accès (ou ouvrez app.zenovay.com/api-keys directement). Les clés commencent par zv_. Incluez votre clé dans chaque requête en utilisant l'en-tête :
X-API-Key: zv_YOUR_API_KEY
# ou
Authorization: Bearer zv_YOUR_API_KEY
Enveloppe de réponse
Chaque réponse de l'API externe est encapsulée dans une enveloppe standard. Les réponses réussies ressemblent à ceci :
{
"success": true,
"data": { },
"timestamp": "2026-06-13T00:00:00.000Z"
}
Les exemples ci-dessous montrent le contenu de l'objet data. Les erreurs utilisent une structure différente - voir Réponses d'erreur.
Points de terminaison d'analytique
Obtenir l'aperçu d'analytique
GET /analytics/{websiteId}
Retourne un résumé analytique agrégé pour un site Web.
Paramètres de requête :
| Paramètre | Type | Description |
|---|---|---|
| range | string | Plage de temps : 24h, 7d, 30d, 90d, 1y (par défaut : 7d) |
data:
{
"website": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website"
},
"time_range": "7d",
"date_range": {
"start": "2026-06-06",
"end": "2026-06-13"
},
"summary": {
"total_visitors": 1247,
"total_page_views": 3891,
"unique_visitors": 982
},
"daily_stats": []
}
daily_stats contient les lignes analytics_daily brutes pour la plage. Pour une API de requête de style Plausible (visitors, pageviews, bounce_rate, visit_duration avec filtres et ventilations), consultez l'API Stats.
Obtenir les visiteurs
GET /analytics/{websiteId}/visitors
Retourne les enregistrements de visiteurs individuels pour un site Web.
Paramètres de requête :
| Paramètre | Type | Description |
|---|---|---|
| range | string | Plage de temps (par défaut : 7d) |
| limit | integer | Résultats par page (par défaut : 100, max : 1000) |
| offset | integer | Nombre d'enregistrements à ignorer (par défaut : 0) |
Obtenir les pages
GET /analytics/{websiteId}/pages
Retourne les meilleures pages d'un site Web. Accepte range et limit (par défaut 20, max 100).
Obtenir les pays
GET /analytics/{websiteId}/countries
Retourne une ventilation géographique des visiteurs par pays. Accepte range et limit (par défaut 20, max 100).
Obtenir la technologie
GET /analytics/{websiteId}/technology
Retourne la ventilation technologique - devices, browsers et operating_systems, chacun avec des compteurs et des pourcentages. Accepte range.
Points de terminaison des sites Web
Lister les sites Web
GET /websites
Retourne tous les sites Web accessibles avec votre clé API.
data:
{
"websites": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"domain": "example.com",
"name": "My Website",
"tracking_code": "abc123def456",
"is_active": true,
"created_at": "2026-01-01T00:00:00Z"
}
],
"total": 1
}
Obtenir les détails du site Web
GET /websites/{websiteId}
Retourne les détails d'un site Web spécifique sous data.website.
Points de terminaison de la carte thermique
Obtenir les pages de la carte thermique
GET /heatmaps/{websiteId}/pages
Retourne les pages qui ont collecté des données de carte thermique. Accepte limit (par défaut 20, max 100).
Points de terminaison de rejeu de session
Obtenir les sessions de rejeu
GET /replays/{websiteId}/sessions
Retourne les enregistrements de rejeu de session pour un site Web. Accepte limit (par défaut 50, max 200) et offset.
Points de terminaison de suivi des erreurs
Obtenir les groupes d'erreurs
GET /errors/{websiteId}/groups
Retourne les données d'erreurs regroupées pour un site Web. Accepte limit (par défaut 50, max 200) et un filtre status optionnel (open, resolved, ignored).
Endpoints IA et avancés (Pro+)
Ces endpoints nécessitent un plan Pro ou supérieur et sont limités par le plan du team propriétaire du site.
| Point de terminaison | Description |
|---|---|
GET /insights/{websiteId} | Insights générés par l'IA pour le site |
GET /anomalies/{websiteId} | Anomalies de trafic/comportement détectées |
GET /retention/{websiteId} | Analyse de cohorte de rétention (granularity, periods) |
GET /revenue/{websiteId}/ltv | Analyse de cohorte de valeur vie client |
Requête en langage naturel (Scale+)
POST /query/{websiteId}
Exécute une requête analytique en langage naturel. Nécessite un plan Scale ou supérieur. Envoyez un corps JSON avec une chaîne query (max 500 caractères); chaque appel consomme 3 crédits de requête.
API Stats
Points de terminaison de requête en lecture seule compatibles Plausible (Pro+). Ceux-ci vous permettent d'interroger des métriques, des séries temporelles et des ventilations avec des filtres. Consultez le guide dédié API Stats pour la référence de paramètre complète.
| Point de terminaison | Description |
|---|---|
GET /stats/aggregate | Métriques uniques sur une période |
GET /stats/timeseries | Séries à temps discrétisé (interval=day/hour/month) |
GET /stats/breakdown | Métriques regroupées (pages principales, pays principaux, etc.) |
Tous les trois prennent site_id plus period, metrics et filters optionnel. Les métriques supportées sont visitors, pageviews, bounce_rate, visit_duration et events.
Point de terminaison d'utilisation
Vérifier l'utilisation de l'API
GET /usage
Retourne votre utilisation API actuelle et vos limites.
data:
{
"api_key": {
"id": "key_123",
"name": "Personal API key",
"permission": "full_access",
"website_id": null,
"auth_kind": "user"
},
"usage": {
"monthly_requests": 4521,
"monthly_limit": 10000,
"monthly_remaining": 5479,
"monthly_reset_at": "2026-07-01T00:00:00.000Z",
"total_requests": 18204,
"scope": "user"
},
"rate_limits": {
"requests_per_minute": 30
},
"subscription": {
"tier": "Pro"
}
}
Points de terminaison de suivi (publics)
Ces points de terminaison ne nécessitent pas d'authentification par clé API. Ils utilisent le code de suivi du site Web et sont ouverts à tous les plans (limités au taux uniquement).
Suivre une vue de page ou un événement
POST /e/{trackingCode}
Envoie une vue de page ou un événement personnalisé. C'est ce que le script de suivi appelle automatiquement. Pour le suivi côté serveur, envoyez le même format de charge utile avec les en-têtes appropriés. Les événements de cœur battement peuvent également être envoyés comme type d'événement heartbeat à ce point de terminaison.
Nombre de visiteurs en direct
GET /e/live/{trackingCode}
Retourne le nombre actuel de visiteurs en direct sur le site, avec une courte liste de sessions actives.
Cœur battement
POST /e/heartbeat/{trackingCode}
Envoie un cœur battement pour maintenir une session de visiteur active. Nécessite un session_id dans le corps JSON.
Réponses d'erreur
Format d'erreur
Les erreurs sont retournées avec success: false et un objet error :
{
"success": false,
"error": {
"message": "site_id parameter is required",
"code": "MISSING_SITE_ID",
"timestamp": "2026-06-13T00:00:00.000Z"
}
}
Codes d'erreur courants
| Code | Statut HTTP | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Clé API invalide ou manquante |
| API_PAID_PLAN_REQUIRED | 403 | L'accès à l'API nécessite un plan Pro ou supérieur |
| FORBIDDEN | 403 | La clé n'a pas accès au site demandé, ou le niveau de plan est trop faible |
| NOT_FOUND | 404 | Ressource non trouvée |
| VALIDATION_ERROR | 400 | Paramètre invalide ou manquant |
| MISSING_SITE_ID | 400 | Le paramètre de requête site_id est requis (API Stats) |
| RATE_LIMIT_EXCEEDED | 429 | Limite de débit par minute dépassée |
| MONTHLY_LIMIT_EXCEEDED | 429 | Limite mensuelle de demandes API atteinte |
| INTERNAL_ERROR | 500 | Erreur interne |
Limites de débit
Les limites de débit de l'API externe sont par clé API. (La ligne Free est affichée par souci de complétude, mais les clés du niveau gratuit ne peuvent pas appeler l'API externe - c'est une fonctionnalité payante.)
| Plan | Demandes/Minute | Limite mensuelle |
|---|---|---|
| Pro | 30 | 10 000 |
| Scale | 60 | 100 000 |
| Enterprise | 120 | 1 000 000 |
Les réponses incluent les en-têtes d'utilisation et de limite de débit :
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z
Lorsqu'une limite par minute est atteinte, la réponse inclut également un en-tête Retry-After (secondes à attendre).