Guides

Guide d'intégration

Ce guide explique comment intégrer Revclic dans votre plateforme e-commerce. Pour les spécifications complètes des endpoints, consultez la Référence de l'API.

Vue d'ensemble

L'intégration se compose de deux étapes :

  1. Capturer l'ID de redirection lorsqu'un visiteur arrive depuis un lien d'affilié
  2. Signaler la transaction lorsque le visiteur complète un achat

1. Capturer l'ID de redirection

Quand un acheteur clique sur un lien d'affilié, il est redirigé vers votre site web avec un paramètre revclic_rid dans l'URL.

Exemple d'URL entrante :

https://yourstore.com/product/123?revclic_rid=42

Vous devez :

  • Extraire le revclic_rid de l'URL
  • Le stocker dans un cookie ou une session le temps de la visite

Exemple en JavaScript

const urlParams = new URLSearchParams(window.location.search);
const revclicRedirectId = urlParams.get('revclic_rid');

if (revclicRedirectId) {
  document.cookie = `revclic_rid=${revclicRedirectId}; max-age=2592000; path=/`;
}

Exemple en PHP

if (isset($_GET['revclic_rid'])) {
    $_SESSION['revclic_rid'] = $_GET['revclic_rid'];
}

2. Signaler une transaction

Après un achat réussi, envoyez la transaction à Revclic via l'endpoint Create Transaction.

Recette : transaction basique avec redirection

Lorsque vous disposez du revclic_rid depuis le lien d'affilié, passez-le en tant que redirect_id. L'affilié est automatiquement résolu à partir de la redirection.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_id": 1,
    "basket_items": [
      {
        "gtin": "1234567890123",
        "name": "Laptop Stand",
        "price": 49.99,
        "quantity": 2,
        "commission_rate": 10.0
      }
    ]
  }'

Recette : transaction basique sans redirection

Lorsqu'aucune redirection n'est disponible, vous devez fournir l'affiliate_id explicitement.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "affiliate_id": 1,
    "basket_items": [
      {
        "gtin": "1234567890123",
        "name": "Laptop Stand",
        "price": 49.99,
        "quantity": 2,
        "commission_rate": 10.0
      }
    ]
  }'

Champs obligatoires par article :

Champ Description
gtin Code d'identification du produit (EAN ou UPC)
price Prix unitaire
quantity Nombre d'unités
commission_rate Pourcentage de commission pour cet article

Champs optionnels :

Champ Description
redirect_id L'ID de redirection capturé depuis le lien d'affilié. Lorsqu'il est fourni, l'affilié est résolu automatiquement.
affiliate_id L'ID de l'affilié. Obligatoire lorsque redirect_id n'est pas fourni.
name Nom du produit (pour l'affichage)
status Statut initial de l'article : pending (par défaut), accepted ou rejected

Recette : transaction avec articles pré-acceptés

Si votre politique de retour ne s'applique pas (ex. produits numériques, commandes non remboursables), vous pouvez signaler les articles comme déjà accepted à la création. Cela saute la période de validation et la commission est incluse dans la prochaine facture immédiatement.

curl -X POST "https://api.revclic.com/merchants/{merchant_id}/transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "redirect_id": 1,
    "basket_items": [
      {
        "gtin": "9876543210987",
        "name": "Digital License",
        "price": 19.99,
        "quantity": 1,
        "commission_rate": 15.0,
        "status": "accepted"
      }
    ]
  }'

3. Valider ou rejeter des articles

Vous avez 3 mois pour examiner chaque article. Utilisez l'endpoint Update Transaction pour modifier les statuts des articles.

Recette : mettre à jour un seul article

Mettez à jour un article spécifique par son ID :

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" }
    ]
  }'

Recette : rejeter un article retourné

Si le client retourne un article :

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 456, "status": "rejected" }
    ]
  }'

Recette : mettre à jour plusieurs articles à la fois

Vous pouvez mettre à jour plusieurs articles en une seule requête :

curl -X PUT "https://api.revclic.com/merchants/{merchant_id}/transactions/{transaction_id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "basket_items": [
      { "id": 123, "status": "accepted" },
      { "id": 456, "status": "rejected" }
    ]
  }'

Statuts des articles :

Statut Signification
pending En attente de validation (par défaut)
accepted Commission confirmée
rejected Pas de commission (retourné, annulé, invalide)

Règles de validation des articles

  • Chaque article doit inclure son id (retourné lors de la création de la transaction)
  • Vous ne pouvez modifier que le champ status
  • Vous pouvez mettre à jour un, plusieurs ou tous les articles en une seule requête
  • Les articles non examinés dans les 3 mois sont automatiquement acceptés
  • La commission n'est calculée que pour les articles acceptés

Comprendre le champ status

Chaque transaction inclut un champ status en lecture seule qui est calculé automatiquement à partir des statuts de ses articles. Il ne peut pas être défini directement sur la transaction.

Valeur Condition
pending Au moins un article est encore pending
accepted Tous les articles sont accepted, ou un mélange de accepted et rejected
rejected Tous les articles sont rejected

Le status de la transaction est recalculé à chaque modification du statut d'un article.

Comprendre le champ reward

Chaque transaction inclut un champ reward en lecture seule qui reflète le cycle de facturation et de versement de la commission. Il est géré automatiquement par Revclic et ne peut pas être défini manuellement.

Valeur Signification
pending La commission attend la fin de la période de validation et la génération d'une facture
to_be_paid Une facture a été générée et est en attente de paiement par le marchand
paid Le marchand a payé la facture — la commission est maintenant due à l'affilié
complete Le versement à l'affilié a été effectué

La valeur de reward progresse dans cet ordre et ne peut qu'avancer.

Bonnes pratiques

  • Signalez les transactions rapidement — envoyez-les dès que la commande est confirmée
  • Stockez l'ID de suivi de manière fiable — utilisez des sessions côté serveur ou des cookies sécurisés
  • Validez les articles régulièrement — n'attendez pas l'acceptation automatique
  • Utilisez des codes EAN/UPC pertinents — ils aident à identifier les produits dans les rapports

Endpoints associés