PartnerCut · Documentation API v1 · stable Ouvrir le CRM →

POST /api/v1/events

Remonter un revenu

Déclare une transaction. La plateforme cherche l'ambassadeur qui a amené ce client, applique le barème du programme, et enregistre la commission.

C'est l'appel central de l'intégration. Appelez-le au moment où l'argent est réellement acquis chez vous — paiement encaissé, abonnement renouvelé, don validé — et non à la commande.

Portée requise : events:write. écrit dans votre projet

Le corps de la requête

ChampTypeCe qu'il fait
externalId
obligatoire 		string L'identifiant de la transaction CHEZ VOUS : identifiant de paiement, de commande, de don. C'est lui qui rend l'appel rejouable.
⚠ N'y mettez jamais un uuid tiré au moment de l'appel : il changerait à chaque tentative, et vous obtiendriez autant de commissions que de rejeux.
customerId
obligatoire 		string L'identifiant du client chez vous. Opaque pour nous : ni email, ni nom, ni rien qui vous engage — un identifiant technique suffit.
revenueType
obligatoire 		string Le code d'un type de revenu que vous avez déclaré sur votre projet (« paid_offer », « subscription », « donation »…). C'est lui qui décide du barème appliqué.
⚠ Un code inconnu n'échoue pas : l'événement est enregistré et la réponse le signale dans « warnings ». Un revenu n'est jamais perdu.
amountCents
obligatoire 		integer La base commissionnable, en CENTIMES et en entier. C'est votre application qui la calcule : nous ne savons pas ce qui est commissionnable chez vous — frais de port compris ou non, TVA incluse ou non, remise déduite ou non.
⚠ Négative pour un remboursement. Jamais de nombre à virgule : 12,34 € s'écrit 1234.
marginCents integer La marge réellement dégagée sur cette transaction. Sert au plafond « la commission ne dépasse jamais X % de la marge ».
⚠ Absente n'est pas nulle : sans elle, ce plafond reste inopérant et la commission peut dépasser ce que vous gagnez.
currency string Code ISO 4217. Par défaut, la devise du projet.
occurredAt string Date de la transaction, ISO 8601. Par défaut, maintenant. C'est elle — et non la date d'appel — qui décide de la période de facturation.
reversesExternalId string Pour un remboursement : la transaction que celui-ci annule. La commission correspondante donne alors lieu à une écriture négative.
rateOverrideBp integer Un taux imposé pour CETTE transaction, en points de base (500 = 5 %). N'est honoré que si le programme l'autorise, et reste plafonné par lui.
raw object Votre charge utile d'origine, archivée telle quelle. Utile le jour d'un litige.

Exemples

cURL

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

PHP

$response = $client->request('POST', 'https://partnercut.fr/api/v1/events', [
    'headers' => ['Authorization' => 'Bearer '.$key],
    'json' => [
        'externalId' => 'pay_9f2c4',
        'customerId' => 'cus_demo_003',
        'revenueType' => 'paid_offer',
        'amountCents' => 12000,
        'marginCents' => 6000,
        'currency' => 'EUR',
    ],
]);

// 201 : première écriture. 200 : rejeu, la même commission est rendue.
$created = 201 === $response->getStatusCode();
$data = $response->toArray()['data'];

JavaScript

const response = await fetch('https://partnercut.fr/api/v1/events', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${key}`,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        "externalId": "pay_9f2c4",
        "customerId": "cus_demo_003",
        "revenueType": "paid_offer",
        "amountCents": 12000,
        "marginCents": 6000,
        "currency": "EUR"
    }),
})

// 201 : première écriture. 200 : rejeu, la même commission est rendue.
const created = response.status === 201
const { data } = await response.json()

Les réponses

CodeQuand
201 Première écriture : l'événement vient d'être enregistré.
200 Rejeu : cet identifiant existait déjà. La MÊME commission est rendue, pas une nouvelle.
422 Corps invalide. Le détail nomme le champ fautif.
403 La clé n'a pas la portée « events:write ».

Ce qu'il faut savoir

Rejouez autant que vous voulez. Le même externalId deux fois, dix fois, depuis deux processus simultanés : une seule écriture. C'est la base de données qui le garantit, pas une vérification préalable.
Un revenu n'est jamais perdu. Client non rattaché, rente échue, aucune règle applicable : l'événement est enregistré avec sa raison, et « warnings » la donne. Vous n'avez rien à rejouer plus tard.
Le montant de la commission est FIGÉ à sa création. Changer le barème demain ne rétroagit pas — ce qui protège autant vous que l'ambassadeur.

Essayer pour de vrai