Points de terminaison API

Zenovay fournit plusieurs groupes de points de terminaison API pour accéder à vos données analytiques par programmation.

Authentification

Toutes les requêtes API nécessitent une authentification. La méthode dépend de l'API que vous utilisez :

Consultez Authentification pour plus de détails sur la gestion des clés API.

API externe

URL de base : https://api.zenovay.com/api/external/v1

API côté serveur pour accéder aux données analytiques avec authentification par clé API (en-tête X-API-Key).

Points de terminaison disponibles

Chaque point de terminaison dispose d'une page de référence dédiée avec les paramètres, les schémas de réponse, les interfaces TypeScript et les exemples de code en cURL, JavaScript, Python et TypeScript.

Consultez également l'aperçu de l'API externe pour une introduction de haut niveau.

Widgets intégrables

URL de base : https://api.zenovay.com/widgets

Widgets prêts à l'emploi qui ne nécessitent aucune authentification. Utilisez votre code de suivi pour identifier le site web.

Consultez Widgets pour des exemples d'intégration.

Données en temps réel

URL de base : https://api.zenovay.com/e

Points de terminaison JSON publics pour les statistiques en direct. Aucune authentification requise.

Consultez Données en temps réel pour les guides d'intégration.

Limites de débit

Les limites de débit de l'API varient selon le plan :

Les en-têtes de limite de débit sont inclus dans toutes les réponses :

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1642771200

La valeur X-RateLimit-Limit reflète la limite par minute de votre plan (par exemple, 10 pour Gratuit, 30 pour Pro, 60 pour Scale, 120 pour Entreprise).

Consultez Limites de débit pour plus de détails sur la gestion des erreurs de limite de débit.

Codes d'erreur

{
"success": true,
"data": { ... },
"timestamp": "2026-02-07T12:00:00.000Z"
}

{
"success": false,
"error": {
  "message": "The provided API key is missing or invalid",
  "code": "UNAUTHORIZED",
  "timestamp": "2026-02-07T12:00:00.000Z"
}
}

Webhooks

Configurez des webhooks pour recevoir des notifications en temps réel :

Événements disponibles

• visitor.identified - Quand un visiteur est identifié
• visitor.high_value - Quand le score du visiteur atteint 80+
• event.tracked - Quand un événement quelconque est suivi
• goal.completed - Quand un objectif est atteint
• visitor.converted - Quand un visiteur se convertit

Charge utile de webhook

{
"event": "visitor.high_value",
"timestamp": "2025-01-20T15:30:00Z",
"data": {
  "visitor_id": "vis_abc123",
  "score": 92,
  "current_page": "/pricing",
  "time_on_site": 420
}
}

Aperçu de l'API du tableau de bord

Les groupes d'API suivants alimentent le tableau de bord Zenovay. Tous les points de terminaison nécessitent un jeton JWT Bearer dans l'en-tête Authorization. Les réponses utilisent une enveloppe standard :

{ "success": true, "data": { ... }, "timestamp": "..." }

Autorisations basées sur les rôles

Les points de terminaison des paramètres du site web appliquent un accès basé sur les rôles. Les rôles par ordre de privilège :

API Conversations

URL de base : https://api.zenovay.com/api/conversations

Authentification : JWT Bearer requis. L'adhésion à l'équipe est vérifiée pour toutes les requêtes.

Opérations CRUD pour les conversations alimentées par l'IA au sein des équipes. Le paramètre de requête team_id par défaut à l'organisation de l'utilisateur authentifié s'il n'est pas fourni.

Points de terminaison

GET /conversations

Retourne les conversations sans contenu de message pour des raisons de performance.

Paramètres de requête :

• team_id (optionnel) — par défaut à l'organisation de l'utilisateur

{
"success": true,
"data": [
  {
    "id": "uuid",
    "team_id": "uuid",
    "title": "Analytics Q3 review",
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-07T14:30:00Z"
  }
]
}

GET /conversations/:id

Retourne la conversation complète y compris le tableau de messages.

{
"success": true,
"data": {
  "id": "uuid",
  "team_id": "uuid",
  "title": "Analytics Q3 review",
  "messages": [
    { "role": "user", "content": "Show top pages", "timestamp": "2026-02-07T14:30:00Z" },
    { "role": "assistant", "content": "Here are your top pages...", "timestamp": "2026-02-07T14:30:01Z" }
  ],
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:30:01Z"
}
}

POST /conversations

{
"title": "New conversation",
"team_id": "uuid"
}

• title (requis) — chaîne non vide
• team_id (optionnel) — par défaut à l'organisation de l'utilisateur

Réponse : 201 avec la conversation créée (inclut messages: [] vide).

PUT /conversations/:id

{
"title": "Updated title",
"messages": [...]
}

Les deux champs sont optionnels. Accepte les mises à jour partielles.

DELETE /conversations/:id

Réponse : 200 avec { "deleted": true }.

POST /conversations/:id/messages

Ajoute un message à la conversation. Le serveur ajoute un timestamp à chaque message.

{
"role": "user",
"content": "What were last week's top referrers?"
}

• role (requis) — rôle du message (par exemple, "user", "assistant")
• content (requis) — texte du message

Réponse : 201 avec la conversation mise à jour complète incluant tous les messages.

API des paramètres du site web

URL de base : https://api.zenovay.com/api/websites

Authentification : JWT Bearer requis. Chaque point de terminaison applique un rôle minimum.

Gérez la configuration du site web y compris les paramètres généraux, les notifications, les exclusions de trafic, le suivi des revenus, les domaines et les membres de l'équipe. Tous les chemins sont délimités par :websiteId.

Points de terminaison

PUT /:websiteId/general

{
"domain": "example.com",
"name": "My Website",
"timezone": "America/New_York",
"primary_color": "#4F46E5",
"kpi_goal": 10000,
"public_dashboard": true,
"allowed_domains": ["example.com", "www.example.com"]
}

{
"success": true,
"data": {
  "id": "uuid",
  "domain": "example.com",
  "name": "My Website",
  "timezone": "America/New_York",
  "primary_color": "#4F46E5",
  "kpi_goal": 10000,
  "public_dashboard": true,
  "allowed_domains": ["example.com", "www.example.com"],
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/notifications

Retourne les préférences de notification. Si aucun n'a été défini, retourne un objet par défaut avec seulement le website_id.

PUT /:websiteId/notifications

Accepte tous les champs de préférence de notification. Utilise un modèle d'upsert : crée le dossier au premier appel, met à jour aux appels suivants.

GET /:websiteId/exclusions

Retourne à la fois les exclusions d'IP et de chemin dans une seule réponse.

{
"success": true,
"data": {
  "ip_exclusions": [
    { "id": "uuid", "website_id": "uuid", "ip_address": "192.168.1.1", "description": "Office IP", "created_at": "..." }
  ],
  "path_exclusions": [
    { "id": "uuid", "website_id": "uuid", "path_pattern": "/admin/*", "description": "Admin pages", "created_at": "..." }
  ]
}
}

POST /:websiteId/exclusions/ip

{
"ip_address": "192.168.1.1",
"description": "Office IP"
}

• ip_address (requis)
• description (optionnel)

Réponse : 201. Retourne 409 si l'IP est déjà exclue.

POST /:websiteId/exclusions/path

{
"path_pattern": "/admin/*",
"description": "Admin pages"
}

• path_pattern (requis)
• description (optionnel)

Réponse : 201. Retourne 409 si le modèle de chemin est déjà exclu.

PUT /:websiteId/revenue

Nécessite le rôle admin.

{
"revenue_provider": "stripe",
"revenue_currency": "USD"
}

{
"success": true,
"data": {
  "id": "uuid",
  "revenue_provider": "stripe",
  "revenue_currency": "USD",
  "updated_at": "2026-02-07T12:00:00Z"
}
}

GET /:websiteId/domains

{
"success": true,
"data": {
  "primary_domain": "example.com",
  "allowed_domains": ["example.com", "www.example.com"],
  "verification_status": "verified"
}
}

PUT /:websiteId/domains

Nécessite le rôle admin.

{
"domain": "example.com",
"allowed_domains": ["example.com", "www.example.com"]
}

allowed_domains doit être un tableau s'il est fourni.

GET /:websiteId/team-members

Retourne les membres de l'équipe enrichis avec les données de profil utilisateur.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "deactivated_at": null,
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "avatar_url": "https://..."
    }
  }
]
}

POST /:websiteId/team-members

Invitez un utilisateur par e-mail. Nécessite le rôle admin.

{
"email": "[email protected]",
"role": "editor"
}

• email (requis) — doit être un utilisateur Zenovay enregistré
• role (optionnel) — par défaut à "viewer". Doit être l'un des : owner, admin, editor, viewer

Réponse : 201. Retourne 404 si l'e-mail n'est pas trouvé, 409 s'il est déjà membre.

PUT /:websiteId/team-members/:memberId

Mettez à jour le rôle d'un membre. Nécessite le rôle admin.

{
"role": "admin"
}

• role (requis) — doit être l'un des : owner, admin, editor, viewer

DELETE /:websiteId/team-members/:memberId

Supprime un membre de l'équipe (suppression logicielle). Nécessite le rôle admin.

Réponse : 200 avec { "deleted": true }.

API d'intégration

URL de base : https://api.zenovay.com/api/onboarding

Authentification : JWT Bearer requis. Limité à l'utilisateur (aucun contrôle d'équipe ou de rôle).

Suivez la progression de l'intégration utilisateur. Chaque utilisateur a un seul enregistrement d'intégration qui persiste entre les sessions.

Points de terminaison

GET /onboarding/progress

Retourne l'état d'intégration de l'utilisateur. Si aucun dossier n'existe, retourne les valeurs par défaut.

{
"success": true,
"data": {
  "user_id": "uuid",
  "current_step": "add_website",
  "completed": false,
  "data": { "welcomed": true },
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-07T14:00:00Z"
}
}

POST /onboarding/progress

Utilise un modèle d'upsert : crée le dossier au premier appel, met à jour aux appels suivants.

{
"step": "install_tracking",
"data": { "welcomed": true, "website_added": true },
"completed": false
}

• step — enregistré en tant que current_step dans la base de données
• data — objet JSON arbitraire pour stocker l'état spécifique à l'étape
• completed — par défaut à false

API Équipes

URL de base : https://api.zenovay.com/api/teams

Authentification : JWT Bearer requis. L'adhésion à l'équipe est vérifiée (tout membre actif peut accéder).

Points de terminaison de contexte d'équipe en lecture seule pour les autorisations, les statistiques d'utilisation et les listes de membres. Pour les actions de gestion d'équipe (inviter, modifications de rôle, suppression), utilisez les points de terminaison des membres de l'équipe de l'API des paramètres du site web.

Points de terminaison

GET /teams/:id/permissions

Retourne le rôle de l'utilisateur authentifié, le plan de l'équipe, les compteurs d'utilisation actuels et les indicateurs d'autorisation calculés.

{
"success": true,
"data": {
  "team_id": "uuid",
  "role": "admin",
  "plan": "Pro",
  "plan_limits": {
    "maxWebsites": 5,
    "maxTeamMembers": 5,
    "eventsPerMonth": 10000,
    "dataRetentionDays": 730
  },
  "current_usage": {
    "websites": 3,
    "team_members": 5
  },
  "permissions": {
    "can_manage_billing": false,
    "can_manage_team": true,
    "can_edit_settings": true,
    "can_view": true
  }
}
}

GET /teams/:id/usage

Retourne les statistiques d'utilisation pour la période de facturation actuelle (mois à ce jour).

{
"success": true,
"data": {
  "team_id": "uuid",
  "plan": "Pro",
  "period": {
    "start": "2026-02-01T00:00:00.000Z",
    "end": "2026-02-07T12:00:00.000Z"
  },
  "usage": {
    "events": 4521,
    "events_limit": 10000,
    "websites": 3,
    "websites_limit": 10,
    "team_members": 5,
    "team_members_limit": 10
  }
}
}

GET /teams/:id/members

Retourne les membres de l'équipe enrichis avec les données de profil utilisateur.

{
"success": true,
"data": [
  {
    "id": "membership_uuid",
    "user_id": "user_uuid",
    "role": "admin",
    "created_at": "2026-01-15T10:00:00Z",
    "user": {
      "id": "user_uuid",
      "email": "[email protected]",
      "full_name": "Jane Doe",
      "name": "Jane",
      "avatar_url": "https://..."
    }
  }
]
}

API Profil utilisateur

URL de base : https://api.zenovay.com/api/users

Authentification : JWT Bearer requis. Limité à l'utilisateur (profil personnel uniquement).

Gérez le profil et l'adresse e-mail de l'utilisateur authentifié.

Points de terminaison

PUT /users/me/email

Point de terminaison dédié pour les modifications d'e-mail avec détection du fournisseur SSO. Si l'utilisateur s'est inscrit via un fournisseur OAuth (Google, GitHub, etc.), la requête est rejetée avec un message pour mettre à jour l'e-mail via ce fournisseur à la place.

{
"email": "[email protected]"
}

• email (requis) — doit être un e-mail valide, différent de l'e-mail actuel

Réponse : 200 avec l'enregistrement utilisateur mis à jour. Retourne 400 si l'utilisateur est un compte SSO ou si l'e-mail est invalide/inchangé.

Étapes suivantes

• API externe - Analytiques côté serveur avec authentification par clé API
• Widgets - Widgets intégrables prêts à l'emploi
• Données en temps réel - Points de terminaison de données de visiteurs en direct
• Authentification - Gestion des clés API
• Limites de débit - Comprendre les limites