Automatiser le suivi des conversions via l’API

L’API Affilae vous permet de créer, d’accepter, de refuser ou d’ajuster vos conversions depuis votre propre système, sans passer par l’interface. C’est la solution quand votre volume de commandes rend la validation manuelle trop lourde.

Cette page décrit les routes utiles et l’ordre dans lequel les appeler. La référence technique complète est publiée sur rest.affilae.com/reference.

Les règles communes à tous les appels

• Chaque requête doit porter l’en-tête Authorization: Bearer {YOUR_TOKEN}
• Les montants des conversions, envoyés ou reçus, sont exprimés en centimes. Ainsi 100 vaut 1,00 €.
• Les dates sont en UTC.

Créer une conversion (Server-to-Server)

En Server-to-Server, vous pouvez envoyer chaque commande par l’API plutôt que par l’URL de postback. Appelez POST /advertiser/conversions.add avec kind = tracking et les identifiants de clic que vous avez conservés.

Exemple :

curl -X POST https://rest.affilae.com/advertiser/conversions.add \
  -H "Authorization: Bearer {YOUR_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"kind": "tracking", "program": "5e336e000000000000000000", "rule": "5e336e000000000000000001",
       "externalId": "CMD-10245", "amount": 8990, "currency": "EUR",
       "cids": ["603ed1800000000000000000"], "ip": "185.179.113.132"}'

Les réponses :

• 201 : la conversion est créée et renvoyée dans conversion.data.
• 202 « No contributions found » : aucun clic ni code promo ne peut être rattaché, aucune conversion n’est créée.
• 400 : la requête est refusée, le message indique pourquoi, par exemple « Conversion already exists » ou « Invalid clickIDs ».

Récupérer l’ID d’une conversion

Avant d’accepter, de refuser ou de modifier une conversion, vous devez connaître son ID interne Affilae. Deux méthodes sont possibles.

1. Lister vos conversions

Appelez GET /advertiser/conversions.list pour obtenir la liste de vos conversions.

Vous pouvez filtrer par :

• statut, avec pending, accepted ou refused ;
• période, avec from et to ;
• identifiant client, avec customerId ;
• identifiant externe, avec externalId.

2. Obtenir les détails d’une conversion

Appelez GET /advertiser/conversions.info si vous connaissez déjà l’identifiant externe ou le client. Cette route renvoie toutes les informations liées à la conversion, dont son ID interne Affilae. Le paramètre program, l’identifiant du programme, est requis.

Accepter ou refuser une conversion

Une fois l’ID connu, vous pouvez automatiser vos décisions de validation. Une conversion verrouillée ne peut plus être acceptée ni refusée.

Accepter

Appelez POST /advertiser/conversions.accept. La conversion est validée et marquée comme acceptée.

Champs requis :

• program, l’identifiant du programme annonceur ;
• id, l’identifiant interne de la conversion.

Refuser

Appelez POST /advertiser/conversions.refuse, par exemple pour un retour produit, une fraude ou une commande de test.

Champs requis :

• program, l’identifiant du programme ;
• id, l’identifiant interne de la conversion ;
• reason, le motif du refus.

Ajuster le montant d’une conversion

En cas de retour produit ou d’ajustement de panier, vous pouvez modifier le montant d’une conversion. Appelez POST /advertiser/conversions.update.

Conditions :

• la conversion ne doit être ni refusée, ni verrouillée, ni incluse dans un paiement ;
• le montant ajusté ne doit pas dépasser le montant initial ;
• le montant n’a pas déjà été modifié.

Champs requis :

• id, l’identifiant interne de la conversion ;
• amount, le nouveau montant en centimes ;
• reason, la raison de l’ajustement, par exemple un retour partiel de panier.

Récapitulatif des routes

Bonnes pratiques

• Conservez la correspondance entre vos commandes, l’externalId, et les ID Affilae, pour éviter les doublons.
• Stockez votre clé API de manière sécurisée et ne la partagez pas.
• L’API impose des limites de débit. Prévoyez leur gestion dans vos appels.
• Conservez les logs de vos appels, ils facilitent le suivi et le support.

Besoin d’aide

Notre équipe support est disponible depuis votre interface annonceur pour toute assistance technique.

Articles liés

• Explication des statuts des conversions
• Ajouter manuellement une conversion
• Valider en masse les conversions de votre programme
• S2S – Server-to-Server
• Postback, Tracking Editeur