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/postback`.

Si vous avez déjà un compte et une clé API, passez à [Envoyer une conversion](#envoyer-une-conversion).

## 1. Créer un compte marchand

Inscrivez-vous sur [app.refcampaign.com](https://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 :

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

<Callout type="warning" title="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.
</Callout>

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

```http
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.

```bash
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.

```bash
curl -X POST https://app.refcampaign.com/api/v1/conversions/postback \
  -H "Authorization: Bearer $REFCAMPAIGN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ord_001",
    "conversionType": "SALE",
    "sessionId": "test-session-001",
    "amount": 4990,
    "currency": "EUR"
  }'
```

Une réponse réussie renvoie `200` avec les détails de la conversion et de la commission :

```json
{
  "success": true,
  "data": {
    "success": true,
    "conversionId": "cnv_01HABCDEFG...",
    "commissionId": "cmm_01HABCDEFG...",
    "commissionAmount": 499
  },
  "meta": {
    "timestamp": "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`](/fr/docs/api/integration/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](/fr/docs/api/integration/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](/fr/docs/api/reference). 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.