Commençons par ce qu'il y a à écrire, le reste vient ensuite. Quand une commande est finalisée et que vous savez qu'elle vient d'un affilié, votre serveur appelle ceci :

POST /api/<merchantSlug>/track/conversion
Content-Type: application/json

{
  "orderId": "ORD-12345",
  "amount": 99.00,
  "currency": "USD",
  "affiliateCode": "ABC123"
}

C'est tout l'obligatoire. Le merchantSlug de l'URL vous identifie, il n'y a donc aucune clé API à gérer. Remonter les clics est facultatif : sans cela vous perdez les statistiques de clics, et rien d'autre.

Premier point de rupture : la commande comptée deux fois

Les webhooks de paiement rejouent. Un délai dépassé chez le prestataire rejoue. Votre propre logique de reprise rejoue. Si chaque rejeu crée une nouvelle conversion, vous payez deux commissions pour une vente, et vous vous en apercevez au rapprochement de fin de mois.

Afflixo dédoublonne sur votre orderId, à l'intérieur de votre programme. Renvoyer le même orderId retourne la conversion existante avec sa commission, au lieu d'en créer une seconde. Rejouer est donc sans risque, et sans en-tête supplémentaire.

Une seule condition : que l'orderId soit unique chez vous. Votre numéro de commande l'est en général. Si votre boutique réattribue des numéros après une annulation, réglez cela d'abord, sinon le dédoublonnage prendra deux commandes différentes pour la même.

Second point de rupture : l'attribution disparaît

Le code de l'affilié est cherché dans cet ordre :

  1. affiliateCode dans le corps de la requête ;
  2. l'en-tête x-affiliate-code ;
  3. le cookie affiliate_ref, déposé par le lien d'affiliation.

Si aucun des trois n'est présent, la requête est rejetée avec un 400, faute de savoir à qui créditer la vente. C'est volontaire : mieux vaut une erreur visible qu'une attribution silencieusement fausse.

En pratique c'est le troisième qui lâche. Le paiement part vers la page 3-D Secure de la banque et revient ; si le retour arrive sur un autre domaine, ou si l'acheteur termine sur un autre appareil, le cookie n'est plus là.

La méthode fiable consiste à ne pas en dépendre : lisez le code dans le paramètre d'URL dès l'arrivée du visiteur, rangez-le dans votre propre session ou sur la commande, et envoyez-le explicitement en affiliateCode au moment de la confirmation.

À propos de la devise

Le champ currency est conservé, mais rien n'est converti. La commission est calculée directement sur le nombre que vous mettez dans amount. Comme Afflixo règle en dollars américains, convertissez le montant avant de l'envoyer si vous facturez en euros, sinon un montant en euros sera compté comme des dollars.

Règles de commission

Trois réglages couvrent presque tout : pourcentage, montant fixe, et un taux posé sur un affilié précis. Vous définissez une valeur par défaut pour le programme et vous la remplacez au cas par cas ; quand les deux existent, le taux de l'affilié l'emporte. La portée se règle à part : première commande seulement, N premières commandes, ou une fenêtre de temps.

Versements

L'affilié demande, vous validez, vous payez par votre moyen habituel. Afflixo conserve seulement le statut pour qu'une même commission ne soit pas validée deux fois, et ne déplace pas d'argent. Cette limite est assumée.

Ce qui n'existe pas aujourd'hui : commissions à plusieurs niveaux, domaine propre par marchand, versement automatique via PayPal ou Stripe, et règlement dans une devise autre que le dollar. La spécification complète est dans la documentation développeur.