API REST Metrikia : automatisez tout

L'API Metrikia vous donne un accès programmatique complet à vos données publicitaires et CRM. Que vous souhaitiez automatiser vos reportings hebdomadaires, connecter un CRM non supporté nativement, ou alimenter votre propre BI, l'API est votre porte d'entrée.

Base URL

L'API est accessible à l'adresse :

https://api.metrikia.io/api/v1/

La documentation interactive (OpenAPI/Swagger) est disponible à :

https://api.metrikia.io/api/v1/docs

Authentification

Toutes les requêtes doivent inclure un header Authorization :

Authorization: Bearer VOTRE_CLE_API

Créez et gérez vos clés API depuis Paramètres > API Keys. Vous pouvez créer des clés en lecture seule (recommandé pour les dashboards et reportings) ou en lecture-écriture (pour la création de leads et deals).

> Astuce pro : Créez une clé API par application ou service. Si une clé est compromise, vous pouvez la révoquer sans impacter les autres intégrations.

Format des échanges

Requêtes : JSON (Content-Type: application/json)
Réponses : JSON-LD (compatible JSON standard)
Pagination : cursor-based (paramètres page et itemsPerPage)
Erreurs : format Problem Details (RFC 7807)
Versioning : préfixe /api/v1/, les changements breaking sont versionnés

Endpoints principaux

Leads

GET /api/v1/leads : Liste paginée de vos leads CRM

Paramètres de query :

status : filtre par statut (new, contacted, qualified, proposal, won, lost)
source : filtre par source (meta, google, tiktok, organic, referral)
page : numéro de page (défaut: 1)
itemsPerPage : éléments par page (défaut: 30, max: 100)
order[createdAt] : tri par date (asc ou desc)

POST /api/v1/leads : Créer un lead

Body :

firstName (requis) : Prénom
lastName (requis) : Nom
email : Email (utilisé pour le matching et la déduplication)
phone : Téléphone (format E.164 recommandé)
source : Source publicitaire (meta, google, tiktok, etc.)
notes : Notes libres

PATCH /api/v1/leads/{id} : Mise à jour partielle

Deals

GET /api/v1/deals : Liste des deals avec pagination et filtres par statut

POST /api/v1/deals : Créer un deal associé à un lead

Body :

leadId (requis) : ID du lead associé
title (requis) : Titre du deal
amount : Montant (en centimes)
status : open, won, lost

Campagnes

GET /api/v1/campaigns : Liste des campagnes synchronisées depuis les plateformes ADS. Lecture seule (les campagnes sont créées via les plateformes publicitaires).

Performance

GET /api/v1/performance : Métriques agrégées

Paramètres :

dateFrom : Date de début (format YYYY-MM-DD)
dateTo : Date de fin
platform : meta, google, tiktok ou all
groupBy : day, week, month

Retourne : dépenses, impressions, clics, leads, revenue, CPL, CPA, ROAS.

Cas d'usage concrets

1. Reporting automatisé hebdomadaire

Créez un script qui récupère les données chaque lundi matin et les envoie par email ou Slack :

Appelez GET /api/v1/performance?dateFrom=LUNDI_DERNIER&dateTo=DIMANCHE&platform=all&groupBy=day
Appelez GET /api/v1/leads?status=won&order[createdAt]=desc&itemsPerPage=100 pour les nouveaux clients
Générez votre rapport (PDF, email, Slack, Google Sheets...)
Programmez l'exécution via cron, Zapier, Make ou n8n

2. Sync CRM personnalisé

Si votre CRM n'est pas directement supporté par Metrikia :

Configurez un webhook sortant depuis votre CRM (événements "nouveau lead" et "deal gagné")
Créez un middleware (Zapier, Make, n8n ou un script) qui transforme le payload
Appelez POST /api/v1/leads pour créer le lead dans Metrikia avec les champs source
Le lead est automatiquement attribué et les métriques mises à jour

3. Dashboard BI personnalisé

Intégrez les données Metrikia dans Power BI, Looker ou Google Data Studio :

Créez une clé API en lecture seule
Utilisez GET /api/v1/performance pour alimenter vos graphiques
Rafraîchissez les données à intervalle régulier (1x/heure recommandé)
Combinez avec vos autres sources de données pour un dashboard unifié

4. Alertes personnalisées

Créez un script qui vérifie quotidiennement vos KPIs :

Appelez GET /api/v1/performance pour les métriques du jour
Comparez le ROAS à votre seuil de rentabilité
Si ROAS < seuil, envoyez une alerte Slack/email
Ajoutez des vérifications pour le CPL, le volume de leads, etc.

Rate Limiting

Plan	Limite	Burst
Starter	100 requêtes/minute	150
Business	500 requêtes/minute	750
Enterprise	2 000 requêtes/minute	3 000

En cas de dépassement, l'API retourne un code 429 avec un header Retry-After indiquant le nombre de secondes à attendre.

Bonnes pratiques

Cachez les résultats : Les données de performance ne changent qu'après chaque sync (toutes les heures), inutile de les requêter toutes les secondes
Utilisez la pagination : Ne récupérez pas tous les leads d'un coup, utilisez itemsPerPage=30 et paginez
Gérez les erreurs : Implémentez un retry avec backoff exponentiel (1s, 2s, 4s, 8s, max 60s)
Clés séparées : Une clé par application/service, révoquez indépendamment
Lecture seule quand possible : Réduisez la surface d'attaque de vos intégrations
Webhooks > Polling : Pour les événements temps réel, utilisez les webhooks plutôt que le polling de l'API

Intégration API avancée