Démarrage

Inscrivez-vous, générez une clé API et suivez votre première conversion en cinq minutes.

Ce guide couvre le chemin le plus court de zéro à une conversion enregistrée : créer un compte, configurer une campagne, générer une clé API, envoyer une requête POST /api/v1/conversions/track.

Si vous avez déjà un compte et une clé API, passez à Envoyer une conversion.

1. Créer un compte marchand

Inscrivez-vous sur app.refcampaign.com. Vous recevrez un email de vérification ; une fois confirmé, le tableau de bord vous propose de créer votre première campagne.

Une campagne est l'unité que les affiliés rejoignent. Chaque campagne a son propre taux de commission, sa fenêtre d'attribution et son URL de tracking. Pour les tests, les valeurs par défaut suffisent.

2. Générer une clé API

Dans le tableau de bord :

Ouvrez Paramètres → Clés API.
Cliquez sur Créer une clé API, donnez-lui un nom (ex. local-dev).
Copiez le token. Il n'est affiché qu'une seule fois — stockez-le dans un gestionnaire de secrets ou un .env local.

Stockez le token avant de fermer la fenêtre

Nous ne conservons pas le token en clair. Si vous le perdez, il faut révoquer la clé et en créer une nouvelle.

Le token est un JWT Bearer signé par RefCampaign. Vous l'envoyez sur chaque requête API ainsi :

Authorization: Bearer <VOTRE_TOKEN>

3. Trouver un clic à attribuer

Une conversion est toujours liée à un clic précédent. Sur du trafic réel, le SDK ou l'URL de tracking capture les clics automatiquement. Pour ce guide rapide, on crée d'abord un clic synthétique.

curl -X POST https://app.refcampaign.com/api/v1/track/click \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_url": "https://votreboutique.com/?ref=affiliate-1",
    "session_id": "test-session-001"
  }'

La réponse contient l'identifiant du clic ; on n'en a pas besoin directement, mais le session_id qu'on a passé (test-session-001) sert à lier la conversion future à ce clic.

4. Envoyer une conversion

Enregistrez maintenant une conversion contre cette session.

curl -X POST https://app.refcampaign.com/api/v1/conversions/track \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "test-session-001",
    "amount": 49.90,
    "currency": "EUR"
  }'

Une réponse réussie renvoie 201 Created avec l'enregistrement de la conversion :

{
  "success": true,
  "data": {
    "id": "cnv_01HABCDEFG...",
    "amount": 49.90,
    "currency": "EUR",
    "status": "PENDING",
    "createdAt": "2026-05-03T10:23:11.000Z"
  }
}

La conversion arrive en statut PENDING. Le marchand l'approuve (ou configure des règles d'auto-approbation), à ce moment une commission est générée pour l'affilié.

5. Et après

Utiliser le SDK plutôt que curl : le paquet @refcampaign/sdk gère click + identify automatiquement depuis un frontend JS.
Postback de serveur à serveur : si vous capturez déjà les conversions dans votre propre backend (webhooks Stripe, PayPal, etc.), voir intégration postback.
Parcourir l'API complète : chaque endpoint, schéma de requête et forme de réponse est dans la référence API. Testez les requêtes en direct avec le playground.

Pièges courants

401 Unauthorized — le header Authorization est manquant ou mal formé. Vérifiez Bearer (avec l'espace) et le token complet.
400 VALIDATION_FAILED sur currency — la devise doit être un code ISO 4217 à 3 lettres (EUR, USD, GBP). Les minuscules fonctionnent ; les symboles et noms complets non.
Conversion non attribuée — soit sessionId ne matche pas un clic récent, soit le clic est plus ancien que la fenêtre d'attribution de la campagne. Passez customerEmailHash (SHA-256 hex de l'email lowercased) en fallback.