Connecter votre e-commerce sur mesure via l'API d'ingestion

Objectif

À la fin de ce guide, votre back-office e-commerce poussera vos commandes et votre catalogue produits dans Metrikia via l'API d'ingestion. Vos ventes seront corrélées à vos campagnes publicitaires : top produits, panier moyen, nouveaux clients et profit sur coûts réels, sans plateforme type Shopify.

Prérequis

• Un compte Metrikia actif avec accès aux paramètres
• Un back-office capable d'envoyer des requêtes HTTP POST en JSON (serveur à serveur)
• Quelques minutes pour générer une clé API

Étape 1 : Créez une clé API avec la permission d'ingestion

1. Dans Metrikia, ouvrez /app/settings puis la section Clés API
2. Cliquez sur Générer une nouvelle clé et nommez-la (par exemple « Ingestion e-commerce »)
3. Cochez la permission E-commerce : Ingestion
4. Copiez la clé affichée (elle commence par mk_live_ et ne s'affiche qu'une seule fois)

Étape 2 : Poussez votre catalogue produits

Envoyez vos produits (grain variante) par lots de 1 à 200 sur :

POST https://api.metrikia.io/api/v1/ecommerce/ingest/products
X-API-Key: mk_live_votre_cle

Corps : un objet JSON avec un tableau products. Champs requis par produit : externalProductId, externalVariantId, title, currency. Les montants (priceAmount, unitCostAmount) sont en centimes entiers. Le coût unitaire alimente le calcul de profit ; un coût modifié manuellement dans Metrikia n'est jamais écrasé par un push.

Étape 3 : Poussez vos commandes

Envoyez vos commandes payées par lots de 1 à 100 sur :

POST https://api.metrikia.io/api/v1/ecommerce/ingest/orders
X-API-Key: mk_live_votre_cle

Corps : un objet JSON avec un tableau orders. Règles du contrat :

• externalOrderId est la clé d'idempotence : renvoyer la même commande met à jour l'existante, jamais de doublon
• email OU phone est requis (au moins un) pour relier la commande à un client
• Tous les montants en centimes entiers, currency en code ISO 3 lettres
• financialStatus : paid, partially_refunded ou refunded ; refundedAmount est le montant remboursé cumulé
• processedAt et updatedAt : dates ISO 8601 complètes
• lines : les lignes de commande (titre, quantité, prix unitaire, identifiants produit) pour le détail produit
• attribution (optionnel) : les UTM de première et dernière visite, stockés comme contexte client

Étape 4 : Lisez le rapport de réponse

Chaque envoi répond 200 avec un statut par élément et un résumé (created, enriched, updated, pending_match, skipped, rejected). Un élément invalide est rejected avec le détail des champs en erreur, sans interrompre le reste du lot.

Résultat attendu

Vos commandes et produits apparaissent sur la page E-commerce (/app/store) quelques instants après l'envoi : revenu net, panier moyen, top produits et profit si les coûts unitaires sont renseignés.

Problèmes fréquents

401 ou 403 sur l'appel

• 401 : la clé est absente, révoquée ou expirée. Vérifiez le header X-API-Key
• 403 : la clé ne porte pas la permission E-commerce : Ingestion. Générez une nouvelle clé avec ce scope

Commande payée via Stripe : statuts enriched et pending_match

Si une commande a été payée via votre intégration Stripe Metrikia, poussez-la toujours avec sa référence (stripePaymentIntentId ou stripeCheckoutSessionId). La vente Stripe existante est alors enrichie (statut enriched) des lignes produits, de la composition et du parcours d'achat, sans jamais modifier ses montants ni créer de doublon. Si le paiement n'est pas encore synchronisé, la commande passe en pending_match : le rattachement est retenté automatiquement toutes les heures pendant 48 heures, rien n'est compté en attendant. Une commande payée via Stripe poussée sans référence serait comptée deux fois.

Étape suivante

Croisez vos ventes avec vos campagnes dans ADS pour mesurer votre vrai ROAS. Une question en cours de route ? Demandez à Diana depuis le menu d'aide.