Aperçu de l'API

Pro Plan

L'API Zenovay vous offre un accès programmatique à vos données analytiques. Créez des intégrations personnalisées, automatisez vos flux de travail et étendez les capacités de Zenovay.

Ce que vous pouvez faire

API externe (authentification par clé API)

Capacité	Endpoint
Aperçu analytique	GET /api/external/v1/analytics/:websiteId
Données des visiteurs	GET /api/external/v1/analytics/:websiteId/visitors
Analytique des pages	GET /api/external/v1/analytics/:websiteId/pages
Données par pays	GET /api/external/v1/analytics/:websiteId/countries
Répartition technologique	GET /api/external/v1/analytics/:websiteId/technology
Lister les sites web	GET /api/external/v1/websites
Détails du site web	GET /api/external/v1/websites/:websiteId
Utilisation de l'API	GET /api/external/v1/usage
Pages de heatmap	GET /api/external/v1/heatmaps/:websiteId/pages
Enregistrements de sessions	GET /api/external/v1/replays/:websiteId/sessions
Groupes d'erreurs	GET /api/external/v1/errors/:websiteId/groups

Suivi (Public)

Ces endpoints sont utilisés par le script de suivi — aucune clé API requise.

Capacité	Endpoint
Enregistrer pageview/événement	POST /e/:trackingCode
Nombre de visiteurs en direct	GET /e/live/:trackingCode
Heartbeat	POST /e/heartbeat/:trackingCode

Accès à l'API par plan

L'API REST est une fonctionnalité payante. Les espaces de travail gratuits ne peuvent pas créer ou utiliser de clés API — les endpoints de suivi non authentifiés ci-dessus restent disponibles sur tous les plans.

Plan	Accès API	Requêtes/Minute	Limite mensuelle
Free	Non disponible	—	—
Pro	Complet	30	10.000
Scale	Complet	60	100.000
Enterprise	Complet	120	1.000.000

URL de base

L'URL de base de l'API externe est :

https://api.zenovay.com/api/external/v1

Authentification

Clés API

Authentifiez-vous avec des clés API à l'aide de l'en-tête X-API-Key ou de l'en-tête Authorization: Bearer :

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Ou en utilisant l'authentification Bearer :

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

Les clés API commencent toujours par le préfixe zv_.

Obtenir votre clé API

1. Allez à Paramètres → Sécurité et ouvrez la section Clés API
2. Cliquez sur « Créer une clé API »
3. Nommez votre clé
4. Définissez son périmètre (tous les sites web ou un site web unique)
5. Copiez la clé (affichée une seule fois)

Les clés API nécessitent un plan Pro ou supérieur. Sur un plan gratuit, le bouton de création est désactivé.

Consultez Authentification pour plus de détails.

Démarrage rapide

Lister vos sites web

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

Obtenir un aperçu analytique

Les endpoints analytiques prennent un ID de site web (un UUID — copiez-le depuis la réponse « Lister vos sites web » ci-dessus) et un range optionnel (l'un de 24h, 7d, 30d, 90d, 1y) :

curl "https://api.zenovay.com/api/external/v1/analytics/YOUR_WEBSITE_ID?range=30d" \
  -H "X-API-Key: zv_YOUR_API_KEY"

Vérifier l'utilisation de l'API

curl https://api.zenovay.com/api/external/v1/usage \
  -H "X-API-Key: zv_YOUR_API_KEY"

Format de la requête

En-têtes

En-tête requis (utilisez l'une ou l'autre forme) :

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Envoyez Content-Type: application/json sur les requêtes POST qui contiennent un corps JSON.

En-tête optionnel :

X-Request-ID: your-unique-id (renvoyé pour le débogage)

Paramètres de query

Paramètres communs sur les endpoints analytiques :

Paramètre	Description	Exemple
range	Fenêtre de temps : 24h, 7d, 30d, 90d, 1y (par défaut 7d)	?range=30d
limit	Max de lignes à retourner	?limit=50
offset	Lignes à sauter (pour pagination)	?offset=100

Format de la réponse

Réponse réussie

Les réponses réussies sont enveloppées dans une enveloppe success/data :

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-06-13T00:00:00.000Z"
}

La forme de l'objet data dépend de l'endpoint (par exemple, l'aperçu analytique retourne website, summary et daily_stats). Les endpoints qui paginèrent leurs résultats incluent un objet pagination dans data.

Réponse d'erreur

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded (30 requests/minute). Try again in 12 seconds",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2026-06-13T00:00:00.000Z"
  }
}

Codes de statut HTTP

Code	Signification
200	Succès
201	Créé
400	Requête incorrecte
401	Non autorisé
403	Interdit
404	Introuvable
429	Limite de débit dépassée
500	Erreur serveur

Bibliothèques clientes

Zenovay n'a pas de paquets SDK officiels. À la place, utilisez le script de suivi CDN pour le suivi côté navigateur et les requêtes HTTP standard (fetch, requests, curl, etc.) pour l'accès à l'API côté serveur.

JavaScript (Navigateur)

Ajoutez le script de suivi à votre HTML :

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Utilisez ensuite la fonction globale zenovay :

// Enregistrer les événements
zenovay('track', 'signup', { plan: 'pro' });

JavaScript (Côté serveur)

Utilisez fetch pour appeler l'API externe directement :

const response = await fetch('https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID', {
  headers: {
    'X-API-Key': 'zv_YOUR_API_KEY',
  },
});
const data = await response.json();

Python (avec requests)

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/analytics/WEBSITE_ID',
    headers={'X-API-Key': 'zv_YOUR_API_KEY'}
)
data = response.json()

Cas d'usage courants

Tableaux de bord personnalisés

Créez des tableaux de bord internes :

• Récupérez des métriques agrégées
• Créez des visualisations personnalisées
• Combinez avec d'autres données

Rapports automatisés

Générez des rapports personnalisés :

• Rapports hebdomadaires pour les parties prenantes
• Alertes en temps réel
• Surveillance des seuils

Intégration CRM

Connectez-vous à votre CRM :

• Envoyez les données des visiteurs
• Mettez à jour les dossiers de contact
• Déclenchez des flux de travail

Limites de débit

Les limites de débit de l'API externe sont par clé API, par minute, et dépendent du plan de l'équipe à laquelle appartient la clé :

Plan	Requêtes/Minute	Limite mensuelle
Pro	30	10.000
Scale	60	100.000
Enterprise	120	1.000.000

En-têtes de limite de débit

Les réponses incluent les en-têtes d'utilisation et de limite de débit :

X-RateLimit-Limit: 30
X-Usage-Monthly: 4521
X-Usage-Limit: 10000
X-Usage-Reset: 2026-07-01T00:00:00.000Z

X-RateLimit-Remaining est inclus si disponible. Lorsque vous dépassez une limite, l'API retourne 429 avec un en-tête Retry-After.

Consultez Limites de débit pour les meilleures pratiques.

Meilleures pratiques

Requêtes efficaces

• Ne demandez que les champs nécessaires
• Utilisez les filtres de date
• Paginrez les grands résultats
• Utilisez le cache quand possible

Gestion des erreurs

• Implémentez les retries
• Gérez les limites de débit
• Enregistrez les erreurs
• Supervisez les taux de réussite

Sécurité

• Gardez les clés secrètes
• Utilisez des permissions minimales
• Faites tourner les clés régulièrement
• Auditez l'utilisation des clés

Test

Il n'existe pas de sandbox séparé — testez en production avec une clé dédiée :

1. Allez à Paramètres → Sécurité et ouvrez la section Clés API
2. Créez une clé et donnez-lui un nom reconnaissable (p. ex. « Test »)
3. Limitez-la à un seul site web de test si possible
4. Utilisez l'URL standard de l'API : https://api.zenovay.com/api/external/v1/
5. Supprimez la clé une fois terminé

Support

Obtenir de l'aide

• Documentation de l'API : docs.zenovay.com/api
• E-mail : [email protected]

Journal des modifications

Suivez les modifications du produit et de l'API sur docs.zenovay.com/changelog.

Étapes suivantes

• Authentification et clés API
• Référence de l'API REST
• Limites de débit