Votre première commission

De la clé d'API à une commission calculée. Quatre appels, une dizaine de minutes, et vous pouvez tout essayer depuis cette documentation sans écrire une ligne de code.

1. Émettez une clé

Dans le CRM, ouvrez votre projet, puis Configurer → Émettre une clé. La clé s'affiche une seule fois : nous n'en gardons qu'une empreinte, et personne chez nous ne peut la relire. Perdue, elle se révoque et se remplace.

pc_live_ff1ec195bcf26cb2f39a4d2e7b8c1a05…

2. Déclarez vos types de revenus

Un type de revenu est un code que vous choisissez : paid_offer, subscription, donation. C'est lui qui décide du barème appliqué, et c'est vous qui le déclarez — la plateforme n'a aucune liste figée, parce qu'elle ne connaît pas votre métier.

Déclarez-les depuis le CRM, dans les réglages du projet, puis associez un barème à chacun dans votre programme.

3. Rattachez un client

À l'inscription d'un nouveau client, si un code de parrainage traîne dans l'URL (?ref=CLAIRE01) ou dans le cookie posé par notre SDK, dites-le-nous :

curl -X POST https://partnercut.fr/api/v1/customers/attribute \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"customerId": "cus_demo_003", "referralCode": "CLAIRE01"}'

Un code inconnu ne fait pas échouer l'appel : la réponse dit attributed: false avec son motif. Un ?ref= périmé traîne des années dans les favoris et les emails ; il ne doit jamais casser une inscription.

4. Remontez un revenu

Au moment où l'argent est réellement acquis chez vous — paiement encaissé, abonnement renouvelé, don validé — déclarez-le :

curl -X POST https://partnercut.fr/api/v1/events \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "pay_9f2c4",
    "customerId": "cus_demo_003",
    "revenueType": "paid_offer",
    "amountCents": 12000,
    "marginCents": 6000
  }'

La réponse contient la commission calculée, son statut, sa date de maturité, et le détail du calcul étape par étape. Ce dernier n'est pas décoratif : c'est ce que vous montrerez à un ambassadeur qui conteste un montant.

Ce qu'il faut retenir avant de mettre en production

Appelez au bon moment. À l'encaissement, pas à la commande. Un revenu déclaré trop tôt devra être annulé.
externalId doit être stable. C'est l'identifiant de la transaction chez vous. Un uuid tiré au moment de l'appel produirait autant de commissions que de rejeux.
Rejouez sans crainte. Le même identifiant deux fois, dix fois, depuis deux processus simultanés : une seule écriture. Votre file d'attente peut reprendre après un incident sans que vous ayez à comparer quoi que ce soit.
Envoyez marginCents si vous le pouvez. Sans lui, le plafond « la commission ne dépasse jamais X % de la marge » reste inopérant, et une promotion agressive peut vous faire commissionner plus que vous ne gagnez.

Le SDK, si vous êtes sous Symfony

Le bundle partnercut/affiliate-bundle fait tout cela pour vous, avec une file d'attente durable qui rejoue les appels quand le réseau revient. Le CRM génère un INTEGRATION.md prérempli pour votre projet — clé, types de revenus, exemples — que vous pouvez suivre pas à pas.