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 Revclic
2. Signaler la transaction lorsque le visiteur complète un achat

1. Capturer l'ID de redirection

Quand un acheteur clique depuis Revclic, 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 Revclic, passez-le en tant que redirect_id.

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

redirect_id est optionnel — si aucune redirection n'est disponible (ex. une vente hors ligne ou par téléphone), omettez-le simplement.

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

Champs obligatoires par article :

Champs optionnels :

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 :

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.

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.

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

• Create Transaction — signaler un nouvel achat
• Update Transaction — valider ou rejeter des articles
• List Transactions — voir toutes les transactions
• List Invoices — voir les factures générées