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. Gardez **API : lecture** sélectionné et ajoutez **API : écriture** pour envoyer des conversions, puis cliquez sur **Générer votre première clé** (ou **Générer une nouvelle clé** si une clé existe déjà).
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 une clé Bearer opaque préfixée `rc_live_` (ou `rc_test_` en mode test). Vous l'envoyez sur chaque requête API ainsi :

```http
Authorization: Bearer <VOTRE_TOKEN>
```

## 3. Choisir un signal d'attribution

Une conversion doit contenir un signal d'attribution. En production, un lien de tracking transporte un paramètre public `ref` vers le site marchand. Le SDK navigateur crée une session uniquement après l'accord de la CMP du marchand pour l'attribution. Pour ce guide API rapide, utilisez un code affilié déjà connu par votre serveur et transmettez-le directement via `affiliateCode`.

## 4. Envoyer une conversion

Enregistrez maintenant une conversion contre ce code affilié.

```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",
    "affiliateCode": "affiliate-1",
    "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) capture une recommandation après l'accord de votre CMP pour l'attribution et peut identifier une session consentie 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 `affiliateCode` est incorrect, 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.